Building Tools with FastMCP: Servers, Tools, Resources, Prompts, Transports

Section 1: Why MCP Exists

Imagine a world without a shared protocol. You have N AI applications (Claude Desktop, Cursor, a custom agent) and M systems they want to reach (GitHub, Postgres, Drive). If every application needs a bespoke connector for every system, you owe N × M integrations, and every team rebuilds the same adapter slightly differently.

MCP collapses this to N + M. Each application implements the MCP client side once; each system is wrapped in an MCP server once; any client can then talk to any server. This is the move USB made for peripherals and the Language Server Protocol made for editors: a universal port replaces a combinatorial mess of adapters.

Host, Client, Server, Transport

• MCP host — the AI application that runs the model, manages communication, and hosts one or more clients (Claude Desktop, Cursor, a custom agent).
• MCP client — the connector inside the host that maintains a 1:1 session with a single server, handling protocol negotiation, capability discovery, and message routing. Three servers means three clients.
• MCP server — an independent program that exposes capabilities (tools, resources, prompts). This is usually what you build.
• Transport — the pipe over which client and server exchange messages. All communication uses JSON-RPC 2.0.

A useful analogy: the host is a restaurant dining room, the client is a waiter assigned to one kitchen, the server is a kitchen, and JSON-RPC is the standardized order-ticket format they all read. Swap in a new kitchen and the same waiters, tickets, and dining room work unchanged.

How MCP Relates to the Raw Tool-Use Primitive

In Chapter 1, a tool was a schema passed inline to the API, and your application executed it. With MCP, the tool definition and its execution move out of your application into a server any host can discover at runtime. The mechanics rhyme — a tool still has a name, description, and JSON input schema, and the model still decides when to call it — but ownership changes. The host's client asks the server "what tools do you have?" during capability discovery, translates them into the tool-use format the model understands, and relays invocations back. MCP is the raw tool-use primitive lifted into a decoupled, reusable, cross-application layer.

Section 2: A FastMCP Server From Scratch

Every server starts with a FastMCP instance, then decorates functions to expose them. This is a complete, valid MCP tool:

from fastmcp import FastMCP

mcp = FastMCP("Demo 🚀")

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

The magic is that FastMCP reads the signature and doc: the parameter names and type hints become the JSON input schema (send a string where an int is required and the framework rejects it before your code runs); the docstring becomes the description the model reads to decide when to call the tool; and the return annotation informs how results are structured. Your type hints and docstrings are not decoration — they are the API contract the model reads.

A richer tool shows async support and a structured docstring whose Args section clarifies each parameter, drawn from the official quickstart with the SDK-bundled FastMCP:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    # ... call an upstream weather API here ...
    return "No active alerts."

Running and Inspecting the Server

A server needs an entry point that starts the transport. The canonical local pattern runs over stdio; run it with uv run weather.py. The recommended toolchain is uv (Python 3.10+, MCP SDK 1.2.0+ or the standalone fastmcp).

def main():
    mcp.run(transport="stdio")

if __name__ == "__main__":
    main()

Before wiring a server into a real host, test it in isolation. The MCP Inspector is a web-based tool that connects to a running server and lets you interactively list and invoke its tools, read its resources, and render its prompts. FastMCP integrates it through the CLI with fastmcp dev server.py, giving a tight click-a-tool, fill-args, see-the-result loop that beats round-tripping through Claude Desktop for every change.

On return handling: because FastMCP knows your return annotation, it serializes results into structured output automatically. Returning a plain int, str, or dict produces a well-typed tool result the client can present to the model. You focus on returning meaningful Python; the framework handles the wire format.

Section 3: Resources and Prompts

A resource is read-only, file-like data identified by a URI that the host application decides to load into context: file contents, configuration, documentation, or an API response. Resources have no side effects — where a tool does something, a resource merely provides something to read. A static resource returns data at a fixed URI:

@mcp.resource("resource://greeting")
def get_greeting() -> str:
    return "Hello from FastMCP Resources!"

Real context is rarely one fixed blob. Resource templates embed path parameters, so a single function serves an entire family. A request for weather://london/current calls get_weather("london"):

import json

@mcp.resource("weather://{city}/current")
def get_weather(city: str) -> str:
    return json.dumps({"city": city, "temperature": 22})

Table 3.1: Resource URI patterns supported by @mcp.resource.

@mcp.prompt — Reusable Parameterized Templates

A prompt template is a reusable, parameterized message template the user deliberately invokes — typically via a slash command or menu — to start a structured interaction. It captures your best-known phrasing for a recurring task.

@mcp.prompt
def summarize_pr(diff: str, tone: str = "concise") -> str:
    """Draft a pull-request summary from a diff."""
    return (
        f"Write a {tone} pull-request summary for the following diff. "
        f"Group changes by theme and flag any breaking changes.\n\n{diff}"
    )

The user picks summarize_pr from a menu, supplies the diff (optionally overriding tone), and the server returns the fully assembled message that seeds the conversation.

The Control Spectrum

Table 3.2: The MCP control spectrum.

Getting this taxonomy right prevents a common mistake: exposing a data read as a tool (needlessly handing the model control over context loading the application should own), or hiding a genuine action inside a resource (silently breaking the "no side effects" contract that lets hosts load resources freely).

Section 4: Transports — stdio vs. HTTP

With the stdio transport, the client launches the MCP server as a subprocess; the server reads newline-delimited JSON-RPC from stdin and writes to stdout (no embedded newlines). One rule dominates: the server MUST NOT write anything to stdout that is not a valid MCP message — a stray print() corrupts the stream. Logging goes to stderr. A mysteriously dead stdio server is almost always a rogue print to stdout. Characteristics: ultra-low latency (~1 ms, no network hop), one subprocess per client, and a client-owned lifecycle. Scaling means running more processes.

mcp.run(transport="stdio")

The streamable HTTP transport runs an independent, long-lived server that can serve many clients over a single endpoint (e.g., https://example.com/mcp) supporting POST and GET. The client POSTs each JSON-RPC message with an Accept header listing both application/json and text/event-stream; the server responds with a single JSON object or an SSE stream. Posted responses/notifications get 202 Accepted. A client MAY issue a GET to open a standalone SSE stream so the server can push messages. Sessions use an MCP-Session-Id header (missing → 400, terminated → 404, DELETE to end); resumability uses SSE event id plus Last-Event-ID replay. Security: MUST validate Origin (403 if invalid), SHOULD authenticate, SHOULD bind to 127.0.0.1 locally.

mcp.run(transport="http", host="127.0.0.1", port=8000)
# "streamable-http" is also accepted

Table 3.3: stdio versus Streamable HTTP — a decision matrix.

An analogy: stdio is a chef you hire to cook in your kitchen — instant, private, and you turn the lights on and off. Streamable HTTP is a restaurant across town — reachable by anyone with the address, always open, but you need a reservation system (sessions), a bouncer checking IDs (Origin validation and auth), and the ability to seat many parties at once.

For a local stdio deployment, register the server with the host and tell it how to launch the subprocess. For Claude Desktop, add an entry under mcpServers in claude_desktop_config.json (with the absolute path to the working directory and to uv), then restart the host. For remote/production, switch to Streamable HTTP and host it as a long-lived service (a PyPI package via CI/CD, or a Docker container), with production hardening: Origin validation, authentication, localhost binding when appropriate, input/path validation, rate limiting, and audit logging. A remote client connects to the endpoint URL rather than spawning a process — the same tools, resources, and prompts appear identically; only the pipe changed.