Model Context Protocol (MCP) is Anthropic’s open standard for giving LLMs access to external tools and data sources. Instead of hardcoding tool integrations into your app, you build an MCP server that exposes tools — and any MCP-compatible client (Claude Desktop, Cursor, custom agents) can use them without extra glue code.

This guide walks through building a working MCP server in Python from scratch, connecting it to Claude Desktop, and writing tools with proper input validation and error handling.

What You’re Building

An MCP server is a small process that runs locally (or remotely) and communicates with an LLM client over a standard protocol. The client discovers what tools your server exposes, the LLM decides when to call them, and your server executes the logic and returns results.

You define tools in Python using the FastMCP class from the official SDK. Type hints and docstrings automatically generate the JSON schema that the client uses to understand each tool.

Environment Setup

You need Python 3.10+ and uv (the fast Python package manager). If you don’t have uv yet:

1

curl -LsSf https://astral.sh/uv/install.sh | sh

Create a new project directory and install dependencies:

1
2
3
4
5

uv init my-mcp-server
cd my-mcp-server
uv venv
source .venv/bin/activate
uv add "mcp[cli]"

The mcp[cli] package includes FastMCP, the high-level wrapper, plus command-line tools for installing your server into Claude Desktop. Use SDK version 1.2.0 or higher — earlier versions lack several FastMCP features.

Your First Tool

Create server.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

import sys
import logging
from mcp.server.fastmcp import FastMCP

# IMPORTANT: For STDIO-based servers, never print to stdout.
# Stdout carries the JSON-RPC messages. Use stderr for logging.
logging.basicConfig(stream=sys.stderr, level=logging.INFO)
logger = logging.getLogger(__name__)

mcp = FastMCP("my-tools")


@mcp.tool()
def add_numbers(a: float, b: float) -> float:
    """Add two numbers together.

    Args:
        a: The first number
        b: The second number
    """
    return a + b


@mcp.tool()
def word_count(text: str) -> dict:
    """Count words, characters, and lines in a block of text.

    Args:
        text: The text to analyze
    """
    words = len(text.split())
    chars = len(text)
    lines = text.count("\n") + 1 if text else 0
    return {"words": words, "characters": chars, "lines": lines}


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

FastMCP reads the function signature and docstring to generate the tool schema automatically. The Args: section in the docstring becomes the parameter descriptions in the schema — this is what the LLM sees when deciding how to call your tool.

Test it immediately using the MCP inspector:

1

uv run mcp dev server.py

This starts the inspector at http://localhost:5173. You can call tools manually and see the JSON-RPC messages flowing, which is invaluable for debugging before you wire up a real client.

Connecting to Claude Desktop

Claude Desktop reads server configurations from a JSON file. Open (or create) the config file:

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

Add your server:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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

Replace /absolute/path/to/my-mcp-server with the actual path — run pwd in your project directory to get it. Relative paths don’t work here.

Restart Claude Desktop completely (Cmd+Q on macOS, not just close the window). Once restarted, click the attachment icon in the chat input. You should see your server listed under “Connectors.” If it doesn’t appear, check ~/Library/Logs/Claude/mcp-server-my-tools.log for errors.

Alternatively, let the MCP CLI handle the config for you:

1

uv run mcp install server.py --name "my-tools"

This writes the config entry automatically and is less error-prone.

Input Validation with Pydantic

For tools that accept complex inputs, use Pydantic models. FastMCP generates the full JSON schema including field descriptions and constraints:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

import logging
import sys
from pydantic import BaseModel, Field
from mcp.server.fastmcp import FastMCP

logging.basicConfig(stream=sys.stderr, level=logging.INFO)
logger = logging.getLogger(__name__)

mcp = FastMCP("my-tools")


class SearchQuery(BaseModel):
    query: str = Field(..., min_length=1, max_length=500, description="Search terms")
    max_results: int = Field(default=10, ge=1, le=100, description="Number of results to return")
    language: str = Field(default="en", pattern=r"^[a-z]{2}$", description="ISO 639-1 language code")


