Add `Skills` extension by vijaydeepsinha · Pull Request #3485 · modelcontextprotocol/python-sdk

vijaydeepsinha · 2026-09-09T18:01:24Z

Summary

Adds Python SDK support for SEP-2640 (Skills Extension): skills/list, skills/get, and resources/directory/read as protocol primitives, SEP-2640 conformance validation, and capability negotiation. This SDK does not provide filesystem discovery, catalog indexing, or caching/refresh policy - those belong to a higher-level provider built on top of this.

Motivation and Context

SEP-2640 defines a convention for serving Agent Skills over MCP using the Resources primitive. The Python SDK has no support for it today. This PR adds the extension using the SDK's existing Extension/MethodBinding mechanism (the same one backing the shipped Apps extension, SEP-2133) - no schema or codegen changes, no new required dependencies.

What's included

src/mcp/shared/skills.py - wire types (Skill, SkillResource, params/results), SEP-2640 conformance validation (name/URI/frontmatter consistency, digest format, resource-manifest completeness, the 512-entry/16 MiB limits), and verify_skill_resource (digest+size integrity check for content already read).
src/mcp/server/skills.py - the Skills extension: handler-based (list_skills, get_skill, optional read_directory), validates results against SEP-2640 before they hit the wire, gates the SEP-2549 ttlMs/cacheScope fields to protocol version 2026-07-28+.
src/mcp/client/skills.py - list_skills/get_skill/read_directory (auto-paginating, with cursor-repeat detection), read_skill_uri (a thin, discoverable resources/read alias), verify_skill_resource re-exported for client use.
src/mcp/client/client.py - client.extension(Skills) returns a typed API for this connection; custom client extensions can expose their own typed API through bind(session).
docs/advanced/skills.md + docs_src/skills/ - a new doc page with a runnable example, explicitly scoping what the SDK does and doesn't do.

Server usage

from mcp.server.skills import Skills
from mcp.shared.skills import ListSkillsResult, GetSkillResult

async def list_skills(ctx, params):
    return ListSkillsResult(skills=[...])

async def get_skill(ctx, params):
    if params.uri != "skill://git-workflow/SKILL.md":
        raise MCPError(code=INVALID_PARAMS, message="unknown skill")
    return GetSkillResult(skill=...)

mcp = MCPServer("catalog", extensions=[Skills(list_skills=list_skills, get_skill=get_skill)])
mcp.add_resource(TextResource(uri="skill://git-workflow/SKILL.md", ...))  # file content is served normally

Client usage

import anyio

from mcp import Client
from mcp.client.skills import Skills


async def main() -> None:
    async with Client("http://localhost:8000/mcp", extensions=[Skills()]) as client:
        for skill in await client.extension(Skills).list_skills():
            print(skill.uri)


if __name__ == "__main__":
    anyio.run(main)

Protocol version / compatibility notes

capabilities.extensions (SEP-2133) and ttlMs/cacheScope (SEP-2549) are 2026-07-28+-only wire fields in this SDK's existing type surface - this is pre-existing, documented SDK behavior (docs/advanced/extensions.md), not something this PR changes. Skills gates its own cache fields to match.
A JSON-RPC -32602 error returns HTTP 200 on the classic (pre-2026-07-28) wire and HTTP 400 on the modern (2026-07-28+) wire. This is existing, spec-mandated (SEP-2575) SDK-wide transport behavior - every handler in the SDK gets it automatically via the shared ERROR_CODE_HTTP_STATUS table; nothing Skills-specific.
No existing public API is removed. This update adds Client.extension() and changes the new Skills.bind hook to accept a session.
Skill results default to cacheScope: private; handlers can explicitly choose public for results shared by all users.
Directory entries are identified by URI, so distinct children can share a display name.

How Has This Been Tested?

tests/{shared,server,client}/test_skills.py - 100% line+branch coverage on all three new modules (shared/skills.py, server/skills.py, client/skills.py), verified via coverage report --fail-under=0. Coverage includes the SEP-2549 cache-attribute behavior on skills/list and skills/get (present on the 2026-07-28 wire, absent on the legacy wire), cursor-resume/pagination, request _meta propagation, and the URI reject rules (trailing-slash and dot-segment).
Full suite: ./scripts/test -q - 6,210 passed, 9 skipped, 1 xfailed, 100% total coverage, strict-no-cover clean.
ruff format --check ., ruff check ., pyright, and the strict Zensical docs build: all clean.

