Add Toolset Versioning extension prototype.

Implements io.modelcontextprotocol/toolsets with toolsets/list, pin filtering on tools/list and tools/call, client helpers, docs, and tests.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: palmertron

docs/advanced/toolsets.md

@@ -0,0 +1,73 @@
+# Toolsets
+
+**Toolsets** are named, SemVer-versioned, immutable capability surfaces: a fixed
+membership of tool names that a client can discover and pin on `tools/list` and
+`tools/call`. They address uncontrolled tool-surface expansion when agents discover
+tools dynamically — a client pinned to `core-ops@1.2.0` never sees tools that only
+exist in a later Toolset version.
+
+This SDK ships Toolsets as the built-in `Toolsets` extension
+(`io.modelcontextprotocol/toolsets`), matching the Toolset Versioning SEP draft.
+If [Extensions](extensions.md) are new to you, skim that page first.
+
+## Advertise and publish
+
+```python
+from mcp.server.mcpserver import MCPServer
+from mcp.server.toolsets import Toolsets
+
+toolsets = Toolsets()
+mcp = MCPServer("crm", extensions=[toolsets])
+
+@mcp.tool()
+def search_contacts(query: str) -> str:
+    return f"found:{query}"
+
+@mcp.tool()
+def analyze_report(report_id: str) -> str:
+    return f"report:{report_id}"
+
+toolsets.add_toolset(
+    name="core-ops",
+    version="1.2.0",
+    status="stable",
+    tools=["search_contacts"],
+)
+toolsets.add_toolset(
+    name="core-ops",
+    version="1.3.0",
+    status="stable",
+    tools=["search_contacts", "analyze_report"],
+)
+```
+
+`(name, version)` is immutable once published. Register ordinary tools with
+`@mcp.tool()`; Toolsets only declare membership by name.
+
+## Client pin
+
+Clients that pin Toolsets must advertise the extension, then pass the same
+`ToolsetRef` on list and call:
+
+```python
+from mcp import Client
+from mcp.client import advertise
+from mcp.server.toolsets import EXTENSION_ID
+from mcp_types import ToolsetRef
+
+pin = ToolsetRef(name="core-ops", version="1.2.0")
+
+async with Client(mcp, extensions=[advertise(EXTENSION_ID)]) as client:
+    published = await client.list_toolsets()
+    tools = await client.list_tools(toolset=pin)  # no analyze_report
+    result = await client.call_tool("search_contacts", {"query": "acme"}, toolset=pin)
+```
+
+Omitting `toolset` keeps today's full flat catalog. Calling a non-member under a
+pin returns a protocol `MCPError` (`reason: tool_not_in_toolset`), not a tool
+`is_error` result.
+
+## Cache keys
+
+Pinned `tools/list` responses are cached separately from the unpinned catalog
+(and from other pins). Distinct pins never reuse an unpinned cache entry.

mkdocs.yml

@@ -67,6 +67,7 @@ nav:
       - Middleware: advanced/middleware.md
       - Extensions: advanced/extensions.md
       - MCP Apps: advanced/apps.md
+      - Toolsets: advanced/toolsets.md
   - Troubleshooting: troubleshooting.md
   - Migration Guide: migration.md
   - API Reference: api/

src/mcp-types/mcp_types/__init__.py

@@ -93,7 +93,11 @@
     ListRootsResult,
     ListTasksRequest,
     ListTasksResult,
+    ListToolsetsRequest,
+    ListToolsetsRequestParams,
+    ListToolsetsResult,
     ListToolsRequest,
+    ListToolsRequestParams,
     ListToolsResult,
     LoggingCapability,
     LoggingLevel,
@@ -184,6 +188,9 @@
     ToolListChangedNotification,
     ToolResultContent,
     ToolsCapability,
+    Toolset,
+    ToolsetRef,
+    ToolsetStatus,
     ToolUseContent,
     UnsubscribeRequest,
     UnsubscribeRequestParams,
@@ -336,6 +343,13 @@
     "CancelTaskRequest",
     "CancelTaskRequestParams",
     "CreateMessageRequest",
