fix: prefix auth routes with issuer_url base path for gateway deployments

[enjoykumawat]

Summary

Fixes #1335 — When an MCP server is deployed behind a gateway with a custom base path (e.g., https://gateway/custom/path/mcp), the OAuth auth routes (.well-known, /authorize, /token, /register, /revoke) are hardcoded at root, making them unreachable through the gateway.

Root cause: create_auth_routes() registers routes at fixed root paths (/.well-known/oauth-authorization-server, /authorize, etc.) regardless of the issuer_url path. Meanwhile, build_metadata() correctly builds metadata URLs using issuer_url + path, creating a mismatch.

Fix: Extract the path component from issuer_url and prefix it to all auth route registrations. This aligns the actual route paths with the metadata URLs already built by build_metadata().

# issuer_url = "https://example.com/custom/path"
# Before: routes at /authorize, /token, etc. (unreachable behind gateway)
# After:  routes at /custom/path/authorize, /custom/path/token, etc.

Backward compatible: when issuer_url has no path (or just /), issuer_path is empty and routes stay at root.

Changes

• src/mcp/server/auth/routes.py: Extract issuer_path from issuer_url and prefix all route paths
• tests/server/auth/test_routes.py: Add 3 tests for default paths, custom base path, and trailing slash handling

Test plan

• All 12 test_routes.py tests pass (9 existing + 3 new)
• All 4 test_error_handling.py tests pass (no regression)
• All 42 test_auth_integration.py tests pass (no regression)
• Ruff format + lint clean

[enjoykumawat]

Friendly ping — happy to address any feedback or make changes if needed. Let me know if there's anything blocking review.

[aadnehovda]

.well-known is only compliant at domain root, see https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#protected-resource-metadata-discovery-requirements and https://datatracker.ietf.org/doc/html/rfc8615#section-3 :

Well-known URIs are rooted in the top of the path's hierarchy; they are not well-known by definition in other parts of the path. For example, "/.well-known/example" is a well-known URI, whereas "/foo/.well-known/example" is not.

This prefixing also competes with Mounting the app under a prefix, like in https://gofastmcp.com/deployment/http#mounting-strategy ?

Which is why FastMCP has get_well_known_routes to extract those routes before Mounting, while patching up .well-known at https://github.com/PrefectHQ/fastmcp/blob/53b20168c892b05b86ea8bf576a33b95936dda26/fastmcp_slim/fastmcp/server/auth/auth.py#L831-L872.

Prefixing the rest of the endpoints makes sense, but afaict FastMCP has hardcoded references to /authorize, /token, etc which may break.

For trusted reverse proxying we could get the scheme and host via X-Forwarded-*, and even the dynamic base path via X-Forwarded-Prefix.

It would be nice if someone took a long hard look at all the various pieces in play here, like proxy forwarding headers and path stripping, FastMCP path (which annoyingly cannot be "", which means you can't avoid the last / with Mount), uvicorn --root-path, Starlette Mount, etc. and avoid overrides and hardcoding. I get the feeling that a lot of this belongs in middleware and not in route construction. E.g. if the routes were named, they could be referenced and resolved by handlers during runtime when they need to be injected into the response with request.url_for(...), which would make them respect namespacing and rewriting middleware.

Just my 2c

[enjoykumawat]

Good catch, thanks — and you're right that this needed a real fix, not just a caveat.

Pushed a3918ebe: the .well-known/oauth-authorization-server route now inserts the well-known suffix between the authority and the issuer's path, per RFC 8414 §3.1 (https://example.com/.well-known/oauth-authorization-server/custom/path), instead of appending it after the path. The old placement (/custom/path/.well-known/...) isn't a valid well-known URI under RFC 8615 §3, exactly as you flagged.

The /authorize, /token, /register, /revoke routes are unaffected by this correction — they're plain URLs registered under the issuer's own path, not well-known URIs, so RFC 8615's root-only constraint doesn't apply to them.

On the broader Mount/forwarded-headers point: agreed that's a real and larger design question (how this interacts with Starlette Mount, X-Forwarded-Prefix, and hardcoded FastMCP paths), but it's bigger than this PR's scope — this fix is narrowly about not violating RFC 8615 in the route construction itself. Happy to see a follow-up issue for the mounting/proxying story if that'd be useful.

[cubic-dev-ai]

No issues found across 2 files

_{Re-trigger cubic}

[maxisbey]

Thanks for the PR, and sorry it sat here without a proper review.

We're closing most of the open PR backlog. v2 is out and changed a lot of the SDK, so many older PRs no longer apply as written, and we're a small team that realistically doesn't have the capacity to work through the rest.

If this still matters to you on v2, the most useful thing you can do is open an issue (or comment on the existing one) with your use case and a repro. Hearing why it matters to you is what we use to decide what to prioritise.

_{AI Disclaimer}