mcp-patterns

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

```json
{
  "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