Learn how to build a production-ready MCP (Model Context Protocol) server in Python that wraps external APIs. Progress from a basic implementation to a comprehensive solution with tools, resources, prompts, error handling, and deployment.

## Overview

You'll build an MCP server that wraps a Weather API, learning each concept as we go. We start with the simplest possible server and incrementally add production features.

**What you'll learn:**
- What MCP is and how it works
- Building tools, resources, and prompts
- Proper error handling and logging
- Deploying to production

**Prerequisites:** Python 3.10+, async/await familiarity, REST API basics

Overview

## Step 1: What is MCP and Why Use It?

**MCP (Model Context Protocol)** is a standard way for AI assistants to talk to external tools and data. Think of it as a "USB port" for AI - any AI that supports MCP can use any MCP server.

```
┌──────────────┐                    ┌──────────────┐
│   Claude /   │  ◄── JSON-RPC ──►  │  Your MCP    │  ──►  External API
│   ChatGPT    │     (standard)     │   Server     │       (Weather, DB, etc.)
└──────────────┘                    └──────────────┘
```

**Why not just call APIs directly?**
- MCP provides a standard interface - write once, works with any MCP-compatible AI
- Built-in tool discovery - AI can see what your server offers
- Structured schemas - AI understands parameters and return types automatically

**Three core concepts:**

| Concept | What it is | Example |
|---------|-----------|---------|
| **Tool** | A function the AI can call | `get_weather("London")` |
| **Resource** | Read-only data (like a GET endpoint) | List of supported cities |
| **Prompt** | A reusable instruction template | "Compare weather for {city1} and {city2}" |

What is MCP and Why Use It?

## Step 2: Project Setup

Create a new project:

```bash
mkdir mcp-weather && cd mcp-weather
```

**Using uv (recommended):**
```bash
uv init
uv add mcp httpx python-dotenv
```

**Why these packages?**
- `mcp` - The official MCP Python SDK
- `httpx` - Modern async HTTP client (better than `requests` for async)
- `python-dotenv` - Load API keys from `.env` files safely

Create your `.env` file:
```env
WEATHER_API_KEY=your_key_here
```

<aside>
⚠️ **Never commit `.env` to git.** Add it to `.gitignore`.
</aside>

Project Setup

Getting Started

## Step 3: Your First MCP Server (Minimal)

Create `server.py`:

```python
from mcp.server.fastmcp import FastMCP

# Initialize the server
# The name appears when AI clients discover your server
mcp = FastMCP(name="weather")

# Define a tool using a decorator
# FastMCP automatically generates the schema from type hints and docstring
@mcp.tool()
def hello(name: str) -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"

# Start the server
if __name__ == "__main__":
    mcp.run()
```

**What's happening here:**

1. `FastMCP(name="weather")` - Creates a server instance. The name identifies your server to AI clients.

2. `@mcp.tool()` - This decorator registers the function as an MCP tool. The AI will see:
   - Function name → tool name
   - Type hints → parameter types
   - Docstring → tool description

3. `mcp.run()` - Starts listening for requests via **stdio** (standard input/output).

**What is stdio transport?**

Stdio means the server communicates through stdin/stdout - the same way command-line programs work. The AI client spawns your Python script and sends JSON messages through the pipe.

```
AI Client  ──stdin──►  Your Server
           ◄─stdout──
```

**Test it:**
```bash
uv run mcp dev server.py
```

This opens the MCP Inspector where you can call your `hello` tool.

Your First MCP Server (Minimal)

## Step 4: Adding a Real API Call

Now let's wrap an actual API. Replace `server.py`:

```python
import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP(name="weather")

@mcp.tool()
async def get_weather(city: str) -> dict:
    """
    Get current weather for a city.

    Args:
        city: City name like "London" or "New York"
    """
    # Create an async HTTP client
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.weatherapi.com/v1/current.json",
            params={
                "key": "YOUR_API_KEY",  # We'll fix this next
                "q": city
            },
            timeout=30.0  # Always set timeouts!
        )
        response.raise_for_status()  # Raises exception on 4xx/5xx
        return response.json()

if __name__ == "__main__":
    mcp.run()
```

**Key changes explained:**

