mcp-builder

Use the MCP Python SDK with FastMCP to register tools via decorators, define Pydantic v2 models for input validation, and use async/await for all I/O. Follow the four-phase workflow: research the API, implement shared utilities first, then tools, then create evaluations.

MCP servers are long-running processes that wait on stdio or HTTP, so running them directly blocks your terminal. Use the evaluation harness script which manages the server lifecycle, run the server in tmux, or use a timeout command like 'timeout 5s python server.py'.

Design tools around workflows rather than raw API endpoints, return concise high-signal data with configurable detail levels, and write error messages that suggest corrective actions. Use snake_case names with service prefixes like 'github_create_issue' and add annotations such as readOnlyHint.

Both are fully supported by official SDKs. Python uses FastMCP with Pydantic validation and suits data-heavy integrations, while TypeScript uses the MCP SDK with Zod schemas and strict typing, fitting Node.js ecosystems.

Create 10 complex, read-only questions with stable verifiable answers in an XML file, then run scripts/evaluation.py against your server via stdio, SSE, or HTTP. The harness reports accuracy, tool call counts, and agent feedback on tool quality.

Tools that return unbounded results overwhelm the LLM's context window. Set a CHARACTER_LIMIT constant around 25,000 characters, implement pagination with limit and offset parameters, and truncate responses with clear guidance on filtering.