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

[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.

[moonbox3]

What happens when this receives a real MCP 2.0 task response? types.Result and GetTaskPayloadResult use Pydantic's default extra="ignore", so the SDK discards the task and payload fields before these checks and __pydantic_extra__ is always None. This makes task creation, polling, and result retrieval fail for valid server responses; could we preserve the raw response or deserialize into the concrete task result types before those fields are lost?

[moonbox3]

Should this package be migrated before raising its MCP floor? _responses.py:120 still imports McpError, which MCP 2.0 removed in favor of MCPError, so installing the dependency declared here makes agent_framework_foundry_hosting fail at import time. Could we update that exception handling in this PR or retain the <2 constraint until the package migration lands?

[moonbox3]

Could this retain the protocol value toolUse? MCP 2.0 renamed the Python field to stop_reason, but its canonical wire value remains toolUse; because the type also accepts arbitrary strings, tool_use silently serializes to {"stopReason": "tool_use"}. A conforming server may then fail to recognize that sampling stopped for tool execution and break the tool-use continuation flow.