1. **`async def` instead of `def`** - API calls are I/O-bound. Using async lets the server handle multiple requests without blocking.

   <aside>❌ **What happens if you use sync?** The server freezes during each API call. Other requests must wait.</aside>

2. **`async with httpx.AsyncClient()`** - Creates a connection pool. The `async with` ensures connections are properly closed.

   <aside>❌ **What happens without `async with`?** Connection leaks. Your server eventually runs out of sockets.</aside>

3. **`timeout=30.0`** - Prevents hanging forever if the API is slow.

   <aside>❌ **What happens without timeout?** A slow API can make your server unresponsive indefinitely.</aside>

4. **`raise_for_status()`** - Converts HTTP errors (404, 500, etc.) into Python exceptions.

   <aside>❌ **What happens without it?** You might return error HTML as if it were valid weather data.</aside>


Adding a Real API Call

## Step 5: Proper Configuration

Hardcoded API keys are dangerous. Let's fix that:

```python
import os
import httpx
from dotenv import load_dotenv
from mcp.server.fastmcp import FastMCP

# Load .env file at startup
load_dotenv()

# Get API key from environment
API_KEY = os.getenv("WEATHER_API_KEY")
if not API_KEY:
    raise ValueError("WEATHER_API_KEY environment variable is required")

mcp = FastMCP(name="weather")

@mcp.tool()
async def get_weather(city: str) -> dict:
    """Get current weather for a city."""
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.weatherapi.com/v1/current.json",
            params={"key": API_KEY, "q": city},
            timeout=30.0
        )
        response.raise_for_status()
        return response.json()

if __name__ == "__main__":
    mcp.run()
```

**Why check at startup?**

The `if not API_KEY: raise ValueError(...)` fails immediately when the server starts, not when someone first calls the tool. Fail fast = easier debugging.

Proper Configuration

## Step 6: Critical - Logging in MCP Servers

This is **the most common mistake** that breaks MCP servers:

```python
# ❌ WRONG - This breaks your server!
print("Debug message")

# ✅ CORRECT - Log to stderr
import sys
print("Debug message", file=sys.stderr)
```

**Why does `print()` break MCP?**

Remember stdio transport? The server uses stdout for JSON-RPC messages:

```
stdout: {"jsonrpc": "2.0", "result": {...}}  ← Valid message
stdout: Debug message                         ← Corrupts the stream!
stdout: {"jsonrpc": "2.0", "result": {...}}  ← AI can't parse this anymore
```

**Proper logging setup:**

```python
import sys
import logging

# Configure logging to stderr
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s",
    stream=sys.stderr  # Critical!
)
logger = logging.getLogger(__name__)

# Now use logger instead of print
logger.info("Server starting...")
logger.error("Something went wrong")
```

Critical - Logging in MCP Servers

## Step 7: Error Handling

APIs fail. Networks timeout. Let's handle it gracefully:

```python
@mcp.tool()
async def get_weather(city: str) -> dict:
    """Get current weather for a city."""
    try:
        async with httpx.AsyncClient() as client:
            response = await client.get(
                "https://api.weatherapi.com/v1/current.json",
                params={"key": API_KEY, "q": city},
                timeout=30.0
            )
            response.raise_for_status()

            data = response.json()
            # Return clean, structured data
            return {
                "city": data["location"]["name"],
                "temperature_c": data["current"]["temp_c"],
                "condition": data["current"]["condition"]["text"],
                "humidity": data["current"]["humidity"]
            }

    except httpx.TimeoutException:
        logger.error(f"Timeout fetching weather for {city}")
        return {"error": "Request timed out. Try again."}

    except httpx.HTTPStatusError as e:
        logger.error(f"HTTP {e.response.status_code} for {city}")
        if e.response.status_code == 400:
            return {"error": f"City '{city}' not found"}
        return {"error": f"API error: {e.response.status_code}"}

    except Exception as e:
        logger.exception("Unexpected error")  # Logs full traceback
        return {"error": "Something went wrong"}
```

**Why return errors as data instead of raising exceptions?**

MCP tools should return useful information even when things fail. The AI can then explain the error to the user. If you raise an exception, the AI just sees "tool failed."

