MCP Python SDK - Stop Writing the Same Database Connector 50 Times

You know that feeling when you've built the same database connector for the fifth fucking time? OpenAI format, Claude format, whatever-new-AI-startup format - it never ends. The MCP Python SDK fixes this nightmare by letting you build one server that talks to everything.

I spent three weeks rebuilding the same PostgreSQL connector for different clients last month. MCP means I build it once, deploy it once, and everything just works. Claude Desktop, browser apps, mobile clients - they all use the same damn protocol.

The basic architecture is simple: MCP Servers expose tools/resources to MCP Clients, which feed context to AI hosts like Claude Desktop.

Check the official architecture guide - it's actually readable, which shocked me after dealing with most protocol docs.

FastMCP Framework

The SDK's FastMCP framework means you don't have to learn the protocol. Just write Python functions and slap decorators on them:

@mcp.tool()
def get_user_data(user_id: int) -> dict:
    """Fetch user data from database."""
    # Your actual database logic here
    return {"user_id": user_id, "name": "John Doe"}

FastMCP reads your type hints and generates the JSON schemas automatically. You write normal functions, it handles all the protocol bullshit in the background.

Transport Options

Stdio transport - Works great with Claude Desktop until Claude randomly stops recognizing your server (happens more than it should). The client spawns your Python script and talks through stdin/stdout. Perfect for development, less reliable than you'd hope.

SSE (Server-Sent Events) - For web apps. Browser clients connect through server-sent events, though you'll spend time debugging CORS issues. The MCP Inspector uses this, and it mostly works.

HTTP transport - The production-ready option. Scales horizontally, works with load balancers, and you can mount it inside existing FastAPI apps. This is what you want for anything serious.

Security and Authentication

OAuth 2.1 is built in, which actually works unlike some OAuth implementations I've suffered through. Standard flows, token refresh, the whole deal without the usual auth framework headaches.

Python Requirements

Python 3.10 minimum. Don't try running this on Python 3.9 - it'll break in mysterious ways. Dependencies are Pydantic for validation, anyio for async stuff, and httpx for HTTP.

Drops right into existing FastAPI or Django projects. No framework conflicts, no weird import issues. Just works.

Deploying MCP servers to production is where you find out what actually works and what's just demo code.

FastMCP Schema Generation

FastMCP reads your type hints and builds JSON schemas automatically. This works until you hit edge cases:

@mcp.tool()
def query_database(table: str, limit: int = 100) -> List[Dict[str, Any]]:
    \"\"\"Query database with row limit.\"\"\"
    try:
        return db.execute(f\"SELECT * FROM {table} LIMIT {limit}\")
    except Exception as e:
        raise MCPError(f\"Database query failed: {e}\")

Schema validation is strict as hell. If your function returns data that doesn't match your type hints, MCP clients get cryptic Pydantic validation errors. You'll spend forever debugging these mismatches.

Deployment Patterns

Stdio Transport: Perfect for Claude Desktop until it breaks. Claude spawns your Python script and talks through stdin/stdout. Works great until your Python path gets fucked up or dependencies go missing.

HTTP Transport: What you actually want for production. Works with load balancers, reverse proxies, all the standard web shit:

## Mount MCP inside existing FastAPI app
app.mount(\"/mcp\", mcp_server.create_asgi_app())

Handles SSL termination, scales horizontally, doesn't randomly die like stdio transport.

Security Implementation

Recent versions have better input validation that actually rejects malformed requests before they hit your code, which is nice.

The OAuth 2.1 implementation includes PKCE support. Works with Auth0 and other providers without the usual OAuth integration nightmares.

Performance Characteristics

Uses anyio for async operations. Memory usage grows with concurrent connections, which is normal. Don't expect miracles - if your tools are slow, MCP won't make them fast.

Hot reloading works with uv run mcp dev server.py. Sometimes complex import changes require a manual restart, but it mostly works.

Development Tools

The MCP Inspector is actually useful for testing servers. Web interface lets you invoke tools and see protocol messages without writing test clients.

Standard Python logging works fine. Enable debug logging to see all the protocol messages, though it gets chatty.

Cloud Deployment

Deploys fine to AWS ECS and Google Cloud Run. Standard Docker containers, standard web infrastructure.

CORS works for browser clients. The SDK handles preflight requests automatically, which saves you from debugging CORS hell for once.

Common Issues

"ImportError: No module named mcp" - Claude Desktop uses its own Python environment. Install dependencies with pip install --user mcp or suffer.

Schema validation failures - Your function returns data that doesn't match your type hints. Pydantic throws cryptic errors that clients can't parse. Test your annotations.

Memory leaks with long connections - Earlier versions had connection pooling issues. Recent updates are better but still close your database connections properly.

Hot reload stops working - Complex import dependency changes confuse the dev server. Kill it and restart. That's what you'll do anyway.