fix(server): return -32602 for nonexistent resources (SEP-2164)#2267
Draft
mattzcarey wants to merge 1 commit into
Draft
fix(server): return -32602 for nonexistent resources (SEP-2164)#2267mattzcarey wants to merge 1 commit into
mattzcarey wants to merge 1 commit into
Conversation
Per SEP-2164, the draft spec upgrades resource-not-found handling from SHOULD return -32002 (2025-11-25) to MUST return -32602 (Invalid params). The requested URI is included in the error's data.uri so clients can still distinguish not-found from other invalid-params errors. ProtocolErrorCode.ResourceNotFound (-32002) is deprecated but remains exported, since clients SHOULD still accept it from older servers. Closes #2194
🦋 Changeset detectedLatest commit: 1f43d9c The changes in this PR will be included in the next version bump. This PR includes changesets to release 2 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
@modelcontextprotocol/client
@modelcontextprotocol/codemod
@modelcontextprotocol/server
@modelcontextprotocol/server-legacy
@modelcontextprotocol/express
@modelcontextprotocol/fastify
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements SEP-2164: reads of nonexistent resources now fail with JSON-RPC
-32602(Invalid params) instead of the MCP-specific-32002(ProtocolErrorCode.ResourceNotFound). The requested URI is carried in the error'sdata.uriso clients can still distinguish not-found from other invalid-params failures.Spec citation
The draft spec (
server/resources.mdx, ~L395-398) says:Note the history: the 2025-11-25 revision said servers SHOULD return
-32002; the draft (SEP-2164) flips this to MUST return-32602, keeping-32002only as a legacy code clients should tolerate.This reverses a recent deliberate change
#1389 (shipped in
2.0.0-alpha.1) intentionally moved unknown-resource reads from-32602→-32002and introducedProtocolErrorCode.ResourceNotFound, matching the then-current SHOULD-strength spec text. SEP-2164 has since standardized the opposite direction, so this PR flips it back:McpServer'sresources/readhandler throwsProtocolErrorCode.InvalidParamswithdata: { uri }.ProtocolErrorCode.ResourceNotFoundis marked@deprecatedbut remains exported — clients may still need to match it from older servers, per the spec's "SHOULD also accept legacy-32002" language.-32002.Open design question for maintainers
Implemented as an unconditional flip — should this instead be gated on the negotiated protocol version (runtime still defaults to 2025-11-25, where
-32002was SHOULD-strength)? Unconditional seems defensible since the draft tells clients to accept both, but flagging for a direction call. (The 2026-07-28 reference types from #2252 already define onlyINVALID_PARAMSfor this case.)Draft until that's resolved.
Changes
packages/server/src/server/mcp.ts:resources/readnot-found path throwsInvalidParamswithdata: { uri }packages/core/src/types/enums.ts:ResourceNotFounddeprecated with JSDoc pointing atInvalidParamsper SEP-2164test/integration/test/server/mcp.test.ts: unknown-resource test now asserts-32602+data.uritest/e2e/scenarios/resources.test.ts+test/e2e/requirements.ts:resources:read:unknown-uriupdated to-32602with a manifest note on the SEP-2164 SHOULD→MUST history@modelcontextprotocol/server+@modelcontextprotocol/core)Validation
pnpm build:all,pnpm typecheck:all,pnpm lint:all: passprotocol:timeout:max-total [sse](unrelated, fails only under full-suite parallel load)bearerAuth"expired 0 seconds ago") failed once under the full run, passes 3/3 in isolation — unrelatedDownstream impact: cloudflare/agents MCPAgent servers will emit -32602 for unknown resources after upgrading; grep confirms no agents code branches on -32002, so no downstream changes needed.
Closes #2194