| name | mcp-builder |
| model | sonnet |
| description | Scaffolds new MCP servers with tool definitions, transport wiring, handler structure, and test harness for Python (FastMCP) or TypeScript (MCP SDK). Use when: 'build a new MCP server', 'scaffold an MCP integration', 'create tools for an external API', 'set up MCP transport and handlers'. |
| category | system-health |
| triggers | ["build a new MCP server","scaffold an MCP integration","create tools for an external API","set up MCP transport and handlers"] |
| tier | 1 |
| agents | ["primary"] |
| tool_dependencies | ["file_system"] |
| inputs | [{"name":"server_name","type":"string","description":"Name of the MCP server to scaffold (used for directory and package naming)","required":true},{"name":"tools","type":"string[]","description":"List of tool names to generate stubs for (e.g., list_items, create_item, search)","required":false},{"name":"transport","type":"string","description":"Transport protocol: 'stdio' (default, for CLI integration) or 'sse' (for HTTP/server deployment)","required":false}] |
| outputs | [{"name":"scaffold","type":"ref","format":"cas-ref","description":"Complete MCP server scaffold with project structure, tool handlers, transport config, and test harness"}] |
MCP Builder
Purpose: Scaffold production-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Produces a complete project structure with tool definitions, transport wiring, handler implementations, input validation, error handling, and an evaluation test harness.
I. When to Use
- Starting a new MCP server to integrate an external API or service
- Adding MCP tool access to an existing service
- Need a working scaffold with transport, validation, and tests from the start
- Building for either Python (FastMCP) or TypeScript (MCP SDK) targets
II. Agent-Centric Design Principles
MCP tools are used by AI agents, not humans. Design accordingly:
- Build for workflows, not API endpoints -- consolidate related operations (e.g.,
schedule_event that checks availability AND creates the event)
- Optimize for limited context -- return high-signal information, not exhaustive data dumps; offer concise vs. detailed response formats
- Actionable error messages -- errors should guide agents toward correct usage ("Try filter='active_only' to reduce results")
- Natural task subdivisions -- tool names reflect how humans think about tasks, with consistent prefixes for discoverability
- Evaluation-driven development -- create realistic eval scenarios early; let agent feedback drive tool improvements
III. Workflow
Phase 1: Research and Planning
- Study the target API -- read all available documentation (endpoints, auth, rate limits, pagination, error codes, data models)
- Select high-value tools -- prioritize operations that enable complete workflows, not just individual API calls
- Plan shared utilities -- identify common patterns (API request helpers, pagination, error formatting, auth token management)
- Design input/output schemas -- Pydantic models for Python, Zod schemas for TypeScript; include constraints and descriptive field docs
Phase 2: Scaffold Generation
For each target language, generate the project structure:
Python (FastMCP):
{server_name}/
server.py # MCP server with @mcp.tool registrations
models.py # Pydantic input validation models
utils.py # Shared API request helpers, error formatting
requirements.txt # Dependencies (mcp, pydantic, httpx)
tests/
test_tools.py # Unit tests for each tool handler
eval.xml # Evaluation questions for agent testing
