Lesson 07 — Sampling & Elicitation

The server asks the LLM. The server asks the user. Both need consent.

MCP Servers Module 3

The inversion

Sampling: what it is

A tool can request the client's LLM to generate a completion mid-execution. The server doesn't hold the API key — the client does. The server says "summarize this", the client routes the request through its own LLM, and returns the result.

Cost lives with the user, not the server operator. Their tokens, their consent.

Why sampling matters

• Server-side reasoning without server-side LLM keys.
• Portable across clients — Claude Desktop, Cursor, Codex CLI — each routes through its own model.
• A tool can chain LLM calls without the user re-prompting.
• One budget, one consent path — the user's.

The sampling API

from mcp.server.fastmcp import Context
from mcp.types import SamplingMessage, TextContent

@mcp.tool()
async def summarize(id: str, ctx: Context) -> str:
    """Summarize a note via the client's LLM."""
    body = NOTES[id]
    result = await ctx.session.create_message(
        messages=[SamplingMessage(
            role="user",
            content=TextContent(type="text", text=f"Summarize in 2 sentences:\n\n{body}"),
        )],
        max_tokens=200,
    )
    return result.content.text

ctx.session.create_message is the server-initiated LLM call.

Cost & consent risks

Elicitation: what it is

A tool can request structured input from the user mid-execution. Example: pkb.write_note mid-call asks "what title?" if the LLM didn't pass one.

The client surfaces a form; the user fills it; the value comes back to the server. Nothing is guessed and nothing is silently defaulted.

The elicitation API (preview)

from mcp.types import ElicitationSchema

result = await ctx.session.elicit(
    message="Pick a title for the new note:",
    requested_schema={
        "type": "object",
        "properties": {"title": {"type": "string"}},
        "required": ["title"],
    },
)
title = result.content["title"] if result.action == "accept" else None

The client owns the UX; the server only declares the shape it needs.

When sampling vs elicitation

What we'll build today

• Add a pkb.summarize(id) tool that uses ctx.session.create_message to summarize a note via sampling.
• Verify in Inspector that the sampling request shows up and routes through the client.
• Observe the consent dialog in Claude Desktop the first time the tool samples.

Common gotchas

• Forgot ctx: Context parameter → no access to the session.
• Sampling response has .content.text, not .text.
• Sampling can timeout or be rejected by the client — handle the error path.
• Running sampling outside an async def tool — create_message is async.

Recap & what's next

• Sampling = server → LLM (via client).
• Elicitation = server → user (via client).
• Both need consent and caps.