DEV Community

Cover image for Building Your First MCP Server in Python: A Practical 2026 Guide
ElysiumQuill
ElysiumQuill

Posted on

Building Your First MCP Server in Python: A Practical 2026 Guide

#ai #python #tutorial #webdev

Every few years, a new protocol emerges that quietly reshapes how developers build tools. In 2026, Model Context Protocol (MCP) is that protocol — and if you haven't started integrating it yet, you're already behind.

This guide breaks down what MCP actually is, why it matters for everyday developers, and how to build your first MCP server in under 30 minutes.

What Is MCP (And Why Should You Care)?

MCP, or Model Context Protocol, is an open standard introduced by Anthropic that defines how AI models can interact with external tools, data sources, and APIs in a structured, interoperable way.

Think of it as USB-C for AI integrations: before USB-C, every device had its own charging standard. MCP does the same for AI — instead of every LLM integration being custom-built, MCP provides a universal layer.

Before MCP:

  • You had to write custom tool integrations for each LLM
  • Switching models meant rewriting your toolchain
  • Security and access controls were ad hoc

With MCP:

  • Write one server, connect to any MCP-compatible client
  • Standards-based tool definitions (JSON Schema)
  • Built-in transport options (stdio, HTTP+SSE)

The MCP Architecture at a Glance

MCP defines three core concepts:

1. Servers

An MCP server exposes capabilities — tools, resources, and prompts — to clients. Your server might expose:

  • A read_file tool that reads from a specific directory
  • A search_db tool that queries your database
  • A get_context resource that injects relevant project docs

2. Clients

An MCP client is the AI-powered application (Claude Desktop, Cursor, your custom app) that connects to servers and uses their capabilities during inference.

3. Transports

Communication happens via stdio (local processes) or HTTP + Server-Sent Events (remote servers). This separation makes MCP both locally embeddable and cloud-deployable.

Building Your First MCP Server (Python)

Let's build a simple MCP server that exposes a get_weather tool. We'll use the official mcp Python SDK.

Step 1 — Install the SDK 

pip install mcp httpx
Enter fullscreen mode Exit fullscreen mode

Step 2 — Create the Server 

# weather_server.py
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent
import httpx

app = Server("weather-server")

@app.list_tools()
async def list_tools():
    return [
        Tool(
            name="get_weather",
            description="Get current weather for a city",
            inputSchema={
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name (e.g., Paris, Tokyo)"
                    }
                },
                "required": ["city"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_weather":
        city = arguments["city"]
        # Using Open-Meteo (free, no API key needed)
        geo_url = f"https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1"
        async with httpx.AsyncClient(timeout=5.0) as client:
            geo_res = await client.get(geo_url)
            geo_data = geo_res.json()

            if not geo_data.get("results"):
                return [TextContent(type="text", text=f"City '{city}' not found")]

            lat = geo_data["results"][0]["latitude"]
            lon = geo_data["results"][0]["longitude"]

            weather_url = (
                f"https://api.open-meteo.com/v1/forecast"
                f"?latitude={lat}&longitude={lon}"
                f"&current=temperature_2m,wind_speed_10m"
            )
            weather_res = await client.get(weather_url)
            weather = weather_res.json()["current"]

            temp = weather["temperature_2m"]
            wind = weather["wind_speed_10m"]

            return [TextContent(
                type="text",
                text=f"Weather in {city}: {temp}°C, wind {wind} km/h"
            )]

if __name__ == "__main__":
    import asyncio
    asyncio.run(stdio_server(app))
Enter fullscreen mode Exit fullscreen mode

Step 3 — Test It With the MCP Inspector 

npx @modelcontextprotocol/inspector python weather_server.py
Enter fullscreen mode Exit fullscreen mode

This opens a browser-based UI where you can invoke your tools manually and inspect the JSON messages exchanged between client and server.

Connecting to Claude Desktop

Once your server works locally, register it in Claude Desktop's config:

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

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/path/to/weather_server.py"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Restart Claude Desktop. The weather tool is now available in every conversation. Claude will call it automatically when you ask something like "What's the weather in Tokyo right now?"

Resources: The Other Half of MCP

Tools handle actions. Resources handle context injection — structured data that an AI can read before responding.

Example: expose your project's README as a resource:

from mcp.types import Resource

@app.list_resources()
async def list_resources():
    return [
        Resource(
            uri="file:///project/README.md",
            name="Project README",
            description="Main project documentation",
            mimeType="text/markdown"
        )
    ]

@app.read_resource()
async def read_resource(uri: str):
    if uri == "file:///project/README.md":
        with open("/project/README.md") as f:
            return f.read()
Enter fullscreen mode Exit fullscreen mode

This pattern is powerful for building AI assistants that have deep knowledge of your specific codebase, internal docs, or domain data — without any fine-tuning.

Common Pitfalls to Avoid

1. Skip input validation at your peril

MCP tools receive raw LLM-generated input. Always validate arguments before using them in file paths, SQL queries, or API calls.

import re

def validate_city(city: str) -> str:
    if not re.match(r"^[a-zA-Z\s\-]+$", city):
        raise ValueError("Invalid city name")
    return city.strip()[:100]
Enter fullscreen mode Exit fullscreen mode

2. Async timeouts matter

External API calls can hang indefinitely. Set explicit timeouts:

async with httpx.AsyncClient(timeout=5.0) as client:
    ...
Enter fullscreen mode Exit fullscreen mode

3. Stdio vs HTTP — choose the right transport

  • Stdio: Simplest option for local dev tools. The server runs as a child process.
  • HTTP+SSE: Needed for multi-client scenarios, cloud deployments, or long-running servers.

4. Log to stderr, not stdout

In stdio mode, stdout is the MCP protocol channel. Logs must go to stderr:

import sys
print("[DEBUG] Tool called", file=sys.stderr)
Enter fullscreen mode Exit fullscreen mode

Real-World MCP Use Cases in 2026

The ecosystem has grown rapidly since MCP's release. Here's what developers are shipping:

Use Case What It Does
Code context servers Feed entire repos to AI (Cursor, VS Code Copilot)
Database agents Natural language queries over Postgres/SQLite
Internal wikis Connect Confluence/Notion to Claude
Git integration PR review bots with live repo access
Log analysis Real-time log search for on-call AI assistants
IoT dashboards Control physical devices via AI-driven MCP tools

If you scan GitHub right now, MCP server repositories are growing at a pace reminiscent of npm in 2015. It's early, the tooling is rough in places, but the upside is enormous.

What's Coming Next

The MCP spec is at v0.6 as of April 2026, with active work on:

  • Auth standards — OAuth 2.0 flows for secure remote server access
  • Multi-server composition — connecting AI to dozens of servers simultaneously
  • Observability — tracing, logging, and monitoring for production MCP deployments
  • Typed schemas — tighter integration with OpenAPI and JSON Schema for richer tool definitions

The community is also building a public MCP server registry — essentially npm for AI tools — which could dramatically accelerate adoption.

Getting Started

If you want to go further after this tutorial:

Wrapping Up

MCP isn't a hype cycle or a research prototype. It's a practical engineering standard that makes AI integrations more composable, portable, and maintainable. Understanding it in 2026 is fast becoming a baseline expectation for developers building anything AI-adjacent.

The weather server above takes about 30 minutes to build. From there, the same pattern scales to any API, database, or file system you want to expose to an AI model.

What's the first MCP server you'd build for your workflow? Leave a comment — always curious to see what the community is working on.

Top comments (0)