mcp-server-builder · diff

v1.2.0 to v1.3.0

85 added, 59 removed. Audit A to A.

---

name: mcp-server-builder

description: >

- Build MCP (Model Context Protocol) servers with tool definitions, resource providers, prompt

- templates, and transports. Use when exposing APIs to AI agents, building tool servers,

- converting OpenAPI to MCP, or creating MCP integrations.

+ Builds MCP servers: OpenAPI-to-tool conversion, tool and schema linting, TypeScript or

+ Python scaffolds, transports. Use when exposing an API to AI agents, building a tool

+ server, or reviewing MCP tool definitions.

license: MIT + Commons Clause

metadata:

- version: 1.2.0

+ version: 1.3.0

author: borghei

category: engineering

domain: ai-integration

tier: POWERFUL

- updated: 2026-06-29

+ updated: 2026-11-08

frameworks: mcp-sdk, typescript, python, openapi

tags:

- mcp

- ai-integration

- tool-definitions

- api

- ai-agents

---

# MCP Server Builder

- **Tier:** POWERFUL

- **Category:** Engineering / AI Integration

- **Maintainer:** Claude Skills Team

+ The agent designs and ships MCP (Model Context Protocol) servers whose tools an agent picks correctly and calls safely: verb_noun names, descriptions that say when to use the tool and what it returns, typed inputs, paginated lists and gated destructive actions. Schema quality is the main lever: the model chooses tools from names and descriptions alone.

- ## Overview

+ ## When to Use

- Design and ship production-ready MCP (Model Context Protocol) servers from API contracts. Covers tool definition best practices, resource providers, prompt templates, OpenAPI-to-MCP conversion, TypeScript and Python server implementations, transport selection (stdio, SSE, StreamableHTTP), authentication patterns, testing strategies, and deployment configurations. Treats schema quality and tool discoverability as first-class concerns.

+ - Exposing an internal REST API to Claude, Cursor or another MCP client.

+ - Converting an OpenAPI spec into MCP tools, then fixing what the conversion gets wrong.

+ - Replacing brittle browser automation with typed tool interfaces.

+ - Reviewing an existing server's tool definitions before release.

- ## Keywords

+ ## Clarify First

- MCP, Model Context Protocol, MCP server, tool definition, resource provider, prompt template, stdio transport, SSE transport, OpenAPI to MCP, AI tool server, Claude tools

+ Before building the server, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

- ## Core Capabilities

+ - **Source contract:** an OpenAPI spec, an existing API, or tools designed from scratch.

+ - **Language:** TypeScript (`@modelcontextprotocol/sdk`) or Python (`mcp`).

+ - **Transport:** stdio for local tools, Streamable HTTP for remote or shared servers (HTTP+SSE only for legacy clients).

- - **Tool design & schema quality** — verb-noun naming, description engineering, typed input schemas, LLM-friendly output formatting

- - **Server implementation** — TypeScript (`@modelcontextprotocol/sdk`) and Python (`mcp[cli]`) servers; tool/resource/prompt registration; structured error handling; logging, auth, and rate-limit middleware

- - **Transport & deployment** — stdio (local/CLI), SSE (web), StreamableHTTP (production), Docker containerization, health checks, graceful shutdown

- - **Testing & validation** — schema validation, MCP Inspector integration tests, contract/snapshot tests, load testing for remote servers

+ Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

- ## When to Use

+ ## Workflow

- - Exposing an internal REST API to Claude, Cursor, or other MCP clients

- - Replacing brittle browser automation with typed tool interfaces

- - Building a shared MCP server for multiple teams and AI assistants

- - Converting an OpenAPI spec into MCP tools automatically

- - Creating domain-specific tool servers (database, monitoring, deployment)

+ 1. **Get tool definitions.** From a spec: `openapi_converter.py spec.json -o tools.json` (add `--filter GET,POST`, `--exclude '/internal/*'`, `--prefix`). From scratch: write `{"tools": [...]}` by hand using [references/tool-schema-design.md](references/tool-schema-design.md).

+ 2. **Lint naming, descriptions and schemas** with `tool_linter.py tools.json`. Fix every error; rewrite descriptions to say when to use the tool and what it returns.

+ 3. **Lint interaction design** with `tool_schema_linter.py tools.json`: add pagination to list tools, a `confirm` or `dry_run` gate to destructive ones, arrays where calls are naturally repeated.

+ 4. **Scaffold** the server with `server_scaffolder.py tools.json --lang typescript|python --output <dir>`, then implement each handler from [references/server-implementation.md](references/server-implementation.md).

+ 5. **Test** with MCP Inspector and the checks in [references/testing-and-troubleshooting.md](references/testing-and-troubleshooting.md).

+ 6. Done when both linters exit 0 with `--strict`, every handler returns structured errors instead of throwing, and the Inspector lists and calls every tool.

- ## Clarify First

+ ## Quick Start

- Before building the server, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

