mcp-patterns

# MCP Patterns

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

## Basic MCP Server (Python)

```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)

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