Improve sampling in the protocol

[saqadri]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

Creating a GH Discussion as requested by @dsp-ant based on a Discord thread we had on the subject.

Context and Motivation

The Model Context Protocol (MCP) includes a sampling/createMessage API that allows servers to request language model (LLM) responses from clients without having direct API credentials or embeddings. As contributors experiment with using the sampling API to build agents and tools, questions arise about

• how to handle tool calls,
• incorporate context, and
• utilize notifications or progress updates in a clean, extensible way (e.g. for streaming).

Key Discussion Points

1. Tool Calls During Sampling

Problem: When an LLM (invoked by a server’s sampling/createMessage request) suggests making a tool call, how should that be communicated and executed?

Current State: The sampling request as currently defined doesn’t explicitly support passing tools or tool definitions to the LLM. The model messages for sampling are limited to text or image responses and do not include resource/tool embeddings.

Potential Approach:
One idea: The client, which implements createMessage, could supply tool context by including them in the system prompt or as part of includeContext. If the LLM requests a tool call, the client could pause the sampling, execute the tool call (via a separate MCP tool/call request), incorporate the response, and continue sampling. This would effectively turn createMessage into a loop until a “steady-state” (no more tool calls requested) is reached.

Concerns:

• This approach might lead to complex orchestration logic in the client, duplicating the “main loop” usually managed by the host application.
• The spec does not clearly define whether or how tool calls should be integrated into the sampling flow.

2. Meaning and Usage of includeContext

Problem: includeContext is described as a mechanism for providing system or conversation context to the LLM. But what kinds of context should be included (e.g., tool definitions, multi-server contexts, etc.)?

Interpretations:

• thisServer: Include the assistant message that triggered the sampling request.
• allServers: Potentially include broader conversation history or additional user-assistant pairs, and possibly external resources or tool definitions.

Open Question: Is it intended or advisable to include tool definitions from other servers or the host application via includeContext? The protocol is silent on this, and it might introduce security or complexity concerns. For example, if server A requests sampling with the includeContext: allServers, should the client include tools and resources from server B in that fulfilling that request?

3. Notifications and Progress Updates

Question: Are notifications bidirectional? Can a client send notifications back to the server, perhaps for streaming partial outputs or reporting progress?

Current Understanding: Notifications as shown in the docs primarily describe server-to-client messages. However, there doesn't seem to be any reason for clients not to be able to send notifications to the server.

Proposal: Consider using notifications or a similar mechanism to stream partial responses from the client’s sampling process back to the server during sampling. This would avoid adding new primitives while supporting progress updates.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[jspahrsummers]

Thanks for opening this discussion!

1. We absolutely would like to support adding tools into sampling calls. This was simply an oversight in the spec, or rather a use case we didn't think of but one that definitely makes sense to have. 🙂
2. You've highlighted some unintended ambiguity in the interpretation of includeContext, for sure.
   • thisServer was meant as, "use whatever you want from this (the sending) MCP server, as if the user had initiated sampling and this server were the only one connected"
   • allServers was meant as, "use whatever you want from all connected MCP servers, just as you do for user-initiated messages right now"
   • In both cases, it's less about the conversation history/messages, and more about which MCP features to attach to sampling. We should definitely clarify this in the wording.
   • However, it is intentionally underspecified how the client should actually implement these options here, because it may differ dramatically based on UX, level of user trust or riskiness, etc. It would probably be good to specify more here over time, but I fear it's too early to have a strong idea of what goes in the blank right now. Probably related: feat: Some kind of risk level returned by servers #114
3. Yep, notifications are absolutely supported from client to server too! Open to ideas on how to clarify the docs to emphasize this.

[saqadri]

Thanks for the detailed reply, @jspahrsummers!

1. Understood, sounds great!
2. Thanks! This is very helpful and clears things up for me.
3. I would recommend expanding this section out a bit: https://modelcontextprotocol.io/docs/concepts/architecture#message-types.

A related point of clarification (probably a docs update) is where LLM calls can be made. For example, I believe it's ok for business logic in MCP servers to make LLM calls directly (without invoking sampling/createMessage) in certain situations. However, it is a bit ambiguous, and even if that may be deliberately ambiguous as well, having a section on recommended patterns/practices may be useful (e.g. when to use sampling/createMessage).

[dsp-ant]

@saqadri Would you be open to working on PRs for these issues? I am happy to review a PR to improve the documentation.

I would also love to see a PR for how we should improve the specification around createMessage. If you would like to work on that, that would be amazing.