# MCP Maker

> Build enterprise-ready TypeScript (default) or Python MCP servers that wrap real APIs for AI agents. Researches API/SDK options, defaults to read-only v1, requires security annotations/tests/timeouts, scopes a small tool surface, designs md/json outputs, scaffolds clients/tools like mcp-bitbucket and mcp-confluence, then runs mandatory audit/QC (mcp-maker qc) before shipping. Use when the user asks to create, design, scaffold, implement, audit, or QC an MCP server, MCP tools, Model Context Protocol integration, or wrap a SaaS/API for agents.

- Skill: `rexysaragih/mcp-maker` (Agent Skill, multi-file: 31 files)
- Install (CLI): `npx skillmds@latest add rexysaragih/mcp-maker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rexysaragih/mcp-maker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: RexySaragih (https://skillmd.com/u/rexysaragih)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/rexysaragih/mcp-maker

---


# MCP Maker — Enterprise MCP Server Builder

Turn a user request (“I need an MCP for X”) into a **small, secure, tested MCP
server** on top of a real API. MCP does not replace APIs — it exposes
discoverable tools with schemas so models can call them safely.

**Core principles**

1. **Research before code** — confirm API/SDK coverage; recommend if unsure.
2. **Read-only v1 by default** — writes/deletes only after explicit user ask.
3. **TypeScript by default** — switch language only when the ecosystem wins.
4. **Narrow tool surface** — few high-value tools beat a kitchen-sink catalog.
5. **Secure by construction** — secrets in mcp.json `env`, annotations, sanitized I/O.
6. **Tested before done** — handler tests + connection smoke + build.
7. **QC before ship** — `mcp-maker qc` + agent audit; never ship on FAIL.
8. **Agent-shaped I/O** — parameters agents can fill; md or compact json.
9. **Reference architecture** — `clients/` + `tools/` + thin `index.ts`.

### Reference loading

| When | Read |
|------|------|
| **Always** | [agent-constraints.md](references/agent-constraints.md), [workflow.md](references/workflow.md), [security.md](references/security.md), [auth.md](references/auth.md) |
| **Before tools** | [research-and-recommend.md](references/research-and-recommend.md), [tool-spec-template.md](references/tool-spec-template.md), [tool-design.md](references/tool-design.md), [tool-annotations.md](references/tool-annotations.md) |
| **Transport** | [transports.md](references/transports.md) |
| **Language** | [language-choice.md](references/language-choice.md) |
| **Output** | [output-format.md](references/output-format.md) |
| **Scaffold** | [architecture-pattern.md](references/architecture-pattern.md), [project-scaffold.md](references/project-scaffold.md), [schema-sync.md](references/schema-sync.md) |
| **Hardening** | [resilience.md](references/resilience.md), [testing.md](references/testing.md), [observability.md](references/observability.md), [ci-and-release.md](references/ci-and-release.md) |
| **After build (mandatory)** | [audit-pipeline.md](references/audit-pipeline.md), [qc-checklist.md](references/qc-checklist.md) |
| **Examples** | [worked-example.md](references/worked-example.md) |
| **Avoid** | [anti-patterns.md](references/anti-patterns.md) |

Templates: [assets/templates/](assets/templates/).  
Evals: [evals/evals.json](evals/evals.json).

**Install / CLI:**

```bash
./install.sh
mcp-maker doctor
mcp-maker qc --project-dir /path/to/mcp-<service>
```

---

## Quiet defaults (do not interrogate)

Proceed with defaults; state them in one short line. **Exception:** never add
write/destructive tools without an explicit user request (or confirmation).

| Field | Default when unspecified |
|-------|--------------------------|
| Language | TypeScript (current `@modelcontextprotocol/sdk` + `zod`) |
| Transport | stdio |
| Capabilities | tools only (no resources/prompts) |
| v1 posture | **read-only** (search/list/read) |
| Package style | ESM, `bin`, `dist/`, lockfile, `.gitignore` |
| Auth | secrets in **user mcp.json `env`** (server uses `requireEnv`); never project `.env` |
| Output | markdown for reads; compact text for lists/search |
| Scope | 3–12 tools for the stated workflow |
| Location | `mcp-<service>/` with `TOOL_SPEC.md` first |
| Verification | unit tests + build + **`mcp-maker qc`** + agent audit |

Ask when: auth model ambiguous, user wants writes/deletes, OAuth vs PAT trade-off,
research finds no viable API, or remote HTTP transport is requested.

---

## Default agent loop

Copy and track:

```text
Task Progress:
- [ ] One-sentence agent job + quiet defaults stated
- [ ] Research API/SDK/existing MCP (research-and-recommend.md)
- [ ] Language + transport + auth model decided
- [ ] If uncertain → recommend (best vs easiest) and wait
- [ ] Write TOOL_SPEC.md (tool-spec-template.md) — required before tools code
- [ ] Scope v1 tools (read-only unless user asked writes)
- [ ] Annotations + output format per tool
- [ ] Scaffold package (gitignore, lockfile, clients, tools, tests, smoke)
- [ ] Implement: base client (timeout/sanitize) → reads → writes last
- [ ] Schema sync checklist; stderr tool logging
- [ ] npm test + npm run build (+ test:connections if env available)
- [ ] README: env, scopes, tools, annotations summary, risks
- [ ] mcp-maker qc --project-dir <repo>  (audit-pipeline.md)
- [ ] If FAIL → fix → re-qc until not FAIL
- [ ] Agent audit checklist (qc-checklist.md)
- [ ] Report qc verdict + qc-report.json; deferred v2 + residual risks
- [ ] mcp.json / install guidance ONLY if PASS (or WARN + user accepts)
```

### Step 1 — Name the job

Rewrite as agent jobs, not API routes. One server = one domain (or one auth
plane pair like Jira+Confluence). Prefer **reuse** existing MCP when it fits.

### Step 2 — Research & recommend

Follow [research-and-recommend.md](references/research-and-recommend.md) and
[security.md](references/security.md). Map jobs → endpoints; note scopes, rate
limits, injection surface. If confidence is low → recommendation gate, no code.

### Step 3 — TOOL_SPEC.md (mandatory)

Copy [tool-spec-template.md](references/tool-spec-template.md) into the target
repo. Fill tools, annotations, auth, non-goals. **No `src/tools` until this exists.**

### Step 4 — Language & transport

TS default ([language-choice.md](references/language-choice.md)).  
stdio default ([transports.md](references/transports.md)).  
Check current MCP SDK docs for annotations support — do not blindly pin ancient versions.

### Step 5 — Design tools

- Verbs: `read_*` / `search_*` / `list_*` / `create_*` / `update_*` / `delete_*`
- Every tool: annotations ([tool-annotations.md](references/tool-annotations.md))
- Params: URL/env fallbacks OK; caps; include flags default false
- Output: [output-format.md](references/output-format.md)
- Zod source of truth; sync `inputSchema` ([schema-sync.md](references/schema-sync.md))

### Step 6 — Scaffold & implement

```text
mcp-<service>/
  TOOL_SPEC.md
  package.json  README.md  .gitignore  .env.example
  tsconfig.json  tsconfig.test.json
  src/index.ts
  src/types/
  src/clients/base-client.ts    # timeout, sanitize, headers
  src/clients/<domain>-client.ts
  src/tools/<domain>.ts         # zod + tool + annotations + handler
  src/scripts/test-connections.ts
  test/helpers/mock-fetch.ts
  test/*.test.ts
  .github/workflows/ci.yml      # when git repo
```

Use [architecture-pattern.md](references/architecture-pattern.md),
[project-scaffold.md](references/project-scaffold.md),
[resilience.md](references/resilience.md),
[testing.md](references/testing.md),
[observability.md](references/observability.md).

Templates under `assets/templates/` when helpful.

### Step 7 — Verify (tests/build)

- [ ] `npm test` + `npm run build` pass
- [ ] Smoke script present; secrets never printed
- [ ] README: env, scopes, tool table, risks (mcp.json draft OK)

### Step 8 — Audit & QC (mandatory gate)

Follow [audit-pipeline.md](references/audit-pipeline.md) and
[qc-checklist.md](references/qc-checklist.md):

```bash
mcp-maker qc --project-dir /path/to/mcp-<service>
```

| Verdict | Action |
|---------|--------|
| `FAIL` | Fix findings; re-run qc; **do not ship** |
| `WARN` | Fix or justify each warning; finish agent checklist |
| `PASS` | Finish agent checklist; then mcp.json guidance |

Agent checklist covers TOOL_SPEC fidelity, annotation honesty, least privilege,
output shaping, and residual risks. **Never claim done on FAIL.**

---

## Mental model

```text
[ LLM / Agent ]
       │  MCP (discover + call + annotations)
       ▼
[ MCP Server ]  ← thin, least-privilege capability surface
       │  HTTP/SDK (timeouts, sanitized errors)
       ▼
[ Real APIs / systems ]
```

Skills = how work is done. MCP = what tools exist. This skill builds the MCP
layer — honest about the API, safe under agent control.

---

## Anti-patterns (summary)

| Anti-pattern | Do instead |
|--------------|------------|
| Kitchen-sink API wrap | 3–12 tools for stated jobs |
| Writes in v1 without ask | Read-only v1; confirm writes |
| Skip TOOL_SPEC / tests | Spec → code → tests mandatory |
| No annotations | Set all four hints honestly |
| Raw API errors / JSON dumps | Sanitize; shape md/compact |
| Admin PAT for read MCP | Least-privilege scopes |
| `console.log` on stdout | `console.error` only |
| Ancient SDK pin blindly | Check current SDK + annotation support |
| Skip qc / ship on FAIL | `mcp-maker qc` + fix loop mandatory |
| Project `.env` / `dotenv` | Secrets only in user mcp.json `env` |

Full list: [anti-patterns.md](references/anti-patterns.md).

---

## Success criteria

- [ ] Research + language + auth + transport stated
- [ ] Recommendation delivered when ambiguous
- [ ] `TOOL_SPEC.md` complete and matched by code
- [ ] Read-only v1 unless writes explicitly requested
- [ ] Annotations, timeouts, sanitized errors, schema sync
- [ ] Tests + build green; smoke script documented
- [ ] `mcp-maker qc` is `PASS` or accepted `WARN` (never ship on `FAIL`)
- [ ] Agent audit checklist completed ([qc-checklist.md](references/qc-checklist.md))
- [ ] User given `qc-report.json` path + residual risks
- [ ] mcp.json guidance only after QC gate
- [ ] No secrets in repo; no project `.env` / `dotenv`; auth via mcp.json `env`
- [ ] Deps verified/pinned