mcp-builder

name	mcp-builder
description	Build high-quality MCP (Model Context Protocol) servers for external APIs or services. Use for MCP server design, TypeScript or Python implementation, tool schemas, transports, resources, prompts, testing, and evaluations.

MCP Builder

Create MCP servers that let agents complete real tasks through clear tools, focused outputs, and actionable errors.

Workflow

1. Research the target API: auth, endpoints, data models, pagination, rate limits, and common workflows.
2. Review MCP docs: start with https://modelcontextprotocol.io/sitemap.xml, then fetch relevant .md pages.
3. Choose stack:
   • TypeScript is preferred for broad SDK support and static typing.
   • Python/FastMCP is acceptable when the ecosystem or existing code favors Python.
   • Use streamable HTTP for remote servers; use stdio for local servers.
4. Design tools:
   • Prefer comprehensive API coverage, with workflow tools only where they remove real friction.
   • Use clear action names, consistent prefixes, pagination/filter arguments, and concise descriptions.
   • Return focused data; include structured content/output schemas where supported.
5. Implement shared client, auth, error handling, pagination, and response formatting.
6. Test build/runtime behavior with MCP Inspector.
7. Create evaluations for realistic read-only tasks.

Tool Design Rules

• Use Zod in TypeScript or Pydantic in Python for input schemas.
• Add constraints and examples in field descriptions when they prevent misuse.
• Add annotations: readOnlyHint, destructiveHint, idempotentHint, openWorldHint.
• Make errors actionable: include what failed, likely cause, and next step.
• Keep result payloads bounded; paginate or filter large collections.
• Avoid hidden destructive behavior in broadly named tools.

Validation

TypeScript:

npm run build
npx @modelcontextprotocol/inspector

Python:

python -m py_compile your_server.py
npx @modelcontextprotocol/inspector

Review for duplicated code, consistent errors, type coverage, useful descriptions, and stable pagination.

Evaluations

After implementation, create 10 realistic read-only questions that require multiple tool calls and have stable, verifiable answers.

Evaluation XML format:

<evaluation>
  <qa_pair>
    <question>Question text</question>
    <answer>Expected answer</answer>
  </qa_pair>
</evaluation>

References

Load only what the task needs:

• reference/mcp_best_practices.md: naming, response formats, pagination, transport, security, errors.
• reference/node_mcp_server.md: TypeScript project structure and SDK patterns.
• reference/python_mcp_server.md: Python/FastMCP implementation.
• reference/evaluation.md: evaluation creation and verification.
• TypeScript SDK README: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• Python SDK README: https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md