Build your first MCP server in 30 minutes

By the end of this lab you will have a small but real Model Context Protocol (MCP) server running on your machine, exposing a tool that an AI client can call. Nothing here is a toy snippet — the code runs as-is.

What you're building: an AI app (client) talking to your tool (server) through MCP.

Before you start

You need Python 3.10+ and about 30 minutes. We use uv because it makes Python environments painless, but plain pip works too.

Set up the project

Create a folder and install the MCP SDK.

terminal

uv init weather-mcp
cd weather-mcp
uv add "mcp[cli]"

If you prefer pip: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Write the server

Create server.py. We expose one tool — a tiny "word stats" tool — so you can see the whole loop without external APIs.

server.py

from mcp.server.fastmcp import FastMCP

# The server's name shows up in the client.
mcp = FastMCP("word-tools")


@mcp.tool()
def word_stats(text: str) -> dict:
    """Return basic statistics about a piece of text.

    Args:
        text: The text to analyse.
    """
    words = text.split()
    return {
        "characters": len(text),
        "words": len(words),
        "longest_word": max(words, key=len) if words else "",
    }


if __name__ == "__main__":
    # Run over stdio — the transport MCP clients use locally.
    mcp.run()

That is the entire server. The @mcp.tool() decorator turns a normal Python function into something an AI client can call — the docstring and type hints become the tool's description and schema automatically.

Run and inspect it

The MCP Inspector is the fastest way to see your tool working — it gives you a UI to call the tool by hand.

terminal

uv run mcp dev server.py

This opens the Inspector in your browser. Open the Tools tab, pick word_stats, enter some text like the quick brown fox, and run it. You should get back character count, word count, and the longest word.

Connect it to a real client

To use it from a desktop AI client that speaks MCP, point its config at your server.

claude_desktop_config.json

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

Restart the client and ask it something like "use word-tools to get stats for this paragraph." It will call your tool and answer from the result.

Where to go next

Add a second tool that calls a real API (start with something keyless).
Read about resources and prompts — the other two MCP primitives.
Work through the full MCP course to take this to production: validation, security, and deployment.