@mcp.tool()
def search_documents(params: SearchQuery) -> list[dict]:
    """Search an internal document corpus.

    Args:
        params: Search parameters including query, result count, and language
    """
    logger.info(f"Searching for '{params.query}' in {params.language}, max {params.max_results} results")

    # Your actual search logic goes here
    # This is a stub that returns sample data
    return [
        {
            "id": f"doc_{i}",
            "title": f"Result {i} for '{params.query}'",
            "score": round(0.9 - i * 0.05, 2),
            "language": params.language,
        }
        for i in range(min(3, params.max_results))
    ]

Pydantic validators run before your function body executes. If the LLM passes an invalid value — say max_results: 500 when the max is 100 — the validation error surfaces in the tool call result and the LLM can correct its input.

Async Tools and External API Calls

Tools can be async. Use this for anything that does I/O — HTTP requests, database queries, file reads:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

import httpx
# mcp and logger are already defined from earlier in your server.py

GITHUB_API = "https://api.github.com"


@mcp.tool()
async def get_github_repo_info(owner: str, repo: str) -> dict:
    """Fetch public metadata for a GitHub repository.

    Args:
        owner: GitHub username or organization name
        repo: Repository name
    """
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(
                f"{GITHUB_API}/repos/{owner}/{repo}",
                headers={"Accept": "application/vnd.github+json"},
                timeout=10.0,
            )
            response.raise_for_status()
            data = response.json()
            return {
                "full_name": data["full_name"],
                "description": data.get("description", ""),
                "stars": data["stargazers_count"],
                "forks": data["forks_count"],
                "language": data.get("language", ""),
                "open_issues": data["open_issues_count"],
                "url": data["html_url"],
            }
        except httpx.HTTPStatusError as e:
            return {"error": f"GitHub API returned {e.response.status_code}"}
        except httpx.TimeoutException:
            return {"error": "Request timed out after 10 seconds"}

Return structured data as dicts or lists — FastMCP serializes them to JSON for the client. For errors, returning a dict with an "error" key is the pattern most clients expect. Raising exceptions works too but gives the LLM less context about what went wrong.

Connecting to Other MCP Clients

Claude Desktop is the easiest starting point, but MCP clients exist for other environments. The configuration format is consistent across them:

Cursor: Edit .cursor/mcp.json in your project root:

1
2
3
4
5
6
7
8

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

Custom Python agent using the MCP client library:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client


async def use_mcp_tools():
    server_params = StdioServerParameters(
        command="uv",
        args=["--directory", "/absolute/path/to/my-mcp-server", "run", "server.py"],
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print("Available tools:", [t.name for t in tools.tools])

            # Call a tool directly
            result = await session.call_tool("add_numbers", {"a": 3.5, "b": 1.2})
            print("Result:", result.content[0].text)


asyncio.run(use_mcp_tools())

This is useful for integration tests or building agents that call your MCP server programmatically.

Debugging Tips

The server starts but no tools appear in Claude: Usually a path issue or syntax error in server.py. Run uv run server.py directly from your terminal — any Python errors will show immediately. Also check the MCP log file mentioned above.

“Command not found: uv”: Claude Desktop may not inherit your shell’s PATH. Use the full path to uv instead:

1
2
3
4
5
6
7
8

{
  "mcpServers": {
    "my-tools": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": ["--directory", "/absolute/path/to/my-mcp-server", "run", "server.py"]
    }
  }
}

Run which uv in your terminal to get the full path.

Tools fail silently: Check that you’re not writing to stdout anywhere in your server code. print() statements corrupt the STDIO transport. Use print("...", file=sys.stderr) or the logging module instead.

Pydantic validation errors: The MCP inspector (uv run mcp dev server.py) shows the full JSON-RPC exchange including error details. Run it, call the failing tool, and read the error message in the response.

What to Build Next

Once the basics work, useful directions include:

  • Resources: Expose file contents or database records as readable resources (not just callable tools)
  • Prompts: Pre-built prompt templates the LLM can request from your server
  • SSE transport: Switch from stdio to HTTP+SSE for servers that multiple clients share simultaneously
  • Authentication: Add API keys via environment variables in the Claude Desktop config’s "env" section

The MCP ecosystem is moving fast — check the official Python SDK at github.com/modelcontextprotocol/python-sdk for new features. The core protocol is stable but FastMCP is still adding conveniences.