Sampling — Servers Asking the LLM

Why sampling matters

Imagine a travel server with a findBestFlight tool. It gathers 47 flight options from APIs — then needs LLM reasoning to balance price, layovers, and the user's preferences. Without sampling the server would have to ship an Anthropic/OpenAI key. With sampling it just asks the client via sampling/createMessage.

One-line version: Sampling lets servers borrow the user's LLM — never their API key.

A sampling request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      { "role": "user", "content": { "type": "text", "text": "Pick the best flight for a morning departure." } }
    ],
    "modelPreferences": {
      "hints": [{ "name": "claude-3-sonnet" }, { "name": "claude" }],
      "intelligencePriority": 0.8,
      "speedPriority": 0.5,
      "costPriority": 0.2
    },
    "systemPrompt": "You are a helpful travel agent.",
    "maxTokens": 200
  }
}

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "role": "assistant",
    "content": { "type": "text", "text": "I recommend AA1234 at 7:15am..." },
    "model": "claude-sonnet-4-6",
    "stopReason": "endTurn"
  }
}

Model preferences

Three priority axes guide model selection — each 0 to 1:

• costPriority — prefer cheaper models.
• speedPriority — prefer faster models.
• intelligencePriority — prefer more capable models.

The hints array is an ordered list of name substrings. Clients map them flexibly — if a user has no Claude access, a "claude-3-sonnet" hint might resolve to gemini-1.5-pro.

Context inclusion

includeContext controls what the client adds before calling the model:

• "none" — strictly the messages provided.
• "thisServer" — include context from the requesting server.
• "allServers" — include context from every connected MCP server.

Clients MAY override this field — they will refuse to leak sensitive cross-server data even if a server asks.

Sampling with tools (SEP-1577)

Servers can include tool definitions in sampling requests, then handle ToolUseContent blocks the model returns. This lets servers run multi-turn agentic loops while the client keeps approving each step.

Trust boundary: the user MUST be able to see and approve each sampling call. Servers don't get implicit access to the LLM.