[v1.x] docs(server/auth): document that resourceServerUrl and resourceMetadataUrl are needed for MCP-compliant discovery - #2752
Open
bumhwan wants to merge 1 commit into
Conversation
…eMetadataUrl are needed for MCP-compliant discovery Both options are optional in the types, but for an MCP server both are effectively required: without resourceServerUrl the Protected Resource Metadata is served at the root well-known with resource set to the origin (not the MCP endpoint), and without resourceMetadataUrl the 401 challenge has no resource_metadata parameter, which the MCP authorization spec requires. Clients that enforce RFC 9728 §3.3 literally (Gemini CLI, Antigravity CLI) abort discovery on the resulting documents while the reference client accepts them, so server authors get no signal. Spell this out in the JSDoc. No behaviour change. Refs modelcontextprotocol#2751 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
|
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.
Motivation and Context
Follow-up to #2751. When an MCP endpoint lives under a path (the usual
/mcp), omittingresourceServerUrlonmcpAuthRouterandresourceMetadataUrlonrequireBearerAuthsilently produces discovery that the MCP authorization spec and RFC 9728 do not allow: PRM at the root well-known withresource: https://host/, and a 401 challenge withoutresource_metadata. The reference client tolerates this, so the only symptom is that strict clients (Gemini CLI, Antigravity CLI) fail discovery withResourceMismatchError.Both options are documented as merely "optional". This PR makes the JSDoc say what each one is for, that the MCP spec requires the
resource_metadatachallenge parameter, and what happens when they are left out.How Has This Been Tested?
JSDoc-only change, no behaviour change.
prettier --checkpasses on the touched files. The underlying behaviour (root-only PRM with originresource, missingresource_metadata) was reproduced against v1.x as described in #2751.Breaking Changes
None.
Types of changes
Checklist
🤖 Generated with Claude Code