Server-Initiated Sampling in MCP

What server-initiated sampling is

Sampling lets an MCP server ask an MCP client to obtain a model completion on its behalf. The server supplies messages and generation parameters; the client decides whether to make the model call and what it will contain.

The MCP Sampling specification for 2025-11-25 defines this as a server request for a completion or generation through the client. The model provider relationship remains on the client side, so the MCP server does not need the user’s model API key or other model credentials.

This is useful when server logic needs model judgment inside a larger operation. The server can request text, image, or audio interaction without becoming a second model client that must store credentials, select a provider, implement provider-specific authentication, or receive a copy of the user’s model key.

Sampling does not give the server general access to the client’s model. It gives the server a typed way to ask. The client retains control over model access, model selection, permissions, approval, and the context sent with the request.

The request direction

Most visible MCP activity begins with the client calling a server: listing tools, invoking a tool, reading a resource, or retrieving a prompt. Sampling adds a request in the other direction. The server sends sampling/createMessage to the client, and the client returns either a sampling result or an error.

That direction matters to an implementation. A message received from a connected server is not automatically a command that the client must execute. It is input crossing a trust boundary. The client has to identify the JSON-RPC method, validate its parameters, confirm that the relevant capability was negotiated, apply its own permission policy, and decide whether to proceed.

The MCP schema reference for 2025-11-25 defines CreateMessageRequest explicitly as a request from the server to sample a model through the client. Its method is sampling/createMessage, and it carries a request ID so the client can return the corresponding result or error.

A client that assumes all meaningful requests originate locally can mishandle this flow in either direction. It may reject valid sampling requests because it routes server traffic only as responses and notifications, or it may accept an inbound request and pass it into a privileged command path without checking what the request authorizes. The correct abstraction is bidirectional request handling with separate authorization for each method.

This direction is the same whether the connection uses a remote process or a program running on the user’s machine. The transport and trust considerations differ, as covered in remote versus local MCP servers, but a local process does not become entitled to model access merely because the client launched it.

Credentials stay with the client

The server does not receive the user’s model credentials as part of sampling. It sends a protocol request to the client; the client uses whatever model access it already has, subject to its own configuration and policy.

This separation removes a credential-sharing requirement, not the need for authentication everywhere else. A remote MCP server may still require authorization for the MCP connection, and it may hold credentials for services it operates. Those are separate from the credentials the client uses to obtain the model completion.

The distinction also limits what the server can assume. It cannot assume that the client uses a particular model provider, has access to a named model, accepts the requested token budget, or permits sampling at all. A server designed around sampling therefore expresses a request in MCP terms and handles rejection or substitution as a normal outcome.

The protocol does not set a price for a sampling request. Any model usage is made through the client’s model access, while the request can express cost, speed, and capability preferences. The client remains responsible for applying whatever usage limits, budget controls, or provider terms govern that access.

Capability negotiation comes first

Sampling is optional. A client that supports it declares a sampling capability during initialization. A server cannot infer support from the client having an embedded model or from the client being able to invoke ordinary MCP tools.

Basic support is declared as an empty sampling capability:

{
  "capabilities": {
    "sampling": {}
  }
}

Tool-enabled sampling has a separate nested capability:

{
  "capabilities": {
    "sampling": {
      "tools": {}
    }
  }
}

A server must not send a tool-enabled sampling request unless the client declared sampling.tools. If a request contains tools or toolChoice without that declaration, the schema requires the client to return an error.

Context inclusion also has a capability marker, sampling.context, but the 2025-11-25 specification soft-deprecates the includeContext values thisServer and allServers. A server should omit includeContext, leaving its default as none, unless the client declared context support. The deprecated values may be removed in a later specification version.

Capability negotiation answers whether a client can receive a class of request. It does not approve each use. A client can advertise sampling and still reject a particular request because of user choice, policy, unsupported content, invalid parameters, rate limits, or permissions.

What the server can put in the request

A sampling/createMessage request contains a messages array and a required maxTokens value. It may also contain model preferences, a system prompt, a context request, temperature, stop sequences, provider-specific metadata, tools, and a tool-choice mode.

The message content can be text, images, audio, tool-use blocks, or tool-result blocks. Messages use the user and assistant roles. These roles describe the conversation being presented for sampling; they do not identify which MCP peer sent the JSON-RPC request.

maxTokens is the requested upper bound, not an entitlement. The client may sample fewer tokens. This lets the server state how much output could be useful while leaving the client able to apply a tighter budget.

The server may supply temperature and stop sequences, but their presence does not transfer control of the model call. The client is still the component deciding whether and how to map the MCP request onto its model provider.

The optional systemPrompt is also a request. The client may modify or omit it. This is important because text placed in a system field can carry more influence than an ordinary user message in many model APIs. A client should not grant that influence merely because the field arrived under the expected schema name.

Model choice remains with the client

A server can send modelPreferences, but it cannot require a particular model. Preferences may include ordered name hints and three normalized priorities from 0 to 1: costPriority, speedPriority, and intelligencePriority.

A model hint is advisory. The client may match it as a substring of an available model name, map it to a model from another provider that fills a similar role, or ignore it. When several hints are supplied, the client evaluates them in order, but final selection still belongs to the client.