Error Handling

Basic Implementation

## Step 8: Adding Resources

**Resources** are read-only data sources. Think of them as GET endpoints the AI can fetch anytime for reference information.

```python
@mcp.resource("weather://supported-cities")
def get_supported_cities() -> str:
    """List of cities with best weather data coverage."""
    cities = ["London", "New York", "Tokyo", "Paris", "Sydney"]
    return "\n".join(f"- {city}" for city in cities)
```

**How resources work:**

1. AI client calls `list_resources` → Server returns available resource URIs
2. AI decides it needs reference data → Calls `read_resource("weather://supported-cities")`
3. Server returns the content → AI uses it to inform its response

**When to use Resources vs Tools:**

| Use Resource when... | Use Tool when... |
|---------------------|------------------|
| Data is read-only | Action has side effects |
| Content rarely changes | Parameters affect output significantly |
| AI needs reference info | AI needs to "do" something |

The `weather://supported-cities` is a URI that identifies the resource. You can use any URI scheme you want.

Adding Resources

## Step 9: Adding Prompts

**What are prompts?**

Prompts are pre-written instruction templates that appear in the AI client's UI. Instead of users typing complex requests, they select a prompt from a menu and fill in the blanks.

**Visual example - How prompts appear in Claude Desktop:**

```
┌─────────────────────────────────────────┐
│  Claude Desktop                         │
├─────────────────────────────────────────┤
│  💬 Chat    📎 Files    📋 Prompts      │
│                         ─────────       │
│  Available from "weather" server:       │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │ 🌤️ travel_planner               │   │
│  │ Plan what to pack for a trip    │   │
│  └─────────────────────────────────┘   │
│  ┌─────────────────────────────────┐   │
│  │ 🌡️ compare_cities               │   │
│  │ Compare weather between cities  │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
```

**When user clicks "compare_cities":**

```
┌─────────────────────────────────────────┐
│  compare_cities                         │
├─────────────────────────────────────────┤
│                                         │
│  city1:  [ London         ]             │
│  city2:  [ Tokyo          ]             │
│                                         │
│         [ Use This Prompt ]             │
└─────────────────────────────────────────┘
```

**What the AI receives after user clicks "Use This Prompt":**

```
Compare the current weather between London and Tokyo:

1. Use get_weather tool for both cities
2. Show temperatures, humidity, and conditions side by side
3. Tell me which city has better weather right now
4. Explain why (temperature, rain chance, etc.)
```

**When to use prompts vs just letting users type:**

| Use Prompts when... | Don't bother when... |
|---------------------|----------------------|
| Task requires multiple steps | Task is simple ("get weather for Paris") |
| Users repeat the same complex request | Each request is unique |
| You want consistent output format | Format doesn't matter |
| Non-technical users need guidance | Users know what they want |

**Implementation:**

```python
@mcp.prompt()
def compare_cities(city1: str, city2: str) -> str:
    """
    Compare weather between two cities.

    Args:
        city1: First city to compare
        city2: Second city to compare
    """
    # This string is sent to the AI as instructions
    return f"""Compare the current weather between {city1} and {city2}:

1. Use get_weather tool for both cities
2. Show temperatures, humidity, and conditions side by side
3. Tell me which city has better weather right now
4. Explain why (temperature, rain chance, etc.)"""
```

**The key insight:** Prompts don't execute anything - they just generate instructions. The AI still needs to call your tools to actually get the weather data. Prompts are "smart shortcuts" for common multi-step tasks.

Adding Prompts

Advanced Features

## Step 10: Production Project Structure

A single `server.py` file works for learning, but production servers need proper organization.

**Why structure matters:**
- Easier to test individual components
- Teams can work on different parts
- Clearer separation of concerns
- Simpler to maintain and extend

**Recommended structure:**

