MCP Server Development Guide
Create MCP servers that enable LLMs to interact with external services through well-designed tools.
High-Level Workflow
Phase 1: Research and Planning
Understand Modern MCP Design:
-
Balance comprehensive API coverage with specialized workflow tools
-
Use clear, descriptive tool names with consistent prefixes (e.g., github_create_issue )
-
Design tools that return focused, relevant data
-
Provide actionable error messages
Study MCP Protocol:
-
Start with sitemap: https://modelcontextprotocol.io/sitemap.xml
-
Key pages: specification, transport mechanisms, tool definitions
Phase 2: Implementation
Recommended Stack:
-
Language: TypeScript (best SDK support)
-
Transport: Streamable HTTP for remote, stdio for local
Project Structure:
my-mcp-server/ ├── src/ │ ├── index.ts # Server entry point │ ├── tools/ # Tool implementations │ └── utils/ # Shared utilities ├── package.json └── tsconfig.json
Tool Implementation Pattern:
server.registerTool({ name: "github_create_issue", description: "Create a new GitHub issue", inputSchema: z.object({ repo: z.string().describe("Repository name (owner/repo)"), title: z.string().describe("Issue title"), body: z.string().optional().describe("Issue body") }), outputSchema: z.object({ id: z.number(), url: z.string() }), annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }, handler: async (input) => { // Implementation return { id: 123, url: "https://..." }; } });
Phase 3: Test
TypeScript
npm run build npx @modelcontextprotocol/inspector
Python
python -m py_compile your_server.py
Phase 4: Create Evaluations
Create 10 complex, realistic questions to test your MCP server:
<evaluation> <qa_pair> <question>Find all open issues labeled 'bug' in the repo</question> <answer>5</answer> </qa_pair> </evaluation>
Tool Design Best Practices
-
Use Zod (TS) or Pydantic (Python) for schemas
-
Include constraints and examples in field descriptions
-
Define outputSchema for structured data
-
Support pagination where applicable
-
Add tool annotations (readOnly, destructive, idempotent)