What is MCP sampling?
MCP sampling lets an MCP server ask the client to run a language model on its behalf, using the client's own model access and keys, with a person able to review and refuse each request. As of the 2026-07-28 revision the feature is deprecated: new servers should call a model provider's API directly instead.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
The client declares the sampling capability in each request's _meta. A server must not ask for completions from a client that has not declared it.
While handling a tools/call, the server needs model output. It returns an InputRequiredResult carrying a sampling/createMessage request: messages and maxTokens.
{ "resultType": "input_required", "inputRequests": { "summary": { "method": "sampling/createMessage", "params": { "messages": [], "maxTokens": 400 } } } }The client shows the request to the person, who can edit or refuse it, then calls its own model with its own credentials. The server never sees a key.
The client retries the original tools/call with the model's reply (role, content, model name, stopReason) in inputResponses, and the server finishes its work.
If the server supplied tools and the model asks to use one, the server runs it and sends another sampling request with the result, until stopReason is endTurn.
Source: MCP specification: sampling
Sampling versus calling a provider directly
Most MCP traffic flows one way: the client asks, the server answers. Sampling reverses it. A server that needs a model, say to summarise a document before returning it, asks the client to generate the text instead of calling a provider itself. The appeal was that a server could be shipped without any model credentials, and the person running the client would see and approve every generation.
The cost is latency, complexity and a long approval chain. Every sampling request is a full round trip through the client, possibly through a human, and back. In 2026-07-28 the maintainers deprecated the feature (SEP-2577) and gave a migration path in one line: integrate directly with LLM provider APIs. If you are starting a server today, that is the answer. If you maintain one that samples, you have a window of at least twelve months before removal becomes possible.
Example: a summary inside a tool call
A client calls a summarise_thread tool. The server has the thread but no model. In the 2026-07-28 shape it replies with an InputRequiredResult whose inputRequests map holds a sampling/createMessage entry: a user message containing the thread, a systemPrompt, maxTokens: 400, and modelPreferences with a speedPriority of 0.8 and a hint such as {"name": "claude"}. Hints are substrings, evaluated in order, and advisory; a client without that family may map the hint to another provider's equivalent.
The client shows the prompt to the person, who can edit it or say no. It then runs its own model and retries the tool call with the result in inputResponses: a role of assistant, the content, the model name actually used, and a stopReason such as endTurn, maxTokens or stopSequence. The server now has its summary and returns the tool result. If the person declines, the client simply does not retry; the server is not left waiting.
This is a change from 2025-11-25, where the server sent sampling/createMessage as its own JSON-RPC request over the open connection. Servers no longer initiate requests at all; everything a server wants from the client travels inside a result.
Why it matters, and why it is going away
Sampling is the clearest example of MCP's human-in-the-loop stance. The spec says there should always be a person able to deny a sampling request, review the prompt before it is sent, and review the output before it is delivered. Clients may rewrite or drop the systemPrompt, temperature, stopSequences and metadata without telling the server; only maxTokens must be respected. The includeContext values thisServer and allServers, which asked the client to add context from connected servers, are deprecated too and default to none.
Those same properties made sampling hard to rely on. A server could not know which model would answer, whether its system prompt survived, or how long approval would take. Direct provider calls give a server a predictable model and no approval queue, at the price of holding a key.
Common mistakes
- Building a new server on sampling. The spec now says new implementations should not. Use a provider SDK.
- Sending tool-enabled requests blindly. A server must not include
toolsunless the client declaredsampling.tools. When it does, everytool_usein the model's reply needs a matchingtool_resultin the next message, and that message may contain nothing else. - Forgetting the loop can run away. Both sides should cap tool iterations; passing
toolChoice: {"mode": "none"}on the last pass forces a final answer. - Keeping message history between requests. The spec says the message list should not be retained across separate sampling requests.
FAQ
- Is MCP sampling still supported?
- It is deprecated, not removed. The 2026-07-28 revision keeps it in the specification for at least twelve months, so clients and servers that already use it keep working. New implementations should not adopt it, and the registry lists the first revision on or after 2027-07-28 as the earliest it can be removed.
- Does MCP sampling expose my API key to the server?
- No. That was the point of the design. The server sends messages and preferences; the client picks a model it has access to, pays for the call, and returns only the generated text. The server never receives credentials, and the client may change or ignore the system prompt and most parameters.
- Can MCP sampling use tools?
- Yes, when the client declares the sampling.tools capability. The server includes tool definitions and a toolChoice mode of auto, required or none. If the model returns tool_use blocks, the server executes them and sends another sampling request with matching tool_result blocks appended.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.