Repository navigation
Controlling Context in Client for Sampling Requests #1205
Description
Question
I am exploring the sampling components in MCP. Based on my understanding of the protocol, this should allow the server to utilise the LLM(s) available on the client side. Unfortunately, none of the examples provide a working demonstration of this.
I have managed to get something working here, but I had to invoke the LLM directly using only part of the information from the CreateMessageRequestParams object. I have not been able to determine the purpose of RequestContext or how it can be leveraged.
In summary, these are my questions:
- How can I access the LLM(s) available to the client directly, rather than making an explicit call?
- How can I use
modelPreferencesto suggest that the client changes the choice of LLM based on priorities or name hints? - How can I use the
RequestContextto pass available context to the LLM for improved generation? - How can I use the
includeContextattribute ofCreateMessageRequestParamsto filter what information is included in the context?
Any guidance or examples would be greatly appreciated.
Additional Context
- MCP Python SDK version:
1.12.2 - Python version:
3.13.5 - Operating System: Ubuntu 22.04.5 LTS on Windows 11 Home via WSL 2
Activity
yarnabrina commentedon Aug 5, 2025
@dsp-ant @ihrpr @Kludex may I kindly request you to have a look at this question when you have a moment? I'd appreciate your inputs.
Kludex commentedon Aug 5, 2025
Check https://ai.pydantic.dev/mcp/server/#mcp-sampling.
yarnabrina commentedon Aug 5, 2025
Thanks for the response. Sorry if I was unclear, what I meant was none of the examples actually show how does the MCP client callback calls already configured LLM (or use hints to switch the model). I am not using
pydantic-aiyet, but in that example also assumes a LLM response as a TODO comment only.As linked, I do have a sample implementation, but I am not sure if this is the intended way to use as I failed to use some properties, some guidance will be much appreciated.
https://github.com/yarnabrina/learn-model-context-protocol/blob/770728148a8aa423a1467785bdb695927cf3428d/src/mcp_learning/mcp_client/orchestrator.py#L253-L334
felixweinberger commentedon Oct 3, 2025
Should add a sampling example to our mkdocs
yarnabrina commentedon Oct 4, 2025
@felixweinberger thanks for looking into it. Can you please have a look at above link and see if this is the ideal way to use sampling? If so, I'm happy to send a PR if you can guide me about the docs/examples contribution process here.
maxisbey commentedon Oct 6, 2025
You could start with a draft PR by adding an example server for sampling, and an example client for sampling in the
examples/folder, each with a README.md stating how to run the tests. We're in the process of adding a proper documentation structure so you can also try to add some docs in thedocs/folder as well if you'd like.Give it your best shot then it makes it easy for someone to give feedback afterwards if anything needs to be changed :)
docs: add sampling example and documentation
ayzmkk-rongbi commentedon Mar 2, 2026
I've submitted a PR to address this: #2194
It adds:
examples/docs/sampling.md) explaining the sampling flow, client-side callback setup, and integration with LLM providers (OpenAI, Anthropic)mkdocs.ymlHappy to incorporate any feedback!
docs: add sampling example and documentation
docs: add sampling example and documentation
feat(examples): add simple-sampling server and client
trentisiete commentedon Apr 19, 2026
Hi all — #1436 is still open on this but has been idle since late 2025 after @felixweinberger's review (drop the
openaiSDK dep, refactor behind anLLMClientabstraction à lasimple-chatbot).I took a shot at an alternative that addresses that feedback:
/chat/completionsviahttpx— runs against OpenAI, Groq, OpenRouter, Ollama, vLLM. No provider SDK in deps; swap via env vars (LLM_API_KEY/LLM_API_BASE_URL/LLM_MODEL).LLMClientwrapper soModelPreferenceshints/priorities handling is isolated, matching thesimple-chatbotpattern.sampling/createMessage(hints, cost/speed/intelligence priorities,systemPrompt,temperature,maxTokens,stopSequences,includeContext,metadata) so the client side demonstrates how each one is interpreted.ModelHintis honoured as a soft override, every advisory field is forwarded, provider failures surface asErrorData.ruffandpyrightclean.Diff on my fork: main...trentisiete:python-sdk:feat/simple-sampling-example
I don't want to step on #1436. @yarnabrina — happy to contribute any of this into your PR instead if that works for you. If maintainers (@felixweinberger, @maxisbey) would rather I open a fresh PR, glad to do that.
yarnabrina commentedon Apr 19, 2026
Hi @trentisiete , I did address the feedbacks, but even after multiple pings got no review or responses from anyone. I doubt maintainers are active and/or tracking old PR's. If you want to contribute in my fork or in a separate PR please go ahead, O don't mind, documentation helps everyone.
He-wei-gui commentedon Jun 6, 2026
I opened #2789 with a smaller docs-only approach for this issue.
It explains how client-side
sampling_callbackhandlers receiveCreateMessageRequestParams, includingmodel_preferences,include_context, andClientRequestContext. I kept it provider-neutral so it complements the existing server-side sampling snippet without adding a full example project or model-provider dependency.prajvalrasik commentedon Jun 20, 2026
I'd like to work on this. I have a focused docs/example update for the client sampling callback that covers model preferences, request context, includeContext, and where to call a local or hosted LLM. Could I be assigned?
Disclosure: AI assistance was used while preparing the draft; I reviewed the change and take responsibility for it.
maxisbey commentedon Jul 29, 2026
Thanks for the report. Closing this as it's been fixed in v2, which is now released (see #2957). If it still reproduces on v2, feel free to reopen.
AI Disclaimer