+ ```bash

+ # from engineering/mcp-server-builder/; write output outside the repo

+ OUT=$(mktemp -d)

+ python3 scripts/openapi_converter.py assets/sample_openapi.json --prefix tasks -o "$OUT/tools.json"

+ python3 scripts/tool_linter.py "$OUT/tools.json" # exit 0: no errors, 2 usage-guidance warnings

+ python3 scripts/tool_schema_linter.py "$OUT/tools.json" # exit 1: delete has no confirm gate

+ python3 scripts/server_scaffolder.py "$OUT/tools.json" --lang python --output "$OUT/server" --dry-run

+ ```

- - **Source contract:** the OpenAPI spec or API to expose, or whether building tools from scratch (the input the tool definitions and conversion derive from).

- - **Language:** TypeScript (`@modelcontextprotocol/sdk`) or Python (`mcp[cli]`) (sets the server implementation generated).

- - **Transport:** stdio (local/CLI), SSE (web), or StreamableHTTP (production) (drives transport, auth, and deployment patterns).

+ ```bash

+ python3 scripts/tool_linter.py assets/flawed_tools.json # exit 1: camelCase name, 1-char description, untyped property

+ python3 scripts/tool_schema_linter.py assets/flawed_tools.json # exit 1: unpaginated list, ungated delete

+ ```

- Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

+ ## Tools Overview

- ## References

+ |------|---------|-----------|------------|

+ | `scripts/openapi_converter.py` | OpenAPI 3.x / Swagger 2.0 JSON to MCP tool definitions (`{"tools": [...]}`), operationId to snake_case | `spec`, `-o`, `--prefix`, `--filter GET,POST`, `--exclude GLOB`, `--no-source`, `--json` | 0 converted; 2 missing or invalid spec |

+ | `scripts/tool_linter.py` | Naming (snake_case, verb_noun), description length and guidance, property types and descriptions | `file`, `--path`, `--strict`, `--json` | 0 no errors (or no warnings with `--strict`); 1 issues; 2 unreadable input |

+ | `scripts/tool_schema_linter.py` | Interaction smells: list tools without pagination, destructive tools without a gate, chatty single-item tools, unconstrained inputs | `file`, `--path`, `--strict`, `--json` | 0 no warnings; 1 smells found; 2 unreadable input |

- Load the reference that matches the task — keep this file lean and pull detail on demand:

+ The linters accept a bare tool, a tool array, or a `{"tools": [...]}` wrapper (converter output); use `--path` for other nesting. The scaffolder takes the converter output directly and derives the server name from the spec title when `name` is absent. Run both linters: they check different things.

- - **[references/tool-schema-design.md](references/tool-schema-design.md)** — naming conventions, description engineering template, and input schema best practices. Read first when defining any tool, since description quality drives LLM tool selection.

- - **[references/server-implementation.md](references/server-implementation.md)** — complete TypeScript and Python server code (tools, resources, prompts) plus the OpenAPI-to-MCP conversion rules and script. Read when writing the server.

- - **[references/transport-and-deployment.md](references/transport-and-deployment.md)** — client configuration (`claude_desktop_config.json` for stdio and remote) and the tool versioning strategy. Read when connecting clients or planning releases.

- - **[references/testing-and-troubleshooting.md](references/testing-and-troubleshooting.md)** — schema validation function, MCP Inspector commands, common pitfalls, best practices, troubleshooting table, and success criteria. Read when validating, hardening for production, or diagnosing failures.

- - **[references/streaming-batch-and-computer-use.md](references/streaming-batch-and-computer-use.md)** — progress/streaming and cancellation for long-running tools, wrapping computer-use/browser/desktop actions (granularity, returning state, safety gates), and batch-friendly tool design (arrays, idempotency, partial-failure results, pagination). Read when a tool runs long, drives a live surface, or processes many items.

+ ## Anti-Patterns

+ **Mistake:** Shipping the converter output as is.

+ **Why it matters:** OpenAPI summaries describe endpoints, not when an agent should call them, so the model picks the wrong tool or none.

+ **Instead:** Rewrite each description with a "Use when ..." clause and what it returns, then re-lint.

+ **Mistake:** A list tool that returns everything.

+ **Why it matters:** Unbounded results flood the context window and get truncated mid-record.

+ **Instead:** Cap the page size, return a cursor, and document both in the description.

+ **Mistake:** Destructive tools that act on the first call.

+ **Why it matters:** The agent calls tools speculatively; an ungated delete turns a misunderstanding into data loss.

+ **Instead:** Add `confirm` or `dry_run` defaulting to the safe path, and say in the description that the action cannot be undone.

## Common Patterns

- - **Streaming long-running tools** — when a call routinely exceeds a few seconds (builds, crawls, automation), emit throttled progress updates with a stable correlation handle, stream semantically whole chunks ending in an explicit terminal signal, and honor cancellation by aborting the real work and cleaning up sessions. The final response must stand alone. See `references/streaming-batch-and-computer-use.md`.