Conformance

Ran the modelcontextprotocol/conformance PR #330 SEP-2640 scenarios end-to-end against a real server and client built on this implementation (server scenarios exercise this PR's server; client scenarios exercise this PR's client against a hostile server the harness stands up):

Scenario	Checks	Result
`sep-2640-skills-enumeration` (`skills/list` + `skills/get`)	32	✅ 32/32
`sep-2640-skills-manifest` (`SKILL.md` resource metadata)	6	✅ 6/6
`sep-2640-skills-directory` (`resources/directory/read`)	7	✅ 7/7
`sep-2640-client-no-prefetch`	1	✅ PASS
`sep-2640-client-verify-digest`	1	✅ PASS
`sep-2640-client-verify-size`	1	✅ PASS
`sep-2640-client-verify-frontmatter`	1	✅ PASS

45 wire checks + 4 client checks, 0 failures, 0 warnings.

Also manually verified via a live server against a Postman collection covering both the session-based (2025-11-25) and stateless (2026-07-28) wires.

Breaking Changes

None. Client.extension() is additive, and the Skills API is new in this PR.

Deliberate scope exclusions (and why)

Filesystem discovery/indexing/caching: this SDK gives the protocol primitives only; a higher-level provider library (e.g. one that walks a directory tree and computes digests) builds on top of Skills, list_skills, and get_skill.
Client-side frontmatter parsing: SEP-2640 requires hosts to parse a SKILL.md's YAML frontmatter and compare it field-by-field against the held entry. This SDK does not ship that comparison, to avoid adding a new required YAML dependency to the core SDK for a check any host already has the means to do with whatever YAML library it uses elsewhere. verify_skill_resource covers the digest/size half (no new dependency needed for that). Documented explicitly in docs/advanced/skills.md's "What this SDK doesn't do".
Skills types living in mcp-types instead of mcp.shared: mcp-types is generated from the official, versioned MCP JSON Schema; SEP-2640 is an extension, not core spec vocabulary, so its types are hand-written and live alongside the extension code - the same placement the existing Apps extension (SEP-2133) uses.

Types of changes

New feature (non-breaking change which adds functionality)
Documentation update

Checklist

I am assigned to the linked issue.
I have disclosed any AI assistance and can explain the change in my own words
I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

AI Disclaimer

This PR was developed with the assistance of either Claude or Codex. I've reviewed and verified the changes.

Wire types, request/result models, and SEP-2640 conformance validation (name/URI/frontmatter rules, resource-manifest completeness, digest and size verification) for the Skills extension, shared by the server and client surfaces.

Skills extension (io.modelcontextprotocol/skills): serves skills/list, skills/get, and the optional resources/directory/read behind the directoryRead capability setting. Handlers are supplied by the server author; the extension validates results against SEP-2640 before they reach the wire and gates the SEP-2549 ttlMs/cacheScope fields to protocol version 2026-07-28+.

Thin client wrappers for skills/list, skills/get, resources/directory/read, and resources/read: list_skills and read_directory follow nextCursor to completion, all four validate the server's response before returning it, and verify_skill_resource checks a read's bytes against a held skill's manifest entry.

Adds the Skills page under Advanced, with a runnable server/client example, and tests proving every claim the page makes against the real SDK.

Parametrize the digest-format rejection test over near-miss cases (uppercase, wrong length, missing/wrong prefix), and add explicit JSON round-trip tests for both shapes of the resources union type (a static array and the "dynamic" marker) to prove neither collapses or mistags on the wire.

_resource_uri_in_skill reads like a boolean predicate but returns None and raises; rename to _validate_resource_uri_in_skill to match its sibling validators (validate_skill, validate_list_result, validate_directory_result) and signal that it asserts.

_handle_read_directory inlined the same "validate incoming URI, convert ValueError to MCPError" pattern that _handle_get had already extracted into a helper. Add a parallel _require_directory_uri so both handlers open with a symmetric one-line precondition check, matching the _require_ui_scheme helper idiom from the Apps extension.

validate_skill already rejects names that violate the Agent Skills grammar (SEP-2640 defers to it), but nothing pinned the edge cases. Add a parametrized test covering consecutive, leading, and trailing hyphens, uppercase, underscores, and the 64-character ceiling.

