Time: 20 minutes.
You will write an MCP server with one tool, fetch_event, run it, and call it
from the terminal. The finished code is in checkpoint_01_first_tool/server.py.
mkdir -p work
touch work/server.pyEverything you write in this workshop goes in work/. Git ignores it.
Open work/server.py and build it up in four small steps.
import os
import httpx2
from fastmcp import FastMCP
EPR_URL = os.environ.get("EPR_URL", "http://localhost:8042")fastmcpis the framework. This workshop uses FastMCP 4.httpx2is the HTTP client. It is a drop-in successor tohttpxwith the same API; only the package name changed. FastMCP 4 depends on it.EPR_URLcomes from the environment, so the same code works against any EPR.
mcp = FastMCP(name="EPR Workshop MCP Server", version="0.1.0")Pass name and version by keyword. The second positional parameter of
FastMCP is instructions, not the version, so
FastMCP("EPR Workshop MCP Server", "0.1.0") quietly sets the instructions to
"0.1.0". The shipped server had exactly this bug.
@mcp.tool(title="Fetch Event", description="Fetch an event from EPR by its ID")
async def fetch_event(id: str) -> str:
"""Fetch an event from the EPR."""
async with httpx2.AsyncClient() as client:
response = await client.get(f"{EPR_URL}/api/v1/events/{id}")
return response.textWhat FastMCP does with this:
- The decorator registers the function as a tool.
- The function name becomes the tool name.
- The type hints become a JSON schema, so an AI client knows
idis a string. descriptionis what the model reads to decide when to call the tool.async deflets the server wait for EPR without blocking.
if __name__ == "__main__":
mcp.run()mcp.run() serves over stdio by default: the host starts your script as a
subprocess and exchanges messages over its stdin and stdout. Because stdout is
the protocol channel, never print() in a tool. Write logs to stderr.
Starting the server directly looks like it hangs; it is waiting for an MCP client on stdin. Press Ctrl+C to stop it.
uv run python work/server.pyUse the workshop client instead. It starts your server the way an editor would, then talks to it:
uv run python client.py list work/server.pyYou should see:
fetch_event: Fetch an event from EPR by its ID
Now call the tool with an event ID from seed_ids.json:
uv run python client.py call work/server.py fetch_event '{"id": "PASTE_AN_EVENT_ID"}'You should see the event as JSON, starting with {"data":.
client.py listshowsfetch_event.client.py callreturns an event from EPR.- Behind schedule?
cp checkpoint_01_first_tool/server.py work/server.py.
- The tool returns EPR's raw response text. If the ID does not exist, you get EPR's error text back as if it were a normal answer. Modules 03 and 04 fix that.
- There is no
Contextargument and noctx.debug()logging. FastMCP 4 deprecates sending logs to the client through the protocol; use Python'sloggingmodule, which goes to stderr.
Next: 02 Inspector.