This arrangement reflects information the server does not have. The client knows which models are configured, which are permitted for the user or workspace, which can handle the supplied content, and which usage controls apply. The server knows what kind of completion its operation needs. Preferences communicate that need without turning a model name into an authorization bypass.

A client should make substitution visible where the difference matters. The response contains the name of the model that generated the message, allowing the server to record or reason about what actually ran rather than assuming its hint was followed.

Context remains with the client

The server controls the messages it submits, but it does not control the rest of the client’s context. The client decides whether any local conversation, resource, server data, or other material is attached to the model request.

The includeContext field is only a request. Its possible values are none, thisServer, and allServers, with none as the default. The client may ignore any requested inclusion. In the 2025-11-25 version, the two values that request server context are soft-deprecated and should not be used unless the client advertised sampling.context.

This control is a data boundary as well as a prompt-construction choice. A server asking for allServers is not proof that information from every connected server is relevant or safe to disclose. The client has the broader view of which sources exist, what permissions apply to them, and what the user approved for the current operation.

The same principle applies to the server’s supplied messages and system prompt. Applications should let users inspect and edit prompts before sending them. Editing can remove irrelevant or sensitive material without giving the server access to the client’s private context.

For server authors, the practical consequence is that a sampling request must remain meaningful when no extra context is added. Context controlled by the client cannot be treated as a guaranteed hidden input.

Permissions and human approval

The specification says there should always be a human in the loop with the ability to deny sampling requests. Applications should provide an interface for reviewing the request, viewing or editing its prompt, and reviewing the generated response before it is returned to the server.

There are therefore two distinct disclosure decisions. Before sampling, the user can decide whether the supplied prompt and any client-selected context may be sent to the model. After sampling, the user can decide whether the resulting content may be returned to the MCP server.

The response review matters because the completion can contain information inferred from context the server did not originally possess. Client control is incomplete if approval covers only the outbound model call and every generated result is automatically disclosed back to the requesting server.

A deployment may implement permissions through interactive approval, pre-approved policy, or a narrower product interface, but support for sampling is not itself permission to satisfy every request. The client remains the enforcement point.

A rejected request should return an error rather than a fabricated model response. The sampling specification identifies error code -1 for user rejection. Invalid message structure, including missing tool results or content mixed where the schema forbids it, uses JSON-RPC invalid-parameters code -32602.

Tool-enabled sampling

A sampling request can offer tools for the model to use. The server places tool definitions in the tools array and may set toolChoice to auto, required, or none. auto lets the model decide, required requires at least one tool use, and none forbids tool use for that sampling turn.

This is separate from the ordinary list of tools an MCP server exposes to the client. The tools array inside a sampling request describes tools available within that model interaction. Clients still need to enforce restrictions on which tools an MCP server exposes at the relevant boundary; a server-supplied tool definition is data, not permission to invoke arbitrary client capabilities.

When the sampled model requests a tool, the result returned to the server has stopReason: "toolUse" and one or more tool_use content blocks. The server executes the requested uses, appends matching tool_result blocks to a later sampling request, and can continue the exchange until it obtains a final completion.

Every tool-use ID must have a corresponding tool result before the conversation continues. A user-role message containing tool results must contain only tool-result blocks; it cannot mix them with text, image, or audio content. Both sides should impose iteration limits so a tool loop cannot continue without a bound.

Tool-enabled sampling increases what must be reviewed. The client is no longer considering only a prompt and completion; it is also processing server-supplied tool schemas and returning model-generated tool arguments. Capability checks, schema validation, approval, and loop limits remain active for each turn.

Treat inbound requests as untrusted input

The MCP security best practices for 2025-11-25 tell clients to validate and sanitize input from MCP servers before processing it. That rule applies directly to sampling because the server supplies messages, prompts, metadata, tool definitions, and requested generation controls.

Schema validity is necessary but not sufficient. A syntactically valid request can still ask for context the server should not receive, propose a tool the client does not permit, request an unacceptable amount of model usage, or include prompt text the user does not approve. Validation establishes that the message has the expected shape; authorization establishes whether the requested effect is allowed.

An implementation should route sampling/createMessage only to its sampling handler. It should not concatenate the method or parameters into a shell command, reinterpret prompt content as client configuration, or let arbitrary metadata select privileged provider behavior. The handler can then apply capability checks, content validation, permission policy, rate limits, model selection, context selection, and response review as separate controls.

Local servers deserve the same boundary. The security guidance notes that local MCP servers may run with the client’s privileges and recommends sandboxing and restricted filesystem and network access. A server process being installed, launched, or trusted for one purpose does not authorize every server-to-client request it can encode.

Logging should preserve enough information to explain a decision: which server requested sampling, which method and request ID were used, whether approval was requested, which model was selected, what stop reason was returned, and whether the request was rejected. Sensitive prompt or completion bodies should be handled according to the same data policy as the model interaction itself rather than copied into logs by default.

What to check next

For an implementation, the next checks are whether the client advertises sampling, whether it separately advertises sampling.tools or sampling.context, how it presents request and response approval, which model policies override server preferences, and how it handles rejection and invalid parameters.

For a server, verify that sampling is optional in the workflow, model hints remain advisory, requests work with includeContext omitted, token bounds are explicit, and tool loops have matching results and an iteration limit. When a live exchange does not match those expectations, inspect the request direction and negotiated capabilities before debugging the failing MCP call.