How do you build your first MCP server?

The Model Context Protocol (MCP) is an open standard that lets an AI assistant use outside data and actions through small programs called servers. The assistant side, such as Claude Desktop, is the client. A server can offer three kinds of things: tools (actions the model can ask to run), resources (data it can read) and prompts (reusable templates). Most people start with a tool, because it is the easiest way to give an assistant a new ability.

You don't need much code. The official Python SDK includes FastMCP, a helper that turns a normal Python function into an MCP tool. The function's name becomes the tool name, its type hints describe the inputs, and its docstring (the text in triple quotes) becomes the description the model reads when deciding whether to use it.

What you need

• A recent Python and uv, a fast Python project manager that the SDK's README recommends. (Plain pip install mcp also works.)
• A text editor and a terminal.
• Node.js, only if you want to run the Inspector on its own with npx.
• Claude Desktop, if you want to connect the finished server to an assistant.

Step by step: a "days until" tool

Our server will answer one question that language models often get wrong: how many days remain until a given date. A model can't reliably know today's date or count calendar days; a three-line function can.

1. Create the project and add the SDK.

uv init days-server
cd days-server
uv add "mcp[cli]"

The [cli] part installs the mcp command-line tool you'll use for testing.

2. Write server.py.

# server.py
from datetime import date
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Days Until")

@mcp.tool()
def days_until(target: str) -> str:
    """Count the days from today until a date given as YYYY-MM-DD.
    Returns a negative number if the date has passed."""
    try:
        when = date.fromisoformat(target)
    except ValueError:
        return "Please give the date as YYYY-MM-DD, for example 2025-12-25."
    delta = (when - date.today()).days
    return f"{delta} days from {date.today().isoformat()} to {target}."

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

Three details matter. The docstring is written for the model, so it says exactly what the input format is. Bad input returns a helpful message instead of crashing, so the model can correct itself. And the function does one job, which makes it easy to test.

3. Test it with the Inspector (next section).

4. Connect it to Claude Desktop.

uv run mcp install server.py

This registers the server with Claude Desktop, which keeps its list of MCP servers in a file called claude_desktop_config.json. Quit Claude Desktop fully and reopen it; it connects to servers at startup. Then ask "How many days until December 25?" and Claude should offer to call days_until. Claude Desktop asks you to confirm before sensitive operations, and the server runs only on your own computer.

If something goes wrong

• The tool doesn't appear in Claude Desktop. Make sure you quit the app completely, not just closed the window. Its logs (on a Mac, in ~/Library/Logs/Claude/ in files starting with mcp) show whether the server started.
• The server starts but the tool fails. Run it in the Inspector and read the error message there; it is much quicker than testing through a chat.
• The model never calls your tool. Improve the docstring. Say plainly what the tool does and when to use it.

How do you test it before connecting it to an assistant?

Use the MCP Inspector, the official tool for checking and debugging a server while you build it. It acts as a client, connects to your server and shows you exactly what an assistant would see: the list of tools, their descriptions and input fields, and the raw results. Because no language model is involved, you test your code alone, without wondering whether the model misunderstood.

The SDK starts the Inspector for you:

uv run mcp dev server.py

The command launches your server together with the Inspector, which runs a small web page in your browser (by default on port 5173) and a local proxy that talks to your server (port 3000 by default). Open the address it prints, connect, and list the tools. You should see days_until with the docstring you wrote. Run it with a valid date, then with something wrong like 25/12/2025, and check that you get your friendly error message rather than a crash.

If your server is written in another language, or you want to run the Inspector on its own, start it with npx @modelcontextprotocol/inspector followed by the command that launches your server; you can pass environment variables with -e KEY=value. One safety note from the Inspector's README: its proxy can start programs on your machine, so keep it on your own computer and never expose it to an untrusted network.

A good habit is to keep a short list of test inputs (a normal case, an edge case such as today's date, and a bad input) and run them in the Inspector every time you change the server. Only when all three behave as you expect is it worth connecting the server to an assistant.