- - **Batch-friendly tools** — when an operation is naturally repeated, accept a bounded array instead of forcing one chatty call per item; make operations idempotent (or take an idempotency key) and return per-item success/failure results so the agent retries only what failed. List/read tools must paginate with a documented cap and a cursor. Run `scripts/tool_schema_linter.py` to flag chatty single-item tools and missing pagination.

- - **Computer-use via MCP** — expose intent-level actions (`navigate`, `click`, `read_page`) rather than raw pixel primitives, return current observable state (text-first, screenshots only when layout matters), and gate destructive/irreversible actions behind a `confirm`/`dry_run` param scoped to an allowlist with secrets redacted. For the automation engine itself, see the `computer-use-automation` skill.

+ - **Long-running tools:** emit throttled progress with a stable handle, honor cancellation, and make the final response stand alone. See [references/streaming-batch-and-computer-use.md](references/streaming-batch-and-computer-use.md).

+ - **Batch-friendly tools:** accept bounded arrays, take an idempotency key, return per-item results so the agent retries only failures.

+ - **Computer use via MCP:** expose intent-level actions (`navigate`, `click`, `read_page`), return observable state as text first, and gate irreversible actions. For the automation engine see `engineering/computer-use-automation`.

- ## Scope & Limitations

+ ## Reference Documentation

- **This skill covers:**

- - Designing tool schemas, resource providers, and prompt templates for MCP servers

- - Implementing servers in TypeScript (`@modelcontextprotocol/sdk`) and Python (`mcp[cli]`)

- - Transport selection and client configuration (stdio, SSE, StreamableHTTP)

- - OpenAPI-to-MCP conversion patterns and testing strategies

+ - **[references/tool-schema-design.md](references/tool-schema-design.md)**: naming, the description template and input-schema rules. Read first when defining any tool.

+ - **[references/server-implementation.md](references/server-implementation.md)**: TypeScript and Python servers (tools, resources, prompts) and the OpenAPI conversion rules. Read when writing handlers.

+ - **[references/transport-and-deployment.md](references/transport-and-deployment.md)**: transport choice, client configuration and tool versioning. Read when connecting clients or planning releases.

+ - **[references/testing-and-troubleshooting.md](references/testing-and-troubleshooting.md)**: schema validation, MCP Inspector, pitfalls, troubleshooting and success criteria. Read when validating or diagnosing.

+ - **[references/streaming-batch-and-computer-use.md](references/streaming-batch-and-computer-use.md)**: streaming and cancellation, computer-use wrappers, batch design and pagination.

- **This skill does NOT cover:**

- - Building MCP clients or custom LLM orchestration layers — see `engineering/agent-workflow-designer`

- - Designing multi-agent systems that consume MCP tools — see `engineering/agent-designer`

- - API design itself (REST conventions, endpoint naming, versioning) — see `engineering/api-design-reviewer`

- - Infrastructure provisioning, container orchestration, or CI/CD pipelines for deploying MCP servers — see `engineering/ci-cd-pipeline-builder`

+ ## Files

- ## Integration Points

+ | File | Purpose |

+ |------|---------|

+ | `scripts/openapi_converter.py` | OpenAPI to MCP tool definitions |

+ | `scripts/tool_linter.py` | Naming, description and schema linter |

+ | `scripts/tool_schema_linter.py` | Interaction-design linter |

+ | `scripts/server_scaffolder.py` | Server skeleton generator |

+ | `assets/sample_openapi.json` | Three-operation Tasks API (list, create, delete) |

+ | `assets/flawed_tools.json` | Deliberately weak tool definitions; both linters exit 1 |

- | Skill | Integration | Data Flow |

- |-------|-------------|-----------|

- | `engineering/api-design-reviewer` | Review the underlying REST API before converting it to MCP tools | OpenAPI spec → API review findings → refined spec → MCP conversion |

- | `engineering/api-test-suite-builder` | Generate integration tests for the HTTP endpoints that MCP tools wrap | MCP tool definitions → endpoint mapping → test suite generation |

- | `engineering/agent-designer` | Design agents that consume the MCP tools this skill produces | MCP tool schemas → agent tool inventory → agent behavior design |

- | `engineering/observability-designer` | Add structured logging, tracing, and metrics to MCP server handlers | MCP server code → instrumentation plan → logging/tracing middleware |

- | `engineering/ci-cd-pipeline-builder` | Automate build, test, and deploy pipelines for MCP server releases | MCP server repo → pipeline config → automated deploy to staging/prod |

- | `engineering/env-secrets-manager` | Manage API keys, database credentials, and tokens used in MCP server configs | MCP server env vars → secrets audit → secure injection patterns |

+ ## Scope & Limitations

+ **Covers:** tool, resource and prompt design; TypeScript and Python servers; transport choice and client configuration; OpenAPI conversion; schema and interaction linting.

+ **Does not cover:**

+ - MCP clients or orchestration layers (see `engineering/agent-workflow-designer`).

+ - Multi-agent systems that consume the tools (see `engineering/agent-designer`).

+ - REST API design itself (see `engineering/api-design-reviewer`).

+ - Deployment pipelines (see `engineering/ci-cd-pipeline-builder`).