Python: feat(core): migrate MCP integration to mcp 2.0.0

[pratik wayase (PratikWayase)]

Summary

Migrate agent-framework-core from mcp>=1.x to mcp>=2.0.0, adapting to all breaking API changes in the MCP Python SDK while preserving existing framework behavior. This includes updating production code, test suites, workspace dependency pins, and the lockfile.

Motivation & Context

The MCP Python SDK 2.0.0 introduced significant breaking changes including snake_case attribute renames, Union type aliases replacing wrapper classes, exception restructuring, and payload serialization changes. Without this migration, agent-framework-core cannot use MCP 2.0 servers or benefit from upstream improvements. This change unblocks adoption of MCP 2.0 across the agent framework ecosystem.

Fixes #7446

Description & Review Guide

What are the major changes?

Production code (_mcp.py):

• Renamed McpError → MCPError and removed .error wrapper (.code, .message accessed directly)
• Converted all camelCase attributes to snake_case (mime_type, is_error, structured_content, input_schema, next_cursor, protocol_version, stop_reason, tool_use_id, poll_interval, status_message, task_support)
• Removed types.ClientRequest() wrappers in 4 locations (now a Union type alias in MCP 2.0)
• Changed message.root.method → message.method for ServerNotification dispatch
• Changed read_timeout_seconds from timedelta to float
• Added __pydantic_extra__ extraction in _fetch_task_result and _call_tool_as_task_create (MCP 2.0 GetTaskPayloadResult and Result only declare meta; tool result fields are carried as extras)
• Updated sampling callback params to snake_case (system_prompt, tool_choice, stop_sequences, max_tokens)
• Changed _send_with_one_reconnect request param type from types.ClientRequest to Any
• Used mime_type= keyword arg in content preparation constructors

Test code (test_mcp.py):

• Replaced Mock(spec=ServerNotification) with real notification instances (ToolListChangedNotification, PromptListChangedNotification) since Union types don't support isinstance checks against Mocks
• Converted AnyUrl objects to plain strings for uri fields
• Fixed MCPError constructor calls to use code= and message= directly
• Fixed _make_create_task_result / _make_task_snapshot timestamps from datetime to ISO 8601 strings
• Fixed _make_payload to construct via CallToolResult round-trip for extras compatibility
• Skipped WebSocket test (mcp.client.websocket removed in base MCP 2.0.0)
• Updated request assertions from .root.method / .root.params to direct attribute access
• Used camelCase keys in mock HTTP JSON responses (wire format uses aliases)

Workspace dependencies:

• Updated foundry_hosting and hosting-mcp pyproject.toml to allow mcp>=2.0.0 (previously pinned <2, causing downgrade on uv sync)
• Regenerated uv.lock with mcp==2.0.0 resolved across the entire workspace

What is the impact of these changes?

• No behavioral changes: All adaptations are mechanical API renames and structural adjustments. Tool discovery, invocation, retry logic, progressive disclosure, sampling approval, and telemetry remain identical.
• Workspace-wide: The dependency pin updates in foundry_hosting and hosting-mcp are required to prevent uv sync / poe syntax from downgrading MCP back to 1.x. These packages may need their own MCP 2.0 migration in follow-up PRs.
• WebSocket transport: MCPWebsocketTool now requires mcp[ws] extra; the base mcp package no longer bundles WebSocket support.

What do you want reviewers to focus on?

1. __pydantic_extra__ extraction logic in _fetch_task_result and _call_tool_as_task_create — this is the most novel pattern, needed because MCP 2.0's GetTaskPayloadResult and Result models only declare meta and carry tool result fields as Pydantic extras.
2. Notification dispatch (message.method vs old message.root.method) — confirm the isinstance(message, types.ServerNotification) check works correctly with real notification instances in tests.
3. Workspace dependency pins — verify that updating foundry_hosting and hosting-mcp to mcp>=2.0.0 is acceptable for this PR scope, or whether those packages should remain pinned and be migrated separately.

Related Issue

Fixes #7446

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass (279 passed, 3 skipped)
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue
• This is not a breaking change. Framework public API is unchanged; only internal MCP SDK integration is updated.

[Copilot]

Pull request overview

Migrates the Python agent-framework-core MCP integration to the MCP Python SDK v2.0.0, updating internal protocol handling and tests to match MCP’s breaking API/model changes while enabling the workspace to resolve MCP 2.x.

Changes:

• Updated core MCP client integration (_mcp.py) for MCP 2.0.0 API/model changes (snake_case fields, MCPError, request model usage, task payload parsing via Pydantic extras).
• Updated MCP-related unit tests to construct MCP 2.0-compatible models and assertions, including conditional skipping of the WebSocket transport test when not available.
• Updated workspace/package dependency constraints to allow installing MCP 2.0.0.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/_mcp.py	Adapts MCP integration code to SDK 2.0.0 request/response models, error types, and renamed fields.
python/packages/core/tests/core/test_mcp.py	Updates tests for MCP 2.0.0 model shapes/fields and skips WebSocket test when transport module is unavailable.
python/packages/core/pyproject.toml	Updates the all optional dependency group to allow MCP 2.0.0.
python/packages/foundry_hosting/pyproject.toml	Updates package dependency to allow MCP 2.0.0.
python/packages/hosting-mcp/pyproject.toml	Updates package dependency to allow MCP 2.0.0.

Suppressed comments (1)

python/packages/core/agent_framework/_mcp.py:2474

• The comment explaining the MCP 2.0 GetTaskPayloadResult extras is mis-indented, making it look like it’s part of the except block even though the extraction logic is outside the handler. Aligning the comment with the surrounding code will avoid confusion.

            # In MCP 2.0, GetTaskPayloadResult only declares `meta`; the actual
        # CallToolResult fields are carried as Pydantic extra fields.

[pratik wayase (PratikWayase)]

Evan Mattson (@moonbox3) Eduard van Valkenburg (@eavanvalkenburg) Tao Chen (@TaoChenOSU) Does this PR fulfill all the requirements of the issue, or does it need any further modifications?

[Evan Mattson (moonbox3)]

What happens when an MCP 2 server accepts this call and returns only a task? ClientSession.send_request validates every tools/call response as CallToolResult before applying _LenientResult, so a valid task response without content raises before we capture its task ID and can leave a side-effecting remote task running untracked. Could we use a raw request path or an upstream-supported task result union so the open response is preserved before strict validation, and cover this through a real ClientSession path rather than a mocked send_request?

[pratik wayase (PratikWayase)]

Thanks for catching this. To prevent the orphaned task scenario, we added a ValidationError catch immediately after send_request. if the SDK strictly bypasses _LenientResult and enforces CallToolResult we now wrap it in a ToolExecutionException to safely halt execution and prevent an untracked retry.

[Giles Odigwe (giles17)]

Hey pratik wayase (@PratikWayase) can you address the failing checks here

[Evan Mattson (moonbox3)]

Please re-open when ready to address CI/CD failures.