Lesson 08 — A Multi-Tool Real Server

The full PKB: search, fetch, write, summarize — and how they compose.

MCP Servers Module 3

State of PKB after L07

• 3 tools: echo, search, summarize.
• 2 resources and 1 prompt.

Today: add fetch and write to finish the canonical tool set, then show composition.

The canonical PKB shape

Tool composition

Real-world tools rarely stand alone. The LLM chains them: search → fetch → summarize.

But sometimes you want the server to chain them — fewer round trips, atomicity, lower cost. That's tool composition at the server.

Example: summarize_and_save

@mcp.tool()
async def summarize_and_save(id: str, ctx: Context) -> str:
    summary = await summarize_via_sampling(id, ctx)
    new_title = f"{id}-summary"
    NOTES[new_title] = summary
    return f"saved: {new_title}"

One LLM-visible tool call, two state changes (sample + write).

When server composition is right

State management

PKB's NOTES dict is in-memory and process-local. Real servers persist state (SQLite, Postgres, filesystem, S3).

Migration sketch: swap the dict for a thin DAO exposing get / put / delete / list_titles — the tool signatures don't change.

write design

class WriteArgs(BaseModel):
    title: str = Field(..., min_length=1, max_length=120)
    body: str = Field(..., max_length=10_000)
    overwrite: bool = Field(False, description="allow replacing an existing note")

@mcp.tool()
def write(args: WriteArgs) -> str:
    if args.title in NOTES and not args.overwrite:
        raise McpError(ErrorData(code=INVALID_PARAMS,
            message=f"note exists: {args.title}; pass overwrite=true to replace"))
    NOTES[args.title] = args.body
    return f"saved: {args.title}"

fetch design

@mcp.tool()
def fetch(id: str) -> str:
    """Fetch one note's body by id."""
    if id not in NOTES:
        raise McpError(ErrorData(code=INVALID_PARAMS,
            message=f"unknown note id: {id}"))
    return NOTES[id]

Why is fetch(id) -> str a tool when pkb://notes/{title} already exposes the same data?

• Tool — the LLM can call it while reasoning.
• Resource — the client can pre-fetch and surface in a panel.

Both have their place; ship both.

Idempotency revisited

What we'll build today

• Add a fetch tool (returns the same data the resource does).
• Add a write tool with a Pydantic schema.
• Add a summarize_and_save composed tool.
• Test all three from Inspector and Claude Desktop.

Common gotchas

• Composed tool errors are confusing — log enough to know which sub-call failed.
• Mutating state without persistence means a restart wipes everything (call this out in the README).
• overwrite=true defaults are dangerous — default to False.

Recap & what's next

• PKB is now a real multi-tool server.
• Composition lives on the server when invariants demand it.
• Persistence is a separate concern from the protocol.