- Correct the server/client snippet hl_lines, which highlighted blank and unrelated lines after the example imports were expanded. - Fix "all four validate": read_skill_uri is a thin resources/read pass-through that validates nothing, contradicting the same section's own next paragraph. Only list_skills/get_skill/read_directory validate. - Replace the phantom add_resource_template API (no such method) with the @mcp.resource(...) template decorator, in both the guide and the mcp.server.skills module docstring.

pja-ant · 2026-09-09T19:01:11Z

Assigned #3486 to @vijaydeepsinha and re-opened

Two behavioral cases the existing suite left unpinned: - A "dynamic" skill now round-trips through the real server extension, the wire, and the client wrapper (validated on both ends), proving the resources union survives intact rather than only in an isolated model round-trip. - list_skills honours a caller-supplied starting cursor, skipping the pages before it — the resume-from-a-saved-cursor contract.

cubic-dev-ai

All reported issues were addressed across 12 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

…RAMS A non-conformant result from a `list_skills`/`get_skill`/`read_directory` handler (or a `get_skill` URI mismatch) is a server-side bug, not a bad caller request, so -32603 is the correct code rather than -32602. Log the real cause server-side and return a generic message, mirroring the runner's existing handling of invalid handler results. Input validation (`_require_skill_md_uri`, `_require_directory_uri`, params) stays -32602.

… children `_validate_resource_uri_in_skill` now rejects a resource URI ending in `/`, which names a directory rather than a file, and `validate_directory_result` now rejects a `.`/`..` child, which is a traversal segment rather than a real direct child. Both slipped past the prior checks.

…ages `list_skills`/`read_directory` now seed the seen-cursor set with a caller-supplied starting cursor, so a server echoing that cursor is caught on the first page instead of being chased a second time. Rebuilding each page request from the caller's own params (via model_copy) also carries `_meta` forward to every page rather than dropping it after the first.

…ic skills `read_skill_uri` returns a `ReadResourceResult`, not bytes, and `verify_skill_resource` raises for a `"dynamic"` skill (no digests to check). Import the tutorials' symbols from `mcp.types` rather than the internal `mcp_types` package.

…ent test The keyword form `ListSkillsParams(meta=...)` fails pyright: the field's alias is `_meta`, so the synthesized constructor only accepts the alias. Build the params through `model_validate` instead, matching how the field is populated off the wire.

cubic-dev-ai

All reported issues were addressed across 9 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

…handler A caller's `_meta.progressToken` is carried over the wire under its camelCase JSON alias but deserialized back to the snake_case field `progress_token`, so a server handler reading `params.meta` finds `progress_token`. Pin both forms of the same params object for `skills/list` and `resources/directory/read`, and expand the client round-trip test's comment to spell out the distinction.

cubic-dev-ai

All reported issues were addressed across 4 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed across 6 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

vijaydeepsinha · 2026-09-24T01:39:07Z

I don't like the fact that we are wrapping the client to expose methods, I think we can do better, but the PR itself is very self contained.

Can you please check my comments?

Also, can you please tell your agent to redo the skills.md as "Please rewrite the skills.md as if you were Sebastian Ramirez, matching the rest of the docs"?

Done.

cubic-dev-ai

All reported issues were addressed across 13 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

This reverts commit 9e0da68.

This reverts commit 5e4fb31.

Kludex · 2026-10-11T14:33:37Z

Shouldn't this be under src/mcp/client/extensions/?

Kludex · 2026-10-11T14:34:11Z

+        return BoundSkills(session)
+
+
+class BoundSkills:


Instead of BoundSkills, can we call it SkillsClient?

vijay added 9 commits September 9, 2026 20:07

Add SEP-2640 protocol types and validation

a4c6ae3

Wire types, request/result models, and SEP-2640 conformance validation (name/URI/frontmatter rules, resource-manifest completeness, digest and size verification) for the Skills extension, shared by the server and client surfaces.

Document SEP-2640 Python SDK support

0729d95

Adds the Skills page under Advanced, with a runnable server/client example, and tests proving every claim the page makes against the real SDK.

github-actions Bot added the missing-issue-link Auto-closed: PR needs a linked issue assigned to its author (see CONTRIBUTING.md) label Sep 9, 2026

github-actions Bot closed this Sep 9, 2026

pja-ant reopened this Sep 9, 2026

