Python: [BREAKING] Remove deprecated MCP compatibility surfaces in vNext #9452

Activity

1. Jose Alvarez (jpalvarezl)

   added

   pythonUsage: [Issues, PRs], Target: PythonUsage: [Issues, PRs], Target: Python

   breaking changeUsage: [PRs], Target: all PRs that introduce changes that are not backward compatibleUsage: [PRs], Target: all PRs that introduce changes that are not backward compatible

   mcpUsage: [Issues, PRs], Target: MCPUsage: [Issues, PRs], Target: MCP

   vnextUsage: [Issues, PRs], Target: breaking-change features deferred to the next major releaseUsage: [Issues, PRs], Target: breaking-change features deferred to the next major release

   on Oct 16, 2026
2. github-project-automation

   added this to Agent Frameworkon Oct 16, 2026
3. github-actions

   changed the title [-]Python: Remove deprecated MCP compatibility surfaces in vNext[/-] [+]Python: [BREAKING] Remove deprecated MCP compatibility surfaces in vNext[/+] on Oct 16, 2026
4. jpalvarezl commented on Oct 16, 2026

   

   Jose Alvarez (jpalvarezl)

   on Oct 16, 2026

   MemberAuthor

   More actions

   MCPSkills and Foundry composition follow-ups

   These items came out of the MCP v2 lifecycle review. They are intentionally tracked as vNext follow-ups rather than expanding the current PR:

   • Remove deprecated ClientSession support from MCPSkillsSource and MCPSkill; accept and document high-level mcp.Client as the connection model.
   • Replace or remove the compatibility-named session_provider API. If a replacement provider API is needed, name it for connections/resource reads and document that returned Clients are borrowed, already entered, and never closed by MCPSkills.
   • Remove session-centric internal names and documentation (_session_provider, "session resolver", swapped MCPTool.session) in favor of connection/resource-read terminology.
   • Remove remaining MCPSkills samples and contributor guidance that construct or promote raw ClientSession; migrate them to high-level Client or FoundryToolbox.as_skills_provider().
   • Remove Foundry Toolbox tests and adapters that read, assign, or impersonate MCPTool.session / ClientSession solely for skills resource access.
   • Replace the internal Foundry session-shaped resource adapter and ClientSession cast with a narrowly typed resource-read abstraction if that adapter is still needed after low-level session removal.
   • Add or retain real high-level Client coverage for fixed connections, provider-resolved replacement connections, response caching, MRTR, and caller-owned lifecycle behavior.
   • Decide separately whether Foundry Toolbox needs a public composable SkillsSource API for aggregating local and Toolbox skills. Do not introduce an as_skills_source() API as incidental cleanup; require an explicit API proposal, naming review, caching/identity semantics, samples, and tests.
   • If no public composable source API is approved, document the supported composition pattern and update mixed local/Toolbox skill samples accordingly.
5. jpalvarezl commented on Oct 16, 2026

   

   Jose Alvarez (jpalvarezl)

   on Oct 16, 2026

   MemberAuthor

   More actions

   Follow-up: connection-owning MCPSkillsSource(url=...)

   Related review discussion: #9237 (comment)

   The suggestion is to let callers write something like:

   source = MCPSkillsSource(url="https://example.com/mcp")

   instead of constructing and entering an mcp.Client themselves. This is more than a constructor convenience because the source would then own an asynchronous connection lifecycle.

   Today, SkillsSource exposes only get_skills(context). SkillsProvider calls that method from before_run, but it does not enter or close the source. An MCP Client also cannot be opened only for the index read and immediately closed: the returned MCPSkill objects fetch SKILL.md bodies and resources later, so the same owned connection must remain available beyond discovery.

   Design TODOs

   • Decide whether the public input should be url, server, or a broader SDK transport/server input matching mcp.Client(...).
   • Define the ownership rule: a URL/server/transport input creates an Agent Framework-owned Client; a supplied Client remains caller-owned and already entered.
   • Decide where source lifecycle belongs:
     • add an async lifecycle contract to SkillsSource and have SkillsProvider enter/close it;
     • make SkillsProvider specifically own managed MCP sources;
     • or introduce a separate managed MCP skills source/provider type rather than changing every source.
   • Keep the owned Client entered across index discovery, lazy SKILL.md loading, sibling resource reads, and archive downloads.
   • Define cleanup through agent/provider open/close, partial-open failure, cancellation, repeated close, and failed discovery.
   • Define concurrency semantics when multiple runs or agents share one source: connect coalescing, in-flight reads, close while active, and reconnect/replacement behavior.
   • Define authentication and transport configuration for URL-owned sources without duplicating MCPStreamableHTTPTool header/HTTP-client APIs.
   • Preserve SDK Client caching and MRTR behavior for all resource reads; do not fall back to ClientSession operations.
   • Ensure a managed source closes only Clients it created and never closes a caller-supplied Client.
   • Decide how managed connection lifetime interacts with CachingSkillsSource, especially cached MCPSkill objects retained after discovery.
   • Add tests for ownership, lazy reads after discovery, caching, MRTR, reconnect, concurrency, cancellation, and cleanup.
   • Add a minimal URL-based sample only after the lifecycle contract is established.

   This should be treated as an explicit lifecycle/API feature, not folded into terminology cleanup or the current PR incidentally.