```
mcp-weather/
├── src/
│   └── mcp_weather/
│       ├── __init__.py        # Package marker
│       ├── __main__.py        # Entry point (python -m mcp_weather)
│       ├── server.py          # MCP server setup only
│       ├── config.py          # Configuration management
│       ├── tools/
│       │   ├── __init__.py
│       │   └── weather.py     # Weather-related tools
│       ├── resources/
│       │   ├── __init__.py
│       │   └── cities.py      # City-related resources
│       └── prompts/
│           ├── __init__.py
│           └── templates.py   # Prompt templates
├── tests/
│   ├── __init__.py
│   ├── test_tools.py
│   └── test_server.py
├── .env                       # Local environment (git-ignored)
├── .env.example               # Template for .env
├── .gitignore
├── pyproject.toml
└── README.md
```

**Key files explained:**

- **config.py** - Centralized settings, environment validation
- **tools/** - Each domain gets its own file (weather.py, users.py, etc.)
- **resources/** - Read-only data sources
- **prompts/** - Instruction templates
- **server.py** - Only MCP registration, imports logic from other modules

Production Project Structure

## Step 11: Testing Locally

**Option 1: MCP Inspector**
```bash
uv run mcp dev server.py
```
Opens a web UI where you can:
- See all registered tools, resources, and prompts
- Call tools with test parameters
- View responses

**Option 2: Claude Desktop**

Add to your Claude config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-weather", "run", "server.py"],
      "env": {
        "WEATHER_API_KEY": "your_key",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

<aside>
💡 `PYTHONUNBUFFERED=1` prevents Python from buffering output, which can cause communication delays.
</aside>

Testing Locally

## Step 12: Production Deployment

**Stdio is for local development only.** For production, use **Streamable HTTP**.

**Why not stdio in production?**
- Only one client can connect at a time
- No network access (must run on same machine)
- No authentication mechanism

**Add HTTP transport support:**

```python
if __name__ == "__main__":
    import argparse

    parser = argparse.ArgumentParser()
    parser.add_argument("--http", action="store_true", help="Use HTTP transport")
    parser.add_argument("--port", type=int, default=8000)
    args = parser.parse_args()

    if args.http:
        # Production: HTTP transport with network access
        logger.info(f"Starting HTTP server on port {args.port}")
        mcp.run(transport="streamable-http", host="0.0.0.0", port=args.port)
    else:
        # Development: stdio for local testing
        logger.info("Starting stdio server")
        mcp.run()
```

**Run in HTTP mode:**
```bash
uv run server.py --http --port 8000
```

**Dockerfile for deployment:**

```dockerfile
FROM python:3.12-slim
WORKDIR /app

# Install uv package manager
RUN pip install uv

# Copy and install dependencies
COPY pyproject.toml .
RUN uv sync

# Copy server code
COPY server.py .

# Expose the port
EXPOSE 8000

# Run with HTTP transport
CMD ["uv", "run", "server.py", "--http", "--port", "8000"]
```

**Deploy to any cloud:** Fly.io, Railway, AWS, Google Cloud, or Cloudflare Workers.

Production Deployment

Production

## Common Mistakes to Avoid

| Mistake | Consequence | Solution |
|---------|-------------|----------|
| `print()` without `file=sys.stderr` | Breaks JSON-RPC communication | Always log to stderr |
| No timeout on HTTP requests | Server hangs indefinitely | Always set `timeout=` |
| Sync functions for I/O | Blocks entire server | Use `async def` |
| Hardcoded API keys | Security risk, can't change without code edit | Use environment variables |
| No error handling | Unhelpful "tool failed" messages | Return structured error data |
| Creating new HTTP client per request | Connection overhead, potential leaks | Reuse clients with `async with` |

Common Mistakes to Avoid

## Summary

You built an MCP server that:
- ✅ Wraps a Weather API with proper async handling
- ✅ Exposes **tools** (functions AI can call)
- ✅ Exposes **resources** (reference data AI can read)
- ✅ Exposes **prompts** (instruction templates for complex tasks)
- ✅ Handles errors gracefully
- ✅ Logs safely without breaking stdio communication
- ✅ Can deploy to production with HTTP transport

**Next steps:**
- Add caching to reduce API calls
- Implement rate limiting
- Add authentication for public deployments

Summary

Reference

How to Create an MCP Server in Python

Want a ready-to-use agent `.md` file that creates your MCP server automatically for just $5? Join the Wish List! If enough people are interested, I'll open this option.

Loading...

Vibki

How to Create an MCP Server in Python

Overview