Comprehensive patterns for building, testing, and deploying Model Context Protocol servers in Python and TypeScript.
\n\n\nEcosystem facts verified as of 2026-07-05 (standalone FastMCP at major 3).
\n
┌─────────────────────────────────────────────────────────┐\n│ MCP Host │\n│ (Claude Desktop, Claude Code, Custom App) │\n│ │\n│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │\n│ │ Client A │ │ Client B │ │ Client C │ │\n│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │\n└────────┼───────────────┼───────────────┼────────────────┘\n │ │ │\n ┌────┴────┐ ┌────┴────┐ ┌────┴────┐\n │Transport│ │Transport│ │Transport│\n │ (stdio) │ │ (SSE) │ │ (HTTP) │\n └────┬────┘ └────┬────┘ └────┬────┘\n │ │ │\n┌────────┴──┐ ┌──────┴────┐ ┌──────┴────┐\n│ Server A │ │ Server B │ │ Server C │\n│ │ │ │ │ │\n│ ┌────────┐ │ │ ┌────────┐ │ │ ┌────────┐ │\n│ │ Tools │ │ │ │Resources│ │ │ │Prompts │ │\n│ └────────┘ │ │ └────────┘ │ │ └────────┘ │\n│ ┌────────┐ │ │ ┌────────┐ │ │ ┌────────┐ │\n│ │Resources│ │ │ │Prompts │ │ │ │ Tools │ │\n│ └────────┘ │ │ └────────┘ │ │ └────────┘ │\n└────────────┘ └────────────┘ └────────────┘\n\nProtocol: JSON-RPC 2.0 over chosen transport\nFlow: Client → request → Server → response → Client\nWhat transport does your MCP server need?\n│\n├─ Local CLI tool / single-user desktop integration?\n│ └─ stdio\n│ - Simplest setup, no networking\n│ - Claude Desktop, Claude Code native support\n│ - Process lifecycle managed by host\n│\n├─ Web dashboard / browser-based client?\n│ └─ SSE (Server-Sent Events)\n│ - HTTP-based, works through firewalls\n│ - Persistent connection for server→client events\n│ - Good for development and internal tools\n│\n└─ Production API / multi-tenant / cloud deployment?\n └─ Streamable HTTP\n - HTTP POST for requests, SSE for streaming responses\n - Supports stateless and stateful modes\n - Full auth support, load balancer friendly\n - Recommended for production deployments\nWhat does the LLM need to do?\n│\n├─ Perform an action or computation?\n│ └─ TOOL\n│ - Has side effects (API calls, file writes, DB mutations)\n│ - Accepts structured input, returns results\n│ - Examples: run_query, create_issue, send_email\n│\n├─ Read data or context?\n│ └─ RESOURCE\n│ - Read-only data retrieval\n│ - Identified by URI (file://, db://, api://)\n│ - Examples: config://app, schema://users, file://readme.md\n│\n└─ Guide the LLM's behavior or workflow?\n └─ PROMPT\n - Templated instructions with arguments\n - Suggests conversation starters or workflows\n - Examples: code_review(language, file), summarize(topic)\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"my-server\")\n\n@mcp.tool()\ndef search_docs(query: str) -> str:\n \"\"\"Search documentation by keyword.\"\"\"\n results = perform_search(query)\n return \"\\n\".join(f\"- {r.title}: {r.snippet}\" for r in results)\n\n@mcp.tool()\ndef create_ticket(title: str, body: str, priority: str = \"medium\") -> str:\n \"\"\"Create a support ticket.\"\"\"\n ticket = api.create(title=title, body=body, priority=priority)\n return f\"Created ticket #{ticket.id}: {ticket.url}\"\n\n@mcp.resource(\"config://app\")\ndef get_config() -> str:\n \"\"\"Return current application configuration.\"\"\"\n return json.dumps(load_config(), indent=2)\n\n@mcp.resource(\"schema://db/{table}\")\ndef get_table_schema(table: str) -> str:\n \"\"\"Return the schema for a database table.\"\"\"\n return json.dumps(get_schema(table), indent=2)\n\n@mcp.prompt()\ndef code_review(language: str, filepath: str) -> str:\n \"\"\"Generate a code review prompt for the given file.\"\"\"\n return f\"Review this {language} code in {filepath} for bugs, style issues, and performance.\"\n\nif __name__ == \"__main__\":\n mcp.run() # Defaults to stdio transport\nInstall and run:
\nuv init my-mcp-server && cd my-mcp-server\nuv add mcp[cli]\n# Run with: uv run python server.py\n# Or: uv run mcp run server.py\nTwo Python FastMCPs — know which you're on. The official mcp SDK bundles a frozen\n1.x-era FastMCP (from mcp.server.fastmcp import FastMCP, used in the samples above —\nstable, minimal). The standalone fastmcp package (gofastmcp.com) is where active\ndevelopment happens and is at major 3: same decorator surface, plus auth, proxying,\nOpenAPI generation, and a test client. To use it:
uv add fastmcp\nfrom fastmcp import FastMCP # standalone FastMCP 3 — not mcp.server.fastmcp\n\nmcp = FastMCP(\"my-server\") # v3: constructor is identity/behaviour only;\n # transport config moved to run()/serve time\nFastMCP 3 breaking changes (from 2.x): 16 deprecated constructor kwargs removed\n(transport settings now passed at serve time), ui= replaced by app=,\nctx.set_state()/ctx.get_state() are now async with session-scoped persistence, and\nthe metadata namespace changed from _fastmcp to fastmcp.
import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { z } from \"zod\";\n\nconst server = new McpServer({\n name: \"my-server\",\n version: \"1.0.0\",\n});\n\n// Register a tool\nserver.tool(\n \"search_docs\",\n \"Search documentation by keyword\",\n { query: z.string().describe(\"Search query\") },\n async ({ query }) => {\n const results = await performSearch(query);\n return {\n content: [{ type: \"text\", text: results.join(\"\\n\") }],\n };\n }\n);\n\n// Register a resource\nserver.resource(\n \"config\",\n \"config://app\",\n { description: \"Current application configuration\" },\n async (uri) => ({\n contents: [{\n uri: uri.href,\n mimeType: \"application/json\",\n text: JSON.stringify(loadConfig(), null, 2),\n }],\n })\n);\n\n// Register a prompt\nserver.prompt(\n \"code_review\",\n \"Generate a code review prompt\",\n { language: z.string(), filepath: z.string() },\n async ({ language, filepath }) => ({\n messages: [{\n role: \"user\",\n content: {\n type: \"text\",\n text: `Review this ${language} code in ${filepath} for bugs and style issues.`,\n },\n }],\n })\n);\n\nasync function main() {\n const transport = new StdioServerTransport();\n await server.connect(transport);\n}\nmain().catch(console.error);\nInstall and run:
\nnpm init -y\nnpm install @modelcontextprotocol/sdk zod\nnpx tsx server.ts\n| Feature | \nstdio | \nSSE | \nStreamable HTTP | \n
|---|---|---|---|
| Use case | \nLocal CLI tools, desktop | \nWeb dashboards, dev | \nProduction APIs | \n
| Protocol | \nstdin/stdout pipes | \nHTTP + EventSource | \nHTTP POST + SSE | \n
| Auth support | \nEnv vars only | \nBearer tokens | \nFull OAuth2/PKCE | \n
| Deployment | \nLocal process | \nSingle server | \nLoad balanced | \n
| Reconnection | \nProcess restart | \nAuto-reconnect | \nStateless resilient | \n
| Multi-client | \n1:1 only | \nMultiple clients | \nHorizontally scalable | \n
| Firewall | \nN/A (local) | \nHTTP-friendly | \nHTTP-friendly | \n
| State | \nProcess lifetime | \nConnection lifetime | \nSession or stateless | \n
| Best for | \nClaude Desktop/Code | \nInternal tools | \nCloud/enterprise | \n
# Pattern 1: API keys from environment\nimport os\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"api-server\")\n\n@mcp.tool()\ndef call_api(endpoint: str) -> str:\n \"\"\"Call external API with configured credentials.\"\"\"\n api_key = os.environ[\"MY_API_KEY\"] # Set in client config\n resp = httpx.get(f\"https://api.example.com/{endpoint}\",\n headers={\"Authorization\": f\"Bearer {api_key}\"})\n return resp.text\n# Pattern 2: OAuth2 token refresh (in-memory cache)\nimport time\n\n_token_cache: dict = {}\n\nasync def get_valid_token() -> str:\n if _token_cache.get(\"expires_at\", 0) > time.time() + 60:\n return _token_cache[\"access_token\"]\n resp = await httpx.AsyncClient().post(\"https://auth.example.com/token\", data={\n \"grant_type\": \"refresh_token\",\n \"refresh_token\": os.environ[\"REFRESH_TOKEN\"],\n \"client_id\": os.environ[\"CLIENT_ID\"],\n })\n data = resp.json()\n _token_cache.update({\n \"access_token\": data[\"access_token\"],\n \"expires_at\": time.time() + data[\"expires_in\"],\n })\n return data[\"access_token\"]\n// Claude Desktop config with env vars\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--directory\", \"/path/to/server\", \"python\", \"server.py\"],\n \"env\": {\n \"MY_API_KEY\": \"sk-...\",\n \"DATABASE_URL\": \"postgresql://...\"\n }\n }\n }\n}\n| Gotcha | \nWhy | \nFix | \n
|---|---|---|
| Tool not appearing in client | \ninputSchema has invalid JSON Schema | \nValidate schema with jsonschema library; use Pydantic/Zod to generate | \n
| Tool returns raw object | \nResults must be content list with typed items | \nAlways return {\"content\": [{\"type\": \"text\", \"text\": \"...\"}]} | \n
| Timeout on long operations | \nDefault client timeout is often 30-60s | \nAdd progress notifications; break into smaller operations | \n
| Concurrent requests fail | \nTool handler uses shared mutable state | \nUse asyncio locks, or make handlers stateless | \n
| Large response crashes client | \nMCP messages have practical size limits | \nPaginate results; return summaries with detail-fetch tools | \n
| Error swallowed silently | \nException in handler returns generic error | \nSet isError: true in response; include error message in content | \n
| SSE connection drops | \nNo keep-alive or reconnection logic | \nImplement heartbeat; client auto-reconnects on SSE | \n
| Client ignores new tools | \nCapabilities not updated after tool change | \nCall server.request_context.session.send_resource_list_changed() | \n
| Tool name collision | \nTwo servers register same tool name | \nNamespace tools: myserver_search not just search | \n
| Resource URI too generic | \ndata://info is ambiguous | \nUse specific schemes: db://myapp/users, config://myapp/settings | \n
async def missing on handler | \nFastMCP tools can be sync or async, but I/O should be async | \nUse async def for any handler doing network/file I/O | \n
| Server works locally, fails in Claude Desktop | \nDifferent working directory or PATH | \nUse absolute paths; log os.getcwd() on startup | \n
| File | \nLines | \nContent | \n
|---|---|---|
references/server-architecture.md | \n~700 | \nServer lifecycle, FastMCP/TS SDK setup, capabilities, middleware, error handling | \n
references/tool-handlers.md | \n~650 | \nSchema design, validation, return types, composition, side effects, examples | \n
references/resources-prompts.md | \n~550 | \nResource URIs, static/dynamic resources, templates, prompts, subscriptions | \n
references/transport-auth.md | \n~550 | \nstdio/SSE/HTTP transports, session management, OAuth2, rate limiting, TLS | \n
references/testing-debugging.md | \n~550 | \nMCP Inspector, unit/integration testing, protocol debugging, CI, performance | \n
This skill encodes fast-moving facts (the MCP SDK package names + spec URL). scripts/check-mcp-facts.py guards them against silent drift:
# Structural (PR CI, no network): every catalogued package's prose_token is\n# still named in this skill's prose, the spec URL is still cited, and the\n# currency note still carries a year.\npython scripts/check-mcp-facts.py --offline # exit 0 consistent, 10 drift\n\n# Live (freshness job, never blocks a PR): each SDK still resolves on\n# npm/PyPI, no tracked major has moved off the sampled major, spec URL 200.\npython scripts/check-mcp-facts.py --live # exit 10 drift, 7 registries unreachable\nThe canonical fact set lives in assets/mcp-facts.json; when you add or drop a package, update it to match or --offline fails CI.
npx @modelcontextprotocol/inspectorclaude-code-hooks (hook into Claude Code), claude-code-debug (debug Claude Code issues)