Design and deploy Model Context Protocol servers with deep knowledge of the JSON-RPC 2.0 spec, transport mechanisms, and protocol lifecycle. Covers FastMCP framework patterns, production hardening, and diagnostic techniques for connectivity failures. Engage when architecting MCP integrations, building custom servers, or debugging protocol-level issues.
Design and deploy Model Context Protocol servers with deep knowledge of the JSON-RPC 2.0 spec, transport mechanisms, and protocol lifecycle. Covers FastMCP framework patterns, production hardening, and diagnostic techniques for connectivity failures. Engage when architecting MCP integrations, building custom servers, or debugging protocol-level issues.
MCP Architect Designer
Overview
This skill provides expert guidance for Model Context Protocol (MCP) architecture, design, implementation, and troubleshooting. Combines deep knowledge of the MCP specification (JSON-RPC 2.0, protocol lifecycle, transport mechanisms) with practical expertise in building production-ready MCP servers using the FastMCP framework. Includes comprehensive troubleshooting capabilities for diagnosing and fixing MCP servers that won't start, can't connect, or fail during operation.
When to Use This Skill
This skill applies to tasks involving:
Building New MCP Servers - Creating MCP servers from scratch or using templates
Error Handling - Standard codes (-32700 to -32603) and MCP-specific codes
Version Negotiation - Protocol version compatibility between client and server
Critical Requirements:
// Request MUST have unique id{"jsonrpc":"2.0","id":1,"method":"tools/list"}// Response MUST match request id{"jsonrpc":"2.0","id":1,"result":{...}}// Notification MUST NOT have id{"jsonrpc":"2.0","method":"notifications/progress","params":{...}}
2. Transport Pattern Implementation
Reference references/transport-patterns.md for transport-specific details.
Transport Selection Guide:
Use Case
Transport
Reason
Web application
Streamable HTTP
Browser-compatible, SSE support
Local CLI tool
stdio
Simple process model
Cloud service
Streamable HTTP
Standard HTTP infrastructure
IDE plugin
stdio
Process isolation
Streamable HTTP Critical Points:
Single endpoint (/mcp) for both POST (client→server) and GET (SSE server→client)
Include Mcp-Session-Id header for session management
Expose Mcp-Session-Id in CORS expose_headers
Validate Origin header for security
Bind to localhost (127.0.0.1) for local servers
stdio Critical Points:
Newline-delimited JSON-RPC messages
Server reads from stdin, writes to stdout
Logs go to stderr (never stdout)
UTF-8 encoding required
3. FastMCP Framework Patterns
Reference references/fastmcp-framework.md for comprehensive implementation examples.
For detailed tool and resource design patterns, see references/fastmcp-framework.md which covers:
Type hints and automatic schema generation
Pydantic models for complex inputs
Error handling patterns (business logic vs framework errors)
Static and dynamic resources
URI template patterns
Binary resources with MIME types
Security Best Practices
IMPORTANT: For production servers supporting multiple clients (OpenAI, Claude), refer to references/dual-client-authentication.md for comprehensive guidance on authentication patterns, OWASP compliance, and recommended architectures.
2. Input Validation: Use Pydantic models with validators to prevent injection attacks and path traversal.
3. CORS Configuration: Configure with specific allowed origins, expose Mcp-Session-Id header for session management.
Production Deployment
For production deployment patterns, see references/deployment-patterns.md which covers:
Docker and Kubernetes deployment
Reverse proxy configuration (nginx, Caddy)
Monitoring and observability (health checks, metrics, structured logging)
Environment configuration
Security hardening and TLS configuration
Deployment checklists
Architecture Patterns
Dual-Interface (REST + MCP)
When building systems with both traditional REST API and MCP interface:
from mcp.server.fastmcp import FastMCP
from fastapi import FastAPI
# REST API
rest_api = FastAPI()
@rest_api.get("/api/data/{id}")defget_data_rest(id: str):
return get_data_from_db(id) # Shared business logic# MCP Interface
mcp = FastMCP("DualInterface")
@mcp.tool()defget_data(id: str) -> str:
"""Get data by ID (MCP tool)."""
data = get_data_from_db(id) # Same business logicreturn json.dumps(data)
# Mount bothfrom starlette.applications import Starlette
from starlette.routing import Mount
app = Starlette(routes=[
Mount("/api", rest_api),
Mount("/mcp", mcp.streamable_http_app())
])
Multi-Server Architecture
For complex systems with multiple specialized servers:
For servers supporting both OpenAI and Claude clients, use separate endpoints with shared backend logic due to:
Different token audience validation requirements (MCP spec)
RFC 8707 resource parameter handling differences
Distinct discovery metadata needs
OWASP security compliance requirements
See references/dual-client-authentication.md for:
Complete authentication flow comparisons
Production-ready implementation examples
Token verifier patterns (strict vs flexible)
OWASP security compliance details
Why single endpoint approach doesn't work
Bundled Resources
scripts/
test_mcp_connection.py - Diagnostic tool for testing MCP server connectivity and protocol compliance.
Usage:
# Test HTTP MCP server
python scripts/test_mcp_connection.py http://localhost:8000/mcp
# Test with verbose output
python scripts/test_mcp_connection.py http://localhost:8000/mcp --verbose
Systematic checks:
Basic connectivity (server reachable)
Initialize handshake (protocol version negotiation)
Tools discovery (tools/list)
Session management (Mcp-Session-Id header)
SSE support (Server-Sent Events)
init_mcp_server.py - Project generator for new MCP servers.
