MCP Patterns

Model Context Protocol (MCP) server patterns for building integrations with Claude Code.

Basic MCP Server (Python)

from mcp.server import Server from mcp.server.stdio import stdio_server

app = Server("my-server")

@app.list_tools() async def list_tools(): return [ { "name": "my_tool", "description": "Does something useful", "inputSchema": { "type": "object", "properties": { "query": {"type": "string", "description": "Search query"} }, "required": ["query"] } } ]

@app.call_tool() async def call_tool(name: str, arguments: dict): if name == "my_tool": result = await do_something(arguments["query"]) return {"content": [{"type": "text", "text": result}]} raise ValueError(f"Unknown tool: {name}")

async def main(): async with stdio_server() as (read_stream, write_stream): await app.run(read_stream, write_stream, app.create_initialization_options())

if name == "main": import asyncio asyncio.run(main())

Project Layout

my-mcp-server/ ├── src/ │ └── my_server/ │ ├── init.py │ ├── server.py # Main server logic │ ├── tools.py # Tool handlers │ └── resources.py # Resource handlers ├── pyproject.toml └── README.md

Claude Desktop Configuration

Basic Configuration

{ "mcpServers": { "my-server": { "command": "python", "args": ["-m", "my_server"], "env": { "MY_API_KEY": "your-key-here" } } } }

With uv (Recommended)

{ "mcpServers": { "my-server": { "command": "uv", "args": ["run", "--directory", "/path/to/my-server", "python", "-m", "my_server"], "env": { "MY_API_KEY": "your-key-here" } } } }

Quick Reference

Pattern Use Case Reference

Tool validation Input sanitization with Pydantic ./references/tool-patterns.md

Error handling Graceful failure responses ./references/tool-patterns.md

Multiple tools CRUD-style tool registration ./references/tool-patterns.md

Static resources Config/settings exposure ./references/resource-patterns.md

Dynamic resources Database-backed resources ./references/resource-patterns.md

Environment auth API key from env vars ./references/auth-patterns.md

OAuth tokens Token refresh with TTL ./references/auth-patterns.md

SQLite cache Persistent state storage ./references/state-patterns.md

In-memory cache TTL-based caching ./references/state-patterns.md

Manual testing Quick validation script ./references/testing-patterns.md

pytest async Unit tests for tools ./references/testing-patterns.md

Common Issues

Issue Solution

Server not starting Check command path, ensure dependencies installed

Tool not appearing Verify list_tools() returns valid schema

Auth failures Check env vars are set in config, not shell

Timeout errors Add timeout to httpx calls, use async properly

JSON parse errors Ensure call_tool returns proper content structure

Official Documentation

• https://modelcontextprotocol.io - MCP specification

• https://modelcontextprotocol.io/docs/concepts/tools - Tools reference

• https://modelcontextprotocol.io/docs/concepts/resources - Resources reference

• https://github.com/modelcontextprotocol/python-sdk - Python SDK

• https://github.com/modelcontextprotocol/servers - Official MCP servers

Additional Resources

For detailed patterns, load:

• ./references/tool-patterns.md

• Validation, error handling, multi-tool registration

• ./references/resource-patterns.md

• Static and dynamic resource exposure

• ./references/auth-patterns.md

• Environment variables, OAuth token refresh

• ./references/state-patterns.md

• SQLite persistence, in-memory caching

• ./references/testing-patterns.md

• Manual test scripts, pytest async patterns