mcp-forge — turn any API into a Claude-callable tool surface

When to use this skill

Trigger when the user wants Claude (or any MCP client) to be able to invoke a remote API as native tools. Strong signals:

• Mentions of "MCP server", "MCP for X", "wrap API as MCP", "Model Context Protocol"
• A pasted OpenAPI/Swagger spec, Postman collection, or list of REST endpoints
• A documentation URL where you can read the API surface (Stripe, GitHub, internal services)

Do not trigger for: pure client-side API calls, simple fetch wrappers, or when an existing first-party MCP already covers the surface (check the MCP registry first — see step 1 below).

The output contract

A working MCP server, in a single directory, that:

1. Builds clean — npm install && npm run build succeeds with zero warnings.
2. Connects — registers without error against claude mcp add and answers tools/list.
3. Is safe — secrets read from env, never logged; rate limits and 5xx retried with exponential backoff and jitter; PII redacted from error messages.
4. Is typed — every tool's inputSchema is a real Zod schema, not a hand-written JSON blob. Response types are inferred.
5. Ships with an install path — README has copy-paste install for Claude Code, plus the bare claude mcp add command.

Workflow

1 — Reconnaissance (do not skip)

Before writing code:

• Ask the user for the API source. Accept: OpenAPI URL/file, docs URL, raw endpoint list, or a Postman export.
• Search the MCP registry for an existing server (mcp__mcp-registry__search_mcp_registry if available, otherwise WebSearch "<service> MCP server github"). If a maintained one exists, say so and ask before forking. Don't reinvent.
• Identify the auth model: API key in header, OAuth 2.0, basic auth, signed requests. Each shapes the code differently.

2 — Surface design

Pick the useful subset of endpoints, not all of them. Heuristic:

• Include: any GET that returns data the user would want Claude to read, any POST/PATCH that performs the headline action of the API.
• Exclude: admin endpoints, billing endpoints, bulk-delete endpoints — unless the user explicitly asked.
• Name tools in the form <verb>_<noun> (list_customers, create_invoice). Never expose the HTTP verb or URL — those are implementation details.

For each tool, decide:

• Required vs optional inputs
• Whether the response needs pagination handling baked in
• Whether the response needs trimming (e.g. strip 80% of fields the model doesn't need to reason over)

3 — Scaffold

Generate this layout:

<service>-mcp/
  package.json
  tsconfig.json
  src/
    index.ts          # entry — wires StdioServerTransport
    server.ts         # registers tools, holds the client
    client.ts         # the typed HTTP client (auth, retries, error mapping)
    tools/
      <one file per tool>.ts
    schemas/
      <zod schemas grouped by resource>.ts
    errors.ts         # MCPError subclasses
  README.md
  .env.example

Use @modelcontextprotocol/sdk for transport and tool registration. Use zod for schemas. Use undici (Node 20+) or native fetch for HTTP — never axios unless the API requires its interceptor model.

4 — Auth, retries, redaction

• Auth: read from process.env.<SERVICE>_API_KEY (or OAuth equivalent). If env is missing, fail at startup with a clear message naming the variable.
• Retries: 3 attempts on 5xx and 429. Exponential backoff: 500ms, 1500ms, 4500ms, plus 0–500ms jitter. Respect Retry-After if present.
• Redaction: build an errorMap that strips tokens, emails, and any header values from error responses before they bubble up as MCPError messages.
• Timeouts: 30s default per request, configurable via <SERVICE>_TIMEOUT_MS.

5 — Test the loop

Before declaring done:

1. npm run build clean.
2. node dist/index.js starts without crash.
3. Add the server locally: claude mcp add <name> -- node /full/path/dist/index.js
4. In a Claude session, ask: "list tools from <name>" — verify the tool list matches the design.
5. Invoke one read tool and one write tool end-to-end against a test account.

6 — README

Must contain:

• One-paragraph summary of what the server exposes
• Required env vars (with where to get the API key)
• Install block (copy-paste) for Claude Code
• The full tool list with one-line descriptions
• Known limitations (rate limits, unsupported endpoints, sandbox vs prod)

Patterns and anti-patterns

✅ Do:

• Pin the SDK version in package.json — MCP is evolving fast.
• Stream paginated results; expose a cursor input rather than auto-following all pages (the model decides when to stop).
• Return concise tool responses. Trim arrays to the first N items by default and add a limit input.
• Catch and re-throw with MCPError so the client gets actionable messages.

❌ Don't:

• Don't expose every endpoint. The model gets confused when a tool list has 80 entries.
• Don't put API keys in inputSchema. They live in env, not in tool arguments.
• Don't console.log the full response — it pollutes the JSON-RPC stream over stdio and breaks the transport.
• Don't catch errors silently. A swallowed 401 looks like a successful empty response to the model.

Example invocation

User: "Wrap the Linear API as an MCP server so I can use it from Claude Code."

1. Confirm the auth model (Linear uses an API key) and the priority surface (issues, projects, comments).
2. Scaffold linear-mcp/ with tools: list_issues, get_issue, create_issue, update_issue, list_projects, comment_on_issue.
3. Wire the client with LINEAR_API_KEY env, GraphQL POST against api.linear.app/graphql, error mapping for the standard Linear error envelope.
4. Generate Zod schemas from the issue, project, comment types.
5. Verify locally, write the README, hand the user the claude mcp add linear -- node ... command.

See also

• api-architect skill — for when you need to design the API before wrapping it
• security-sentinel — sweep the generated server for leaked secrets and unsafe defaults
• doc-craft — polish the README before sharing