+    "ListToolsetsRequestParams",
+    "ListToolsetsResult",
+    "ListToolsetsRequest",
+    "ListToolsRequestParams",
+    "Toolset",
+    "ToolsetRef",
+    "ToolsetStatus",
     "CreateMessageRequestParams",
     "DiscoverRequest",
     "ElicitRequest",

src/mcp-types/mcp_types/_types.py

@@ -188,6 +188,69 @@ class PaginatedResult(Result):
     """
 
 
+ToolsetStatus = Literal["stable", "deprecated", "experimental"]
+"""Lifecycle status of a published Toolset version (toolsets extension)."""
+
+
+class ToolsetRef(MCPModel):
+    """Reference to a published Toolset `(name, version)` pin."""
+
+    name: str
+    """Toolset identifier within the server."""
+    version: str
+    """Exact Toolset SemVer. Ranges are not supported in v1."""
+
+
+class Toolset(MCPModel):
+    """A named, versioned, immutable capability surface (toolsets extension)."""
+
+    name: str
+    """Toolset identifier within the server. Unique together with `version`."""
+    version: str
+    """Semantic Version 2.0.0 of this Toolset publication."""
+    title: str | None = None
+    """Optional human-readable display name."""
+    description: str | None = None
+    """Optional description of the capability surface."""
+    status: ToolsetStatus = "stable"
+    """Lifecycle status of this Toolset version."""
+    tools: list[str]
+    """Fixed membership: tool names included in this surface."""
+    deprecation_date: str | None = None
+    """Optional ISO-8601 date after which clients SHOULD stop selecting this version."""
+
+
+class ListToolsetsRequestParams(RequestParams):
+    """Parameters for `toolsets/list`."""
+
+    name: str | None = None
+    """If set, only Toolsets with this name."""
+    status: ToolsetStatus | None = None
+    """If set, only Toolsets with this status."""
+    cursor: str | None = None
+    """Opaque pagination cursor."""
+
+
+class ListToolsetsResult(PaginatedResult):
+    """Result of `toolsets/list`."""
+
+    toolsets: list[Toolset]
+
+
+class ListToolsetsRequest(Request[ListToolsetsRequestParams, Literal["toolsets/list"]]):
+    """Discover published Toolsets on a server that supports the toolsets extension."""
+
+    method: Literal["toolsets/list"] = "toolsets/list"
+    params: ListToolsetsRequestParams
+
+
+class ListToolsRequestParams(PaginatedRequestParams):
+    """Parameters for `tools/list`, including an optional Toolset pin."""
+
+    toolset: ToolsetRef | None = None
+    """When set, restrict the listing to this Toolset's membership."""
+
+
 class CacheableResult(Result):
     """Base class for results that carry client-side caching directives (2026-07-28).
 
@@ -1351,10 +1414,12 @@ class PromptListChangedNotification(
     params: NotificationParams | None = None
 
 
-class ListToolsRequest(PaginatedRequest[Literal["tools/list"]]):
+class ListToolsRequest(Request[ListToolsRequestParams | None, Literal["tools/list"]]):
     """Sent from the client to request a list of tools the server has."""
 
     method: Literal["tools/list"] = "tools/list"
+    params: ListToolsRequestParams | None = None
+    """Pagination + optional Toolset pin. Session layer materializes `_meta` on modern versions."""
 
 
 class ToolAnnotations(MCPModel):
@@ -1446,6 +1511,8 @@ class CallToolRequestParams(InputResponseRequestParams):
     arguments: dict[str, Any] | None = None
     task: TaskMetadata | None = None
     """If specified, the caller requests task-augmented execution (2025-11-25 only)."""
+    toolset: ToolsetRef | None = None
+    """When set, the tool MUST be a member of this Toolset (toolsets extension)."""
 
 
 class CallToolRequest(Request[CallToolRequestParams, Literal["tools/call"]]):

src/mcp/client/client.py

@@ -29,6 +29,9 @@
     ListPromptsResult,
     ListResourcesResult,
     ListResourceTemplatesResult,
+    ListToolsetsRequestParams,
+    ListToolsetsResult,
+    ListToolsRequestParams,
     ListToolsResult,
     LoggingLevel,
     PaginatedRequestParams,
@@ -38,6 +41,7 @@
     ResourceTemplateReference,
     Result,
     ServerCapabilities,
+    ToolsetRef,
 )
 from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
 from typing_extensions import deprecated
@@ -543,10 +547,12 @@ async def _cached_fetch(
         cache_mode: CacheMode,
         send: Callable[[], Awaitable[_CacheableT]],
         absorb: Callable[[_CacheableT], _CacheableT] | None = None,
+        cache_key: str = "",
     ) -> _CacheableT:
         """Serve one of the four list verbs through the response cache.
 
         `absorb` (tools/list only) re-applies session-side derived state to a served cache hit.
