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, review code quality, then create evaluations.

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

Design tools around workflows rather than raw API endpoints, consolidate related operations, and return high-signal concise responses. Use snake_case names with service prefixes, provide tool annotations like readOnlyHint, and write error messages that suggest corrective next steps.

Both are fully supported by official SDKs. Python uses FastMCP with Pydantic validation and suits data-heavy integrations, while TypeScript uses server.registerTool with Zod schemas and strict typing, fitting Node-based stacks.

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

Tools returning unbounded data exhaust the agent'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.