Merge remote-tracking branch 'origin/main' into sep-2468-validate-iss

Author: Kludex

.github/actions/conformance/expected-failures.2026-07-28.yml

@@ -118,7 +118,5 @@ server:
   # These scenarios emit no FAILURE checks, only SHOULD-level WARNINGs, but
   # the expected-failures evaluator counts WARNINGs as failures. Same entries
   # as the draft suite in expected-failures.yml.
-  # SEP-2164: server returns -32600 (not -32602) and omits error.data.uri.
-  - sep-2164-resource-not-found
   # SEP-2322 SHOULD-level behaviour (re-request missing inputResponses).
   - input-required-result-missing-input-response

.github/actions/conformance/expected-failures.yml

@@ -71,8 +71,6 @@ server:
   - http-header-validation
   # WARNING-only entries: these scenarios emit no FAILURE checks, only SHOULD-level
   # WARNINGs, but the expected-failures evaluator counts WARNINGs as failures.
-  # SEP-2164: server returns -32600 (not -32602) and omits error.data.uri.
-  - sep-2164-resource-not-found
   # SEP-2322 SHOULD-level behaviour (re-request missing inputResponses).
   - input-required-result-missing-input-response
   # SEP-2322 negative-case scenarios: input-required-result-validate-input is

.github/dependabot.yml

@@ -1,9 +1,21 @@
 version: 2
 updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: monthly
+    cooldown:
+      default-days: 14
+    groups:
+      python-packages:
+        patterns:
+          - "*"
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: monthly
+    cooldown:
+      default-days: 14
     groups:
       github-actions:
         patterns:

.github/workflows/weekly-lockfile-update.yml

@@ -8,6 +8,17 @@ Version 2 of the MCP Python SDK introduces several breaking changes to improve t
 
 ## Breaking Changes
 
+### `MCPServer.call_tool()` returns `CallToolResult`
+
+`MCPServer.call_tool()` now always returns a `CallToolResult`. It previously
+advertised `Sequence[ContentBlock] | dict[str, Any]` and leaked the internal
+conversion shapes (a bare content sequence or a `(content, structured_content)`
+tuple), forcing callers to re-assemble a `CallToolResult` themselves.
+
+If you call `MCPServer.call_tool()` directly, read `.content` and
+`.structured_content` off the returned `CallToolResult` instead of branching on
+the result type.
+
 ### `streamablehttp_client` removed
 
 The deprecated `streamablehttp_client` function has been removed. Use `streamable_http_client` instead.
@@ -509,6 +520,12 @@ async def my_tool(x: int, ctx: Context) -> str:
 
 The internal layers (`ToolManager.call_tool`, `Tool.run`, `Prompt.render`, `ResourceTemplate.create_resource`, etc.) now require `context` as a positional argument.
 
+### Resource not found returns `-32602` and resource lookups raise typed exceptions (SEP-2164)
+
+Reading a missing resource now returns JSON-RPC error code `-32602` (invalid params) with the requested URI in `error.data` (`{"uri": ...}`), per [SEP-2164](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2164). Previously the server returned code `0` with no `data`. Clients can now reliably distinguish not-found from other errors; a template handler that raises `ResourceNotFoundError` (from `mcp.server.mcpserver.exceptions`) produces this same response.
+
+The underlying lookups now raise typed exceptions instead of `ValueError`. `ResourceManager.get_resource()` raises `ResourceNotFoundError` when no resource or template matches the URI, and `ResourceTemplate.create_resource()` raises `ResourceError` when the template function fails. Neither subclasses `ValueError`, so callers catching `ValueError` should switch to `ResourceNotFoundError` / `ResourceError` (both importable from `mcp.server.mcpserver.exceptions`; `ResourceNotFoundError` subclasses `ResourceError`).
+
 ### Registering lowlevel handlers from `MCPServer`
 
 `MCPServer` does not expose public APIs for `subscribe_resource`, `unsubscribe_resource`, or `set_logging_level` handlers. In v1, the workaround was to reach into the private lowlevel server and use its decorator methods:
@@ -1232,6 +1249,16 @@ Tasks are expected to return as a separate MCP extension in a future release.
 
 ## Bug Fixes
 
+### OAuth metadata URLs no longer gain a trailing slash
+
+`OAuthMetadata`, `ProtectedResourceMetadata`, and `OAuthClientMetadata` now set
+`url_preserve_empty_path=True` (Pydantic 2.12+). A path-less URL parsed from the wire keeps its
+empty path instead of acquiring a trailing slash, so e.g. an `issuer` of `https://as.example.com`
+round-trips as `https://as.example.com` rather than `https://as.example.com/`. This matters for
+RFC 9207 / RFC 8414 issuer comparisons, which require simple string comparison (RFC 3986 §6.2.1).
+URLs constructed in Python from an already-built `AnyHttpUrl` object are unaffected (they were
+normalized at construction); only values parsed from strings/JSON change.
+
 ### Lowlevel `Server`: `subscribe` capability now correctly reported
 
 Previously, the lowlevel `Server` hardcoded `subscribe=False` in resource capabilities even when a `subscribe_resource()` handler was registered. The `subscribe` capability is now dynamically set to `True` when an `on_subscribe_resource` handler is provided. Clients that previously didn't see `subscribe: true` in capabilities will now see it when a handler is registered, which may change client behavior.