+        `cache_key` disambiguates variants of the same method (e.g. Toolset pins).
         """
         cache = self._response_cache
         if cache is None or cache_mode == "bypass":
@@ -564,13 +570,13 @@ async def _cached_fetch(
                 if e.code == INVALID_PARAMS:
                     await cache.evict_method(method)
                 raise
-        if cache_mode == "use" and (hit := await cache.read(method, "")) is not None:
+        if cache_mode == "use" and (hit := await cache.read(method, cache_key)) is not None:
             # The hit is a private deep copy, so absorption may mutate it freely.
             served = cast(_CacheableT, hit)
             return served if absorb is None else absorb(served)
-        gen = cache.capture(method, "")
+        gen = cache.capture(method, cache_key)
         result = await send()
-        await cache.write(method, "", result, gen, cache_mode)
+        await cache.write(method, cache_key, result, gen, cache_mode)
         return result
 
     async def list_resources(
@@ -742,6 +748,7 @@ async def call_tool(
         input_responses: InputResponses | None = None,
         request_state: str | None = None,
         meta: RequestParamsMeta | None = None,
+        toolset: ToolsetRef | None = None,
     ) -> CallToolResult:
         """Call a tool on the server.
 
@@ -768,6 +775,7 @@ async def call_tool(
                 resuming from a persisted `InputRequiredResult`).
             request_state: Opaque state to seed the first call with.
             meta: Additional metadata for the request.
+            toolset: Optional Toolset pin (toolsets extension).
 
         Returns:
             The tool result.
@@ -788,6 +796,7 @@ async def retry(r: InputResponses | None, s: str | None) -> CallToolResult | Inp
                 input_responses=r,
                 request_state=s,
                 meta=meta,
+                toolset=toolset,
                 allow_input_required=True,
                 # Input rounds resolve before a claimed result, so a claim may end any round.
                 allow_claimed=True,
@@ -910,15 +919,27 @@ async def list_tools(
         *,
         cursor: str | None = None,
         meta: RequestParamsMeta | None = None,
+        toolset: ToolsetRef | None = None,
         cache_mode: CacheMode = "use",
     ) -> ListToolsResult:
-        """List available tools from the server."""
+        """List available tools from the server.
+
+        Args:
+            cursor: Pagination cursor.
+            meta: Request `_meta`.
+            toolset: Optional Toolset pin (toolsets extension).
+            cache_mode: Response-cache behaviour.
+        """
+        key = "" if toolset is None else f"{toolset.name}@{toolset.version}"
         return await self._cached_fetch(
             "tools/list",
             cursor=cursor,
             meta=meta,
             cache_mode=cache_mode,
-            send=lambda: self.session.list_tools(params=PaginatedRequestParams(cursor=cursor, _meta=meta)),
+            cache_key=key,
+            send=lambda: self.session.list_tools(
+                params=ListToolsRequestParams(cursor=cursor, toolset=toolset, _meta=meta)
+            ),
             # A cache hit skips session.list_tools, so the session re-absorbs the served
             # listing to rebuild its derived per-tool state. Hits are cursorless, but a
             # cached page 1 can carry next_cursor - never prune on a partial listing.
@@ -927,6 +948,16 @@ async def list_tools(
             ),
         )
 
+    async def list_toolsets(
+        self,
+        *,
+        name: str | None = None,
+        status: types.ToolsetStatus | None = None,
+        meta: RequestParamsMeta | None = None,
+    ) -> ListToolsetsResult:
+        """List published Toolsets (toolsets extension)."""
+        return await self.session.list_toolsets(params=ListToolsetsRequestParams(name=name, status=status, _meta=meta))
+
     @deprecated("The roots capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def send_roots_list_changed(self) -> None:
         """Send a notification that the roots list has changed."""