Python: [Feature]: Support the released MCP Skills extension in MCPSkillsSource #9582

Problem

Python's MCPSkillsSource still discovers skills through the draft-era skill://index.json convention. The released MCP Skills extension instead negotiates io.modelcontextprotocol/skills, discovers skills through skills/list, supports direct lookup through skills/get, and requires hosts to retain and verify each skill's resource manifest.

The .NET implementation has already established the Agent Framework behavior through #9198, #9217, #9319, #9372, #9425, and #9464. Python should follow that design closely so the framework has one cross-language security and compatibility model.

The existing #8772 captured the original specification gap and prerequisite questions, but it predates the completed .NET implementation, combines both languages, and does not capture the hardening requirements discovered during review. This issue is the maintainer-owned Python roadmap.

Use Case and Evidence

Agent Framework users need Python agents to consume skills from servers implementing the released Skills extension without losing compatibility with existing Foundry Toolbox and other servers that still expose skill://index.json.

Evidence and prerequisites:

• Python: [Feature]: Support the stateless MCP 2026-07-28 revision alongside 2025-era peers #8245 migrated Python to the MCP 2026-07-28 protocol and deliberately retained the legacy skills discovery path.
• .NET: Python: [Feature]: Move MCPSkillsSource to the released SEP-2640 (skills/list and skills/get) #8772 identified that the final SEP no longer defines skill://index.json, called out Foundry Toolbox compatibility, and recommended Python/.NET alignment.
• Sergey partitioned the .NET implementation into runtime support (.NET: Add runtime support for MCP-listed skills #9198), capability-based discovery (.NET: Integrate MCP-listed skill discovery #9217), frontmatter verification (.NET: Verify MCP-listed skill frontmatter with a shared parser #9319), digest and size verification (.NET: Verify MCP-listed skill resource digests and sizes #9372), resource bounds (.NET: Bound MCP-listed skill resource sizes #9425), and pagination/catalog limits (.NET: Add pagination to MCP-listed skill discovery #9464).
• The latest published Python mcp package is 2.3.0 (October 2, 2026). Its wheel does not contain the Skills extension modules.
• Add Skills extension modelcontextprotocol/python-sdk#3485 added the Skills extension on October 11, with a specification-alignment follow-up in Add cache fields to directory read and _meta to Skill modelcontextprotocol/python-sdk#3719, but no release containing those changes exists yet.
• The SDK's current main branch requires Python 3.11 or later. Agent Framework still advertises Python 3.10; Python: Drop Python 3.10 support by October 31, 2026 #9373 tracks raising the minimum to Python 3.11 by October 31.

Desired Outcome

Python supports MCP-listed skills through the released extension with behavior aligned to .NET:

• Framework-created MCP clients advertise the Skills extension when the framework can consume it.
• MCPSkillsSource uses skills/list when the server advertises io.modelcontextprotocol/skills.
• skill://index.json remains a deprecated compatibility fallback only when the server does not advertise the extension.
• A server that advertises the extension but returns invalid or failed extension results does not silently downgrade to the legacy path.
• Listed SKILL.md instructions and supporting resources are loaded lazily, restricted to the retained manifest, and verified before use or caching.
• Foundry Toolbox, samples, documentation, and tests use the same capability and verification model.
• Follow-up work provides URI-first skills/get loading where Agent Framework's host API can preserve server identity and URI.

Alternatives Considered

• Continue tracking Python through .NET: Python: [Feature]: Move MCPSkillsSource to the released SEP-2640 (skills/list and skills/get) #8772. That issue remains useful historical context, but its combined-language scope and pre-implementation assumptions make it unsuitable as the execution roadmap.
• Implement the entire extension in one PR. This would combine protocol integration, compatibility behavior, parsing, integrity verification, resource limits, Foundry integration, and API design into one difficult review. The staged .NET approach produced clearer security review and should be mirrored.
• Wait to create the roadmap until the next mcp release. The implementation cannot merge before a released dependency exists, but the architecture, work partition, and acceptance criteria are ready now.
• Remove skill://index.json immediately. This would break existing Foundry Toolbox and legacy server scenarios. The fallback should remain deprecated and capability-gated during the transition.
• Implement the protocol methods directly in Agent Framework. The upstream SDK implementation is merged and should own protocol types, negotiation, and typed request routing once released.

Proposed Direction

Treat this as an umbrella with the following implementation slices, modeled on Sergey's .NET work:

• Prerequisite: SDK and connection wiring. Consume the first published mcp release containing the Skills extension, complete Python: Drop Python 3.10 support by October 31, 2026 #9373, register the SDK Skills client extension on framework-created clients, and define behavior for caller-owned Client and deprecated ClientSession paths.
• Runtime support for MCP-listed skills (model: .NET: Add runtime support for MCP-listed skills #9198). Add an internal listed-skill implementation that retains the originating connection, skill URI, raw frontmatter, and static resource manifest; load content lazily and restrict relative resource lookup to the retained manifest.
• Capability-based discovery and compatibility fallback (model: .NET: Integrate MCP-listed skill discovery #9217). Select skills/list only when advertised, preserve skill://index.json only when absent, avoid downgrade after extension failures, and update Foundry Toolbox plus the MCP skills sample.
• Frontmatter verification (model: .NET: Verify MCP-listed skill frontmatter with a shared parser #9319). Extract or reuse a shared parser and compare every advertised frontmatter field against the fetched SKILL.md before caching or returning instructions.
• Digest and byte-size verification (model: .NET: Verify MCP-listed skill resource digests and sizes #9372). Require exactly one text or binary content block and verify raw UTF-8 or decoded bytes against the manifest for SKILL.md and supporting resources.
• Resource bounds (model: .NET: Bound MCP-listed skill resource sizes #9425). Apply conservative configurable limits before expensive encoding, decoding, hashing, or caching.
• Pagination and catalog bounds (model: .NET: Add pagination to MCP-listed skill discovery #9464). Reuse SDK pagination where possible and add Agent Framework limits and tests for excessive catalogs, repeated cursors, duplicates, and partial failures.
• URI-first extension follow-up. Design and implement skills/get activation for known or unlisted URIs, preserving server identity and URI in registries, approvals, and caches. Track optional directoryRead, dynamic manifests, and wire ttlMs / cacheScope semantics separately if they require additional host API design.

Each implementation slice should be independently reviewable and link back to this umbrella. The core capability, compatibility, verification, and security decisions remain maintainer-owned; bounded community contributions may build on those decisions.

Scope and Non-Goals

The first implementation milestone targets parity with the current .NET behavior: advertised skills/list, static manifests, verified lazy resource reads, bounded discovery, legacy fallback, and Foundry Toolbox integration.

The following are not required in the first parity milestone:

• Dynamic manifests ("resources": "dynamic"); the host may initially decline them.
• resources/directory/read when a static manifest already supports resource lookup.
• Persisted approval storage or a new general-purpose skill registry.
• Removing legacy skill://index.json support.
• Restoring or changing the separate MCP Tasks implementation tracked by Python: Design MCP 2026 Tasks client support with SDK v2 extensions #9215.

Prerequisites for merge are a published mcp release containing the Skills extension and completion of the Python 3.11 transition in #9373. Do not pin Agent Framework production dependencies to an unreleased SDK commit.

Related: #8245, #8772, #9215, #9373, modelcontextprotocol/python-sdk#3485, modelcontextprotocol/python-sdk#3719.

Language

Python

Contribution Intent

I am willing to implement this

Acknowledgements

• I searched existing issues and did not find a duplicate.
• I will wait for explicit maintainer agreement before starting implementation of a non-trivial change.