Add SkillCatalog and FilesystemSkillProvider for serving skills from a directory - #3795

Fixes #3683

Adds an optional helper that serves a directory of skills through the existing Skills extension, without changing the protocol or the Skills API. mcp/server/skills.py becomes a package; from mcp.server.skills import Skills and the handler aliases still work.

Motivation and Context

Serving skills from disk currently means writing handlers and registering every file as a resource by hand. This adds:

• SkillProvider: a small protocol for listing and reading files.
• FilesystemSkillProvider: a local-directory provider that skips symlinks and junctions and runs blocking I/O in a worker thread.
• SkillCatalog: a Skills extension that scans a provider, validates each skill, and answers skills/list, skills/get and optionally resources/directory/read. Manifest digests always match what resources/read serves, and a file that changed after the last scan is refused.
• SkillCatalog.reload(): rescans the provider and swaps the new catalog in all at once, returning the skills added, removed and changed. If the scan fails, the previous catalog keeps serving; concurrent calls run one after another.
• auto_refresh=True (off by default) with refresh_interval (seconds, default 60): reloads on a timer while the server runs, serving the bytes it scanned so manifests and content stay consistent between refreshes. A failed refresh is logged and the previous catalog keeps serving.

Optional pagination (page_size) and SEP-2549 cache hints (ttl_ms, cache_scope) are supported.

To let a catalog change while the server runs, Extension gains two optional hooks, both off by default:

• resources_are_dynamic = True: the server asks resources() again on each listing and lookup instead of copying it once. Returning the same tuple until something changes lets lookups reuse a URI index. Resources registered directly on the server still win URI collisions.
• lifespan(): an async context manager entered inside the application's lifespan, used for the refresh timer.

Server usage

from pathlib import Path

import anyio
import yaml

from mcp.server.mcpserver import MCPServer
from mcp.server.skills import FilesystemSkillProvider, SkillCatalog


async def main() -> None:
    catalog = await SkillCatalog.load(
        FilesystemSkillProvider(Path("skills")),
        parse_frontmatter=yaml.safe_load,
        directory_read=True,
        auto_refresh=True,
        refresh_interval=30,
    )
    server = MCPServer("my-server", extensions=[catalog])
    await server.run_stdio_async()


anyio.run(main)

How Has This Been Tested?

All run locally on macOS

• ./scripts/test, twice: 6,377 passed, 100.00% statement and branch coverage, strict-no-cover clean.
• Python 3.11, 3.12, 3.14 and 3.15 (3.15.0rc3) locked environments, same command: all passed at 100.00%.
• lowest-direct resolution on 3.11, and MCP_EXAMPLES_SMOKE=1 on 3.12: all passed.
• ruff format, ruff check, pyright, pre-commit on the changed files, README snippet check, gen_surface_types.py --check, the standalone mcp-types import check, and the Node workflow tests: all clean.
• scripts/docs/build.sh: every language built with 0 warnings.
• Manually through Postman against real servers on both the legacy 2025-11-25 and the 2026-07-28 protocol versions: list/get/read, pagination, directory reads enabled and disabled, and auto-refresh picking up skills added and removed on disk without a restart.

Conformance

CI's pinned harness (@modelcontextprotocol/conformance@0.2.0-alpha.11), all suites, run exactly as conformance.yml does:

The baseline check passes on every leg.

The pinned harness has no SEP-2640 scenarios, so I also ran them from the conformance repository (modelcontextprotocol/conformance#330), against servers built with SkillCatalog + FilesystemSkillProvider, one with auto_refresh=True and one with page_size=2:

The four sep-2640-client-* scenarios pass 1/1 each.

Breaking Changes

None. Existing public signatures and defaults are unchanged; the new SkillCatalog options and the Extension hooks are optional and off by default.

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

Additional context

• The SDK has no YAML dependency; the examples use PyYAML.
• Reloading does not notify connected clients; they see changes on their next request. Sending resources/list_changed after a reload could be a follow-up if wanted.