ComeOnOliver/skillshub / skills/aiskillstore/marketplace/0xdarkmatter/mcp-patterns
mcp-patterns
VerifiedModel Context Protocol (MCP) server patterns for building integrations with Claude Code. Triggers on: mcp server, model context protocol, tool handler, mcp resource, mcp tool.
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |