mcp-patterns

Model Context Protocol (MCP) server patterns for building integrations with Claude Code. Triggers on: mcp server, model context protocol, tool handler, mcp resource, mcp tool.

⭐3stars🔀0forks📁View on GitHub🕐Updated Dec 27, 2025

When & Why to Use This Skill

This Claude skill provides a comprehensive collection of Model Context Protocol (MCP) server patterns designed to streamline the development of custom integrations for Claude Code. It offers standardized templates and best practices for tool registration, resource management, secure authentication, and state persistence, helping developers build robust, production-ready MCP servers efficiently.

Use Cases

  • Bootstrapping new MCP servers with standardized project structures for Python or Node.js environments.
  • Implementing secure tool handlers with Pydantic-based input validation and graceful error handling for agentic workflows.
  • Exposing dynamic database-backed resources or static configuration files to Claude's context window.
  • Managing persistent state in AI agents using SQLite or implementing TTL-based in-memory caching for optimized performance.
  • Configuring complex authentication flows, including environment-variable-based API keys and OAuth token refresh mechanisms.
  • Setting up automated testing environments for MCP tools using pytest and asynchronous testing patterns.
namemcp-patterns
description"Model Context Protocol (MCP) server patterns for building integrations with Claude Code. Triggers on: mcp server, model context protocol, tool handler, mcp resource, mcp tool."
compatibility"Requires Python 3.10+ or Node.js 18+ for MCP server development."
allowed-tools"Read Write Bash"
depends-on[]
related-skills[claude-code-hooks, claude-code-debug]

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"
      }
    }
  }
}
{
  "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

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