docs/migration.md

@@ -97,7 +97,9 @@ async def main():
 
     Pinning to ``2026-07-28`` or later selects the stateless transport era: no initialize
     handshake is sent on the wire (the session synthesizes its `InitializeResult` locally),
-    and for HTTP the ``MCP-Protocol-Version`` header is set from the first request.
+    and for HTTP the ``MCP-Protocol-Version`` header is set from the first request. A modern
+    pin currently requires a URL or `Transport`; the in-memory `Server`/`MCPServer` path
+    does not yet have a modern entry point.
     Leave as ``None`` to negotiate the version via the initialize handshake.
     """
 

src/mcp/client/client.py

@@ -93,13 +93,14 @@ def __init__(self, url: str, protocol_version: str | None = None) -> None:
 
         Args:
             url: The endpoint URL.
-            protocol_version: Pin the MCP-Protocol-Version header from the first request
-                instead of waiting to snoop it from an InitializeResult. Required for
-                stateless 2026-07-28 sessions that never send initialize.
+            protocol_version: Pin the MCP-Protocol-Version header from the first request.
+                Only honoured for stateless 2026-07-28+ sessions that never send
+                initialize; for earlier (stateful) versions the header is populated
+                from the negotiated InitializeResult, so a pre-2026 value is ignored.
         """
         self.url = url
         self.session_id: str | None = None
-        self.protocol_version: str | None = protocol_version
+        self.protocol_version: str | None = protocol_version if protocol_version in MODERN_PROTOCOL_VERSIONS else None
 
     def _per_message_headers(self, message: JSONRPCMessage) -> dict[str, str]:
         """Per-POST routing headers (Mcp-Method, Mcp-Name) for 2026-07-28+ pinned transports.
@@ -158,7 +159,8 @@ def _maybe_extract_session_id_from_response(self, response: httpx.Response) -> N
     def _maybe_extract_protocol_version_from_message(self, message: JSONRPCMessage) -> None:
         """Extract protocol version from initialization response message."""
         if self.protocol_version is not None:
-            # Constructor pin wins over snooping the InitializeResult.
+            # Only a modern constructor pin reaches here (pre-2026 values are dropped
+            # in __init__), and a modern pin never sends initialize.
             return
         if isinstance(message, JSONRPCResponse) and message.result:  # pragma: no branch
             try:

src/mcp/client/streamable_http.py

@@ -113,6 +113,10 @@ async def read_resource(self, uri: str | AnyUrl) -> Iterable[ReadResourceContent
 
         Returns:
             The resource content as either text or bytes
+
+        Raises:
+            ResourceNotFoundError: If no resource or template matches the URI.
+            ResourceError: If template creation or resource reading fails.
         """
         assert self._mcp_server is not None, "Context is not available outside of a request"
         return await self._mcp_server.read_resource(uri, self)

src/mcp/server/mcpserver/context.py

@@ -13,6 +13,15 @@ class ResourceError(MCPServerError):
     """Error in resource operations."""
 
 
+class ResourceNotFoundError(ResourceError):
+    """Resource does not exist.
+
+    Raise this from a resource template handler to signal that the requested instance does not exist;
+    clients receive `-32602` (invalid params) per
+    [SEP-2164](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2164).
+    """
+
+
 class ToolError(MCPServerError):
     """Error in tool operations."""
 

src/mcp/server/mcpserver/exceptions.py

@@ -7,6 +7,7 @@
 
 from pydantic import AnyUrl
 
+from mcp.server.mcpserver.exceptions import ResourceNotFoundError
 from mcp.server.mcpserver.resources.base import Resource
 from mcp.server.mcpserver.resources.templates import ResourceTemplate
 from mcp.server.mcpserver.utilities.logging import get_logger
@@ -79,7 +80,12 @@ def add_template(
         return template
 
     async def get_resource(self, uri: AnyUrl | str, context: Context[LifespanContextT, RequestT]) -> Resource:
-        """Get resource by URI, checking concrete resources first, then templates."""
+        """Get resource by URI, checking concrete resources first, then templates.
+
+        Raises:
+            ResourceNotFoundError: If no resource or template matches the URI.
+            ResourceError: If a matching template fails to create the resource.
+        """
         uri_str = str(uri)
         logger.debug("Getting resource", extra={"uri": uri_str})
 
@@ -90,12 +96,9 @@ async def get_resource(self, uri: AnyUrl | str, context: Context[LifespanContext
         # Then check templates
         for template in self._templates.values():
             if params := template.matches(uri_str):
-                try:
-                    return await template.create_resource(uri_str, params, context=context)
-                except Exception as e:  # pragma: no cover
-                    raise ValueError(f"Error creating resource from template: {e}")
+                return await template.create_resource(uri_str, params, context=context)
 
-        raise ValueError(f"Unknown resource: {uri}")
+        raise ResourceNotFoundError(f"Unknown resource: {uri}")
 
     def list_resources(self) -> list[Resource]:
         """List all registered resources."""