[bh-wise]

Motivation and Context

When requesting server.com/resource/, the SDK uses server.com/.well-known/oauth-protected-resource/resource for the OAuth Protected Resource metadata. This is a bug -- RFC 9728 §3.1 requires removal of a "terminating slash (/) following the host component" but not following the path. This PR fixes the bug.

How Has This Been Tested?

I created new unit tests to test this.

Breaking Changes

None.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• 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

[changeset-bot]

🦋 Changeset detected

Latest commit: 4d091aa

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@modelcontextprotocol/client	Patch
@modelcontextprotocol/server	Patch
@modelcontextprotocol/codemod	Patch
@modelcontextprotocol/core	Patch
@modelcontextprotocol/server-legacy	Patch
@modelcontextprotocol/core-internal	Patch

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

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@3062

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@3062

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@3062

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@3062

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@3062

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@3062

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@3062

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@3062

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@3062

commit: 4d091aa

[arhancanli]

Read the diff (didn't run the suite). Keeping the trailing slash on non-root paths matches RFC 9728 section 3.1 as I read it: only the slash right after the host is dropped before /.well-known/oauth-protected-resource is inserted, so /mcp/ -> .../oauth-protected-resource/mcp/ is the spec form.

The risk is the one the changeset already names: a server that only serves the stripped /mcp path now gets a 404 on the first probe and the new test shows the next probe is the root URL, never .../mcp. Servers that registered metadata at the old URL then fall through to the root document, which may describe a different resource. Would it be worth one extra fallback to the stripped form between the two (and a test pinning the order), or is the intent to be strict? Either is defensible, but the order should be explicit.

[bh-wise]

The risk is the one the changeset already names: a server that only serves the stripped /mcp path now gets a 404 on the first probe and the new test shows the next probe is the root URL, never .../mcp. Servers that registered metadata at the old URL then fall through to the root document, which may describe a different resource. Would it be worth one extra fallback to the stripped form between the two (and a test pinning the order), or is the intent to be strict? Either is defensible, but the order should be explicit.

What's the concern here -- if a server has a resource of /mcp/ (with trailing slash) but only publishes metadata at /.well-known/oauth-protected-resource/mcp (without trailing slash)? I'd say that's a bug in the server so I'm not inclined to do anything to accommodate -- that said, I can see an argument for including some sort of transitional support until v3 (especially if we were to say that this is a breaking change). What do others think?

[arhancanli]

Yes, that is the case I meant, and I agree with you that strict is right. RFC 9728 §3.1 builds the metadata URL by inserting the well-known segment between host and path and keeping the path as written, so https://host/mcp/ maps to /.well-known/oauth-protected-resource/mcp/. §3.3 then requires the resource value in the document to be identical to the URL the client used, so a server that answers /mcp/ from the stripped-path document is already non-conformant.

If a transitional fallback is added anyway, I would put it after the exact URL and before the root document, and pin that order in a test. Falling through to root is the worse outcome because root may describe a different resource. The fallback result could also be checked against the §3.3 resource rule, which would reject a stripped-path document that names /mcp instead of /mcp/.

Do you know whether the existing OAuth conformance servers publish under a trailing-slash path, or only the stripped form?

[bh-wise]

Let's see what the maintainer(s) say, but I'm glad we're agreed that transitional support for buggy MCP servers is a waste of everyone's time.

FYI: §3.3 validation is mandatory -- it's "must be checked" rather than "could be checked". The SDK is currently more permissive than this but IMO that should be a separate change (and probably requires some discussion / alignment first!).

The current conformance metadata-discovery scenarios use /mcp without a trailing slash so this case doesn't apply.

[JosephDoUrden]

ran client auth.test (278/278), server oauthMetadata.test (19/19), authUtils (12/12). also ran the client against our own oauthMetadataResponse with /mcp, /mcp/ and ?query on both sides, first probe hits every time. merges clean with #3042. small thing: server oauthMetadata.ts:102 still strips the slash when building the PRM path, so client and server disagree now. follow-up, lgtm

[crablab]

@JosephDoUrden 👋 Hey - picking this up on Ben's behalf. Thank you for taking the time to review; I've adjusted the PR to fix that small point.

Is there anything else you'd like to see for us to get this merged? Thanks!