6. jpalvarezl commented on Oct 19, 2026

   

   Jose Alvarez (jpalvarezl)

   on Oct 19, 2026

   Last edited by jpalvarezl

   MemberAuthor

   More actions

   MCP transport-tool ownership cleanup

   Follow-up from #9369: the stabilized transport constructors distinguish framework-owned construction parameters from a caller-owned high-level mcp.Client. The compatibility branches below should be removed in vNext rather than carried into the final API.

   MCPStreamableHTTPTool

   • Remove the deprecated session: ClientSession | None parameter, including the temporarily preserved url + session constructor path.
   • Remove HTTP-tool branches that initialize, inspect, trace, reset, or route operations through a caller-supplied low-level session; retain supported legacy wire-protocol negotiation through the high-level mcp.Client.
   • Remove the caller-supplied http_client: httpx2.AsyncClient | None constructor parameter and its borrowed-lifecycle contract.
   • Simplify _httpx_client handling so any HTTP client created inside URL-owned mode is always framework-owned and deterministically closed; remove owned-versus-borrowed HTTP-client cleanup branches and tests.
   • Direct callers that need a customized HTTP client or transport to configure an SDK transport/high-level mcp.Client themselves and pass it through mcp_client=.
   • Revisit HTTP-only constructor options and supporting hooks that exist primarily to configure or protect a caller-supplied HTTP client; keep only options required for the final framework-owned URL transport contract.
   • Remove compatibility docstrings, warnings, telemetry branches, security tests, and lifecycle tests that exist solely for session= or caller-supplied http_client=.

   MCPStdioTool

   • Remove the deprecated session: ClientSession | None parameter, including temporarily preserved command + session and session-only compatibility paths.
   • Remove stdio-tool branches that initialize, inspect, reset, or route operations through a caller-supplied low-level session.
   • Remove compatibility tests and documentation that require placeholder process configuration for an externally owned connection.
   • Keep command, args, env, encoding, and stdio transport kwargs scoped exclusively to framework-owned process construction.
   • Ensure transport telemetry represents only a process/transport the wrapper actually created; do not report pipe transport solely because a caller-owned Client was wrapped by MCPStdioTool.
   • Decide explicitly whether caller-owned high-level Clients remain accepted by transport-specific wrappers or move to a transport-neutral Client-backed MCP tool. Do not infer transport identity from SDK Client internals.

   Final ownership surface

   • Reduce transport constructors to their final ownership modes after compatibility removal: framework-owned URL/command construction or caller-owned high-level Client, never contradictory combinations.
   • Remove associated compatibility docstrings, warnings, telemetry branches, security tests, lifecycle tests, and type suppressions.
   • Add migration guidance showing how low-level-session users and custom-transport users construct an entered high-level mcp.Client and pass mcp_client= without transferring ownership.

   This cleanup must not remove automatic fallback to supported legacy MCP peers; it removes deprecated Python ownership/configuration surfaces only.
7. Jose Alvarez (jpalvarezl)

   self-assigned this

   on Oct 22, 2026