github-actions Bot added bypass-issue-check and removed missing-issue-link Auto-closed: PR needs a linked issue assigned to its author (see CONTRIBUTING.md) labels Sep 9, 2026

vijaydeepsinha force-pushed the sep-2640-python-sdk-support branch from 321ab53 to b845490 Compare September 10, 2026 00:12

cubic-dev-ai Bot reviewed Sep 10, 2026

View reviewed changes

vijay added 4 commits September 10, 2026 06:20

vijaydeepsinha force-pushed the sep-2640-python-sdk-support branch from 3b09033 to f1d2920 Compare September 10, 2026 00:54

cubic-dev-ai Bot reviewed Sep 10, 2026

View reviewed changes

Comment thread tests/client/extensions/test_skills.py

vijay added 4 commits September 10, 2026 06:41

Empty commit to re-trigger CI after a transient PyPI network flake

473804e

empty coomit to re-trigger ci check

a2e49d5

added changes for cache-attributes and its tests

071ad0e

pja-ant mentioned this pull request Sep 11, 2026

SEP-2640: Skills Extension modelcontextprotocol/modelcontextprotocol#2640

Merged

cubic-dev-ai Bot reviewed Sep 23, 2026

View reviewed changes

Comment thread src/mcp/shared/skills.py

vijay added 2 commits September 24, 2026 05:52

re validate the outbound payload for mutation

7ca165a

modified the docs and added check for de-dup across pages

662ce93

cubic-dev-ai Bot reviewed Sep 24, 2026

View reviewed changes

Comment thread src/mcp/server/skills.py Outdated

Comment thread src/mcp/client/skills.py Outdated

relaxed the de-dup failure

083a5dc

vijaydeepsinha requested a review from Kludex September 24, 2026 01:39

Kludex reviewed Sep 24, 2026

View reviewed changes

Comment thread src/mcp/shared/skills.py

Kludex reviewed Sep 24, 2026

View reviewed changes

Comment thread src/mcp/server/skills.py Outdated

removed extra logging and extra exports

12957be

vijaydeepsinha requested a review from Kludex September 24, 2026 11:26

danielquintas8 mentioned this pull request Sep 25, 2026

.NET: Python: [Feature]: Move MCPSkillsSource to the released SEP-2640 (skills/list and skills/get) microsoft/agent-framework#8772

Closed

Merge branch 'main' into sep-2640-python-sdk-support

03e24f0

jaredLunde mentioned this pull request Oct 6, 2026

agent: MCP Skills extension (SEP-2640) client support beyondoss/ai#131

Merged

vijaydeepsinha and others added 2 commits October 7, 2026 16:32

Merge branch 'main' into sep-2640-python-sdk-support

01e5234

Expose typed client extension APIs and tighten Skills validation

3f45540

cubic-dev-ai Bot reviewed Oct 10, 2026

View reviewed changes

Comment thread docs/advanced/extensions.md Outdated

Kludex added 7 commits October 11, 2026 13:46

Link the Skills server setup from the extension example

18e0634

Keep skill resource verification in the shared API

aea9f96

Verify skill resources through the client extension

5e4fb31

Default skill reads to the main resource

9e0da68

Revert "Default skill reads to the main resource"

36264c2

This reverts commit 9e0da68.

Revert "Verify skill resources through the client extension"

c7c4a95

This reverts commit 5e4fb31.

Limit Skills client API to catalog methods

7ff625f

Kludex reviewed Oct 11, 2026

View reviewed changes

Move Skills client API into extensions

52143f9

Kludex approved these changes Oct 11, 2026

View reviewed changes

Kludex merged commit 9a754b0 into modelcontextprotocol:main Oct 11, 2026
34 checks passed

vijaydeepsinha mentioned this pull request Oct 11, 2026

Add a filesystem backed provider for the Skills extension #3683

Open

Conversation

vijaydeepsinha commented Sep 9, 2026 • edited by Kludex Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation and Context

What's included

Server usage

Client usage

Protocol version / compatibility notes

How Has This Been Tested?

Conformance

Breaking Changes

Deliberate scope exclusions (and why)

Types of changes

Checklist

AI Disclaimer

Uh oh!

pja-ant commented Sep 9, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

vijaydeepsinha commented Sep 24, 2026

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Kludex Oct 11, 2026

Choose a reason for hiding this comment

Uh oh!

Kludex Oct 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vijaydeepsinha commented Sep 9, 2026 •

edited by Kludex

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading