Anthropic Model Context Protocol (MCP) Implementation Guide

Configuration Requirements

System Dependencies

• Python 3.10+ (required - corporate machines with locked Python 3.8 will fail)
• uv package manager (frequently disappears from PATH after installation)
• Claude Desktop (randomly stops detecting servers, requires multiple restarts)
• Git (standard requirement)

Critical Installation Issues

• Time Investment: 3-4 hours minimum (not the claimed "30-minute quickstart")
• PATH Problems: uv install script doesn't update current terminal session
• Corporate Environment Failures: IT-locked Python 3.8 systems require pyenv or manual installation

Working Server Implementation

Dependencies

uv add "mcp>=1.2.0" httpx

Functional Weather Server Code

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather-server")
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "mcp-weather-server/1.0"

async def make_nws_request(url: str) -> dict[str, Any] | None:
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)

    if not points_data:
        return "Unable to fetch forecast data for this location."

    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)

    if not forecast_data:
        return "Unable to fetch detailed forecast."

    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:3]:
        forecast = f"""
{period['name']}:
Temperature: {period['temperature']}°{period['temperatureUnit']}
Wind: {period['windSpeed']} {period['windDirection']}
Forecast: {period['detailedForecast']}
"""
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)

if __name__ == "__main__":
    mcp.run(transport="stdio")

Claude Desktop Integration

Configuration File Locations

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Working Configuration

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/weather-server",
        "run",
        "weather_server.py"
      ]
    }
  }
}

Critical Configuration Rules

• Absolute paths only - relative paths cause silent failures
• Windows users: Use forward slashes / in JSON (backslashes break parsing)
• Restart requirement: Claude Desktop requires 3 complete restarts to detect changes
• JSON syntax: Single comma error breaks entire configuration

Failure Modes and Solutions

Common Errors and Resolutions

Error	Root Cause	Solution
uv: command not found	Install script doesn't update current session	source ~/.bashrc or restart terminal
Python 3.8.10 found, but 3.10+ required	Corporate Python lockdown	Use uv python install 3.11 or pyenv
ModuleNotFoundError: No module named 'mcp'	MCP version <1.2.0 installed	Force upgrade: uv add "mcp>=1.2.0"
Failed to connect to MCP server	Path issues or server crashes	Test with uv run weather_server.py first
Tools visible but not callable	Claude Desktop transport issues	Use MCP Inspector for verification

NWS API Limitations

• Geographic Coverage: US-only (silent failure for international coordinates)
• API Reliability: Monthly downtime for maintenance
• Rate Limiting: Requires User-Agent header or returns 403 Forbidden
• Response Times: Slow API requiring timeout configuration

Testing and Debugging

MCP Inspector (Reliable Testing)

npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector uv run weather_server.py

Production Considerations

Security Requirements

• API Keys: Environment variables only, never hardcoded
• Input Validation: All user inputs require validation (injection risks)
• Error Messages: Don't expose internal paths or database schemas
• HTTPS: Required for remote deployments
• Rate Limiting: Prevent DoS attacks

Performance Optimization

• Caching: NWS API responses (slow response times)
• Timeouts: 30-second maximum for external API calls
• Connection Pooling: Required for database connections
• Error Handling: Comprehensive exception handling for external API failures

Monitoring Requirements

• Tool Response Times: External API latency impacts user experience
• Error Rates: Alert at >10% error rate
• Memory Usage: Python memory leak detection
• Request Patterns: Abuse detection and prevention

Advanced Implementation

Database Integration

import asyncpg
import asyncio
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("database-server")
pool = None

@mcp.on_startup
async def startup():
    global pool
    DATABASE_URL = os.getenv("DATABASE_URL")
    pool = await asyncpg.create_pool(DATABASE_URL, min_size=1, max_size=5)

@mcp.tool()
async def safe_query(sql: str) -> str:
    try:
        async with pool.acquire() as conn:
            result = await asyncio.wait_for(conn.fetch(sql), timeout=30)
            return str(result)
    except asyncio.TimeoutError:
        return "Query timed out - check your SQL"
    except Exception as e:
        return f"Database error: {str(e)}"

Remote Deployment Configuration

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "server.py", "--transport", "sse", "--port", "8000"]

Remote Server Configuration

{
  "mcpServers": {
    "team-server": {
      "url": "https://your-server.com/mcp-sse",
      "headers": {
        "Authorization": "Bearer your-team-token"
      }
    }
  }
}

Transport Modes

• stdio: Local development only
• SSE: Remote server deployment
• Mixing transports: Causes debugging difficulties

Resource Requirements

• Development Time: 3-4 hours minimum for first working implementation
• Expertise Level: Intermediate Python knowledge required
• System Resources: Minimal computational requirements
• Network Dependencies: External API access required for functionality

Breaking Points

• Claude Desktop: Randomly stops detecting servers (no clear resolution)
• Configuration Errors: Single JSON syntax error breaks entire setup
• PATH Issues: uv installation frequently requires manual PATH configuration
• API Dependencies: NWS API downtime breaks functionality
• Version Compatibility: MCP versions <1.2.0 lack FastMCP support

Decision Criteria

• Use MCP when: Need custom tools integrated with Claude Desktop
• Avoid MCP when: Simple API calls sufficient, or rapid prototyping required
• Alternative Frameworks: Direct API integration often simpler for basic use cases