Support MCP Elicitation, Sampling, and Roots via new McpSessionHost

[Tyler Payne (tylerpayne)]

Why are these changes needed?

With the introduction of sampling and elicitation to MCP, "workbenches" need the ability to initiate communication with the host agent/user/system.

This is an initial attempt at introducing an extensible WorkbenchHost protocol that implementers can extend the functionality of agents' workbenches without altering the agent themselves. See the McpAssistantAgent in autogen-ext for an example and implementation of MCP Sampling, Roots, and Elicitation.

Related issue number

N/A

Checks

I need to remove old tests and add new ones. I expect checks to fail at the moment.

• I've included any doc changes needed for https://microsoft.github.io/autogen/. See https://github.com/microsoft/autogen/blob/main/CONTRIBUTING.md to build and test documentation locally.
• I've added tests (if relevant) corresponding to the changes introduced in this PR.
• I've made sure all auto checks have passed.

[Tyler Payne (tylerpayne)]

Victor Dibia (@victordibia) Eric Zhu (@ekzhu) Let me know what you think of this approach. I think this is more extensible than my one-off change to support sampling. Any new features that MCP (or other tools) may add that require host communication would be centralized in this new WorkbenchHost type.

(I asked Claude to write my commit messages, let me know if you have any questions)

[Eric Zhu (ekzhu)]

This looks good to me. Do you think it make sense that we just add MCP features into the AssistantAgent?

[Tyler Payne (tylerpayne)]

Arch & Sequence diagrams here: https://github.com/microsoft/autogen/blob/9ec3da92d39d67015937d7bebe4beba5aed3e836/python/packages/autogen-ext/src/autogen_ext/tools/mcp/host/README.md

[codecov]

Codecov Report

❌ Patch coverage is 97.86325% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.22%. Comparing base (a2bf539) to head (7c35ac2).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...es/autogen-ext/src/autogen_ext/tools/mcp/_actor.py	76.92%	3 Missing ⚠️
...ogen-ext/src/autogen_ext/tools/mcp/_host/_roots.py	95.83%	1 Missing ⚠️
...utogen-ext/src/autogen_ext/tools/mcp/_workbench.py	88.88%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6833      +/-   ##
==========================================
+ Coverage   81.06%   81.22%   +0.16%     
==========================================
  Files         239      244       +5     
  Lines       18333    18512     +179     
==========================================
+ Hits        14861    15036     +175     
- Misses       3472     3476       +4     

Flag	Coverage Δ
unittests	81.22% <97.86%> (+0.16%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Eric Zhu (ekzhu)]

I like that we separate the host from the agent class.

Can you help me understand why it needs to modify the group chat and update the runtime?

[Tyler Payne (tylerpayne)]

Eric Zhu (@ekzhu) Sorry for the late reply!

Because elicitation happens during other MCP calls (esp. tool calls in our case here), it happens out-of-order with respect to the agent's message handler. I wanted to take advantage of the Runtime's existing connections to fulfill the elicitation request asynchronously.

I recognize that this touches very core code is therefore potentially not great.

Ideally we'd use the Handoff mechanism. But that would require the agent noticing that it's turn is being interrupted mid tool call, store that state, handoff, wait for its next turn, then finish its request.

So in my mind, hijacking the runtime is more elegant than having to force an agent to manage that much state. I could be convinced otherwise.

[Metodi Simeonov (mesimewplc)]

Looking forward to this addition

[Tyler Payne (tylerpayne)]

Eric Zhu (@ekzhu) Revisiting this update. Is it still desirable to integrate this? I saw you referenced it in the agent-framework.

I could update this to provide cleaner public getters for GroupChat properties that I'm "illegally" accessing in the current version.

[Eric Zhu (ekzhu)]

Eric Zhu (@ekzhu) Revisiting this update. Is it still desirable to integrate this? I saw you referenced it in the agent-framework.

I could update this to provide cleaner public getters for GroupChat properties that I'm "illegally" accessing in the current version.

Let's get this in. I think as long as it is adding to the behavior rather than affecting existing usage should be fine.

[Tyler Payne (tylerpayne)]

Eric Zhu (@ekzhu) I simplified the implementation, now it is isolated to the MCP Workbench (and new McpSessionHost). Doesn't mess with the GroupChat logic anymore.

To recap:

MCP Servers sometimes need to make (non-tool call) requests to the Host. Currently, the allowed requests are ListRoots, Elicitation, and Sampling.

Our McpWorkbench already handles connection to the MCP Server and tool calling. This PR introduces a McpSessionHost which delegates MCP Server elicitation, sampling, and roots requests to optional handlers. The handlers are abstract and extensible Components: Elicitor, Sampler, RootsProvider. I also provide concrete subclasses: StreamElicitor, StdioElicitor, ChatCompletionClientSampler, and StaticRootsProvider.

[Tyler Payne (tylerpayne)]

We could try and get autogen added to: https://modelcontextprotocol.io/clients as well. The row would look pretty good:

Client	Resources	Prompts	Tools	Discovery	Sampling	Roots	Elicitation
autogen	❌	❌	✅	❌	✅	✅	✅

Not many clients have sampling, roots, and elicitation supported.

[Eric Zhu (ekzhu)]

We could try and get autogen added to: https://modelcontextprotocol.io/clients as well. The row would look pretty good:

Client Resources Prompts Tools Discovery Sampling Roots Elicitation
autogen ❌ ❌ ✅ ❌ ✅ ✅ ✅
Not many clients have sampling, roots, and elicitation supported.

Good idea!

[Metodi Simeonov (mesimewplc)]

This is a long waited feature! I am sure it will propel autogen as the go to framework for MCP workflows. Good job guys! Moreover, adding tool annotations to workbench list_tools() would make it even better - #6929