Lesson 04 — Your First MCP Server

From an empty server to a callable tool, in one sitting.

MCP Servers Module 2

One tool: pkb.echo

By the end of this lesson the PKB server exposes a single tool — pkb.echo(message: str) -> str — that returns the message right back to the caller. Both the MCP Inspector and Claude Desktop can call it, and you'll watch the round-trip from both sides.

It's a deliberately tiny tool. The point isn't what echo does; the point is that you wire up everything around it — project, entry point, client config — without any moving parts you can't see.

The shape of an MCP tool

Every tool the protocol exposes carries the same four pieces of metadata:

• Name — the string the client uses in tools/call.
• Description — one or two sentences of natural language the LLM reads to decide whether to use it.
• JSON-Schema input — the contract for arguments. The client validates against it before sending.
• Return type — one or more content blocks (text, image, resource). For now: a single TextContent.

This is exactly what the tools/list response from Lesson 02 returned — one entry per tool, with those four fields.

FastMCP for ergonomic tools

@mcp.tool()
def echo(message: str) -> str:
    """Echo the message back."""
    return message

FastMCP introspects the function's type hints and docstring to build the schema. The parameter name and type become the inputSchema; the docstring becomes the tool description; the function name becomes the tool name. Four metadata fields, derived from four pieces of Python you'd be writing anyway.

Wiring FastMCP into pkb/server.py

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("pkb", version="0.1.0")

@mcp.tool()
def echo(message: str) -> str:
    """Echo the message back."""
    return message

def main() -> None:
    mcp.run()

This replaces the placeholder server.py you scaffolded in Lesson 03 — same file, same main() entry point, but now there's an actual tool behind it.

Wiring up Claude Desktop config

{
  "mcpServers": {
    "pkb": { "command": "pkb" }
  }
}

The pkb binary came from [project.scripts] in pyproject.toml (set up in Plan A Task 4) — pip install -e . drops it onto your PATH. Restart Claude Desktop after editing the config and PKB shows up in the tools panel, ready to call.

Calling the tool from Claude Desktop

• Ask Claude: "use the pkb echo tool with message hello world".
• Watch the tool-call card unfold: tool name, arguments, raw response.
• Watch the natural-language wrapper Claude builds around the raw "hello world".

Same tool through MCP Inspector

mcp dev pkb/server.py

• One command boots your server and the Inspector pointed at it.
• Pick echo from the tools list in the left rail.
• Call it with message="ping" from the arguments form.
• See the TextContent block come back — the same payload Claude Desktop would have received, just rendered as raw JSON.

What just happened on the wire

Recap the Lesson 02 lifecycle for this one call:

1. The client connected over stdio and sent initialize; the server replied with its capabilities.
2. The client called tools/list — the response included an entry for echo with its schema.
3. The client called tools/call with {name: "echo", arguments: {message: "ping"}}.
4. The server returned a content block: [{type: "text", text: "ping"}].

Same JSON-RPC envelopes you traced by hand in Lesson 02 — just produced by your code instead of read from a transcript.

Error handling preview

Common gotchas

• Forgot pip install -e . after editing — Claude Desktop keeps running the old pkb binary from the last install, and your new tool never shows up.
• Forgot to restart Claude Desktop after editing the config — mcpServers is read at startup, not live-reloaded. No restart, no PKB in the panel.
• Tool name collisions — if multiple servers in mcpServers expose a tool with the same name, the client has to disambiguate, and you'll see confusing behaviour until you rename one.

Recap & what's next

• FastMCP makes tools cheap — a decorator, a type hint, a docstring, and you have a fully described tool on the wire.
• Claude Desktop config + [project.scripts] connect the dots — the JSON config points at a binary that pip install -e . put on your PATH.
• The wire format is the same JSON-RPC from Lesson 02 — FastMCP is sugar over the same envelopes you already know.