Merge pull request #2136 from modelcontextprotocol/v2/fix/2110-oauth-path-scoped-discovery

fix(oauth): keep the server's path in the fallback authorization-server URL (#2110)
This commit is contained in:
Cliff Hall 2026-08-26 00:44:28 -04:00 • committed by GitHub
commit dd67164bea
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 437 additions and 27 deletions

View file

@ -73,6 +73,34 @@ v2/main/
│ │ # the advertised document rather than a
│ │ # location derived from the MCP server
│ │ # URL — #2071;
│ │ # discovery.ts the authorization-server
│ │ # URL POLICY — when protected-resource
│ │ # metadata names no authorization
│ │ # server, the MCP server URL stands in,
│ │ # and its PATH is load-bearing: the
│ │ # SDK's buildDiscoveryUrls derives the
│ │ # path-scoped well-known locations from
│ │ # that pathname, so reducing it to the
│ │ # origin can only ever probe the domain
│ │ # root. getAuthorizationServerUrlCandidates
│ │ # therefore yields the path-scoped URL
│ │ # FIRST and the bare origin second, and
│ │ # discoverAuthorizationServerMetadataForServer
│ │ # walks them — the second candidate is
│ │ # what keeps a server that merely lives
│ │ # under a path while publishing metadata
│ │ # at the root working, so do not drop it
│ │ # in favour of a straight swap. EVERY
│ │ # consumer of the fallback must walk:
│ │ # discoverScopes, the CIMD probe, and
│ │ # the CLI's refreshStoredAuthToken,
│ │ # which is why the walk is also exposed
│ │ # as ...FromCandidates(candidates,
│ │ # discover) — the CLI injects its own
│ │ # discovery function as a test seam and
│ │ # needs to know WHICH candidate
│ │ # answered, since that is the base its
│ │ # token request is made against — #2110;
│ │ # scopes.ts SEP-2350 scope union, oauthUx.ts
│ │ # shared copy, mcpAuth.ts force-reauthorization,
│ │ # issuerBinding.ts SEP-2352 callback-leg failure

View file

@ -158,6 +158,97 @@ describe("refreshStoredAuthToken", () => {
}
});
// #2110: with no stored metadata the MCP server URL stands in as the
// authorization server. A path-hosted server has two plausible answers, and
// both must keep working — the path-scoped URL for a server that publishes
// its metadata under its own path, the bare origin for one that merely lives
// under a path. The candidate that answers is also the base the token request
// is made against, so the walk has to report *which* one it was.
it("prefers the path-scoped authorization server for a path-hosted MCP server", async () => {
const path = writeOAuthFixture({
[SERVER]: {
tokens: { refresh_token: "old-refresh", token_type: "Bearer" },
clientInformation: { client_id: "cid" },
},
});
try {
const refresh = vi.fn().mockResolvedValue(freshTokens);
const pathMetadata = {
issuer: "https://api.example/mcp",
token_endpoint: "https://api.example/mcp/token",
};
const discover = vi.fn().mockResolvedValue(pathMetadata);
await refreshStoredAuthToken(SERVER, path, { refresh, discover });
expect(discover).toHaveBeenCalledTimes(1);
expect(discover).toHaveBeenCalledWith(new URL("https://api.example/mcp"));
const [authServerUrl, opts] = refresh.mock.calls[0]!;
expect(authServerUrl).toEqual(new URL("https://api.example/mcp"));
expect(opts.metadata).toEqual(pathMetadata);
} finally {
rmSync(path, { force: true });
}
});
it("falls back to the origin when a path-hosted server publishes metadata at the root", async () => {
const path = writeOAuthFixture({
[SERVER]: {
tokens: { refresh_token: "old-refresh", token_type: "Bearer" },
clientInformation: { client_id: "cid" },
},
});
try {
const refresh = vi.fn().mockResolvedValue(freshTokens);
const rootMetadata = {
issuer: "https://api.example",
token_endpoint: "https://api.example/token",
};
const discover = vi
.fn()
.mockResolvedValueOnce(undefined)
.mockResolvedValueOnce(rootMetadata);
const token = await refreshStoredAuthToken(SERVER, path, {
refresh,
discover,
});
expect(token).toBe("refreshed-access-token");
expect(discover).toHaveBeenNthCalledWith(
2,
new URL("https://api.example/"),
);
// The candidate that answered is the one the token request targets.
const [authServerUrl, opts] = refresh.mock.calls[0]!;
expect(authServerUrl).toEqual(new URL("https://api.example/"));
expect(opts.metadata).toEqual(rootMetadata);
} finally {
rmSync(path, { force: true });
}
});
it("keeps the path-scoped candidate as the token-request base when no candidate answers", async () => {
const path = writeOAuthFixture({
[SERVER]: {
tokens: { refresh_token: "old-refresh", token_type: "Bearer" },
clientInformation: { client_id: "cid" },
},
});
try {
const refresh = vi.fn().mockResolvedValue(freshTokens);
const discover = vi.fn().mockResolvedValue(undefined);
await refreshStoredAuthToken(SERVER, path, { refresh, discover });
expect(discover).toHaveBeenCalledTimes(2);
const [authServerUrl] = refresh.mock.calls[0]!;
expect(authServerUrl).toEqual(new URL("https://api.example/mcp"));
} finally {
rmSync(path, { force: true });
}
});
it("uses the distinct no_client_information code when client info is missing", async () => {
const path = writeOAuthFixture({
[SERVER]: {

View file

@ -47,7 +47,11 @@ import {
serializeOAuthPersistBlob,
type OAuthPersistSnapshot,
} from "@inspector/core/auth/oauth-persist.js";
import { getAuthorizationServerUrl } from "@inspector/core/auth/discovery.js";
import {
discoverAuthorizationServerMetadataFromCandidates,
getAuthorizationServerUrl,
getAuthorizationServerUrlCandidates,
} from "@inspector/core/auth/discovery.js";
import { writeStoreFile } from "@inspector/core/storage/store-io.js";
import {
refreshAuthorization,
@ -347,11 +351,27 @@ export async function refreshStoredAuthToken(
);
}
const authServerUrl = found.state.serverMetadata?.issuer
? new URL(found.state.serverMetadata.issuer)
: getAuthorizationServerUrl(serverUrl);
const metadata =
found.state.serverMetadata ?? (await discover(authServerUrl)) ?? undefined;
// With stored metadata the issuer settles it. Without, the MCP server URL
// stands in as the authorization server — and a path-hosted server has two
// plausible answers, so walk them rather than committing to the path-scoped
// one: a server that merely lives under a path while publishing its metadata
// at the domain root must keep working (#2110). The candidate that *answered*
// becomes `authServerUrl`, since it is also the base the token request below
// is made against.
let authServerUrl: URL;
let metadata = found.state.serverMetadata ?? undefined;
if (found.state.serverMetadata?.issuer) {
authServerUrl = new URL(found.state.serverMetadata.issuer);
} else {
const discovered = await discoverAuthorizationServerMetadataFromCandidates(
getAuthorizationServerUrlCandidates(serverUrl),
discover,
);
authServerUrl =
discovered?.authorizationServerUrl ??
getAuthorizationServerUrl(serverUrl);
metadata = discovered?.metadata;
}
let tokens: OAuthTokens;
try {

View file

@ -1,7 +1,9 @@
import { describe, it, expect, vi, beforeEach } from "vitest";
import {
discoverAuthorizationServerMetadataForServer,
discoverScopes,
getAuthorizationServerUrl,
getAuthorizationServerUrlCandidates,
} from "@inspector/core/auth/discovery.js";
import type { OAuthProtectedResourceMetadata } from "@modelcontextprotocol/client";
@ -335,3 +337,172 @@ describe("getAuthorizationServerUrl", () => {
expect(captured?.message).toMatch(/Invalid MCP server URL: "" \(.+\)/);
});
});
// #2110: an MCP server hosted under a path (Moodle, a WordPress plugin, any
// PHP endpoint) publishes its OAuth metadata under that same path. Reducing the
// fallback authorization-server URL to the origin threw that path away, so
// discovery could only ever probe the domain root and 404'd.
describe("path-hosted MCP servers (#2110)", () => {
const pathServerUrl = "https://misc.example.com/mod/minilesson/mcp.php";
describe("getAuthorizationServerUrl", () => {
it("keeps the server's path in the fallback URL", () => {
expect(getAuthorizationServerUrl(pathServerUrl)).toEqual(
new URL(pathServerUrl),
);
});
it("strips query and fragment, which an RFC 8414 issuer never carries", () => {
expect(
getAuthorizationServerUrl(`${pathServerUrl}?session=abc#frag`),
).toEqual(new URL(pathServerUrl));
});
});
describe("getAuthorizationServerUrlCandidates", () => {
it("tries the path-scoped URL before the bare origin", () => {
expect(getAuthorizationServerUrlCandidates(pathServerUrl)).toEqual([
new URL(pathServerUrl),
new URL("https://misc.example.com/"),
]);
});
it("offers a single candidate for a root-hosted server", () => {
expect(
getAuthorizationServerUrlCandidates("https://mcp.example.com"),
).toEqual([new URL("https://mcp.example.com/")]);
});
it("does not probe past an authorization server named by resource metadata", () => {
const resourceMetadata: OAuthProtectedResourceMetadata = {
resource: pathServerUrl,
authorization_servers: ["https://auth.example.com/realms/r"],
};
expect(
getAuthorizationServerUrlCandidates(pathServerUrl, resourceMetadata),
).toEqual([new URL("https://auth.example.com/realms/r")]);
});
});
describe("discoverAuthorizationServerMetadataForServer", () => {
const metadata = {
issuer: pathServerUrl,
authorization_endpoint: "https://misc.example.com/mod/authorize.php",
token_endpoint: "https://misc.example.com/mod/token.php",
response_types_supported: ["code"],
};
beforeEach(() => {
vi.clearAllMocks();
});
it("returns the path-scoped result without probing the origin", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue(
metadata,
);
await expect(
discoverAuthorizationServerMetadataForServer(pathServerUrl),
).resolves.toEqual(metadata);
expect(discoverAuthorizationServerMetadata).toHaveBeenCalledTimes(1);
expect(discoverAuthorizationServerMetadata).toHaveBeenCalledWith(
new URL(pathServerUrl),
{ fetchFn: undefined },
);
});
it("falls back to the origin when the path-scoped candidate has no metadata", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata)
.mockResolvedValueOnce(undefined)
.mockResolvedValueOnce(metadata);
await expect(
discoverAuthorizationServerMetadataForServer(pathServerUrl),
).resolves.toEqual(metadata);
expect(discoverAuthorizationServerMetadata).toHaveBeenNthCalledWith(
2,
new URL("https://misc.example.com/"),
{ fetchFn: undefined },
);
});
it("survives a throwing candidate while another remains", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata)
.mockRejectedValueOnce(new Error("issuer mismatch"))
.mockResolvedValueOnce(metadata);
await expect(
discoverAuthorizationServerMetadataForServer(pathServerUrl),
).resolves.toEqual(metadata);
});
it("rethrows the first error when every candidate fails", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata)
.mockRejectedValueOnce(new Error("path-scoped failed"))
.mockRejectedValueOnce(new Error("origin failed"));
await expect(
discoverAuthorizationServerMetadataForServer(pathServerUrl),
).rejects.toThrow("path-scoped failed");
});
it("resolves undefined when every candidate answers with no metadata", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue(
undefined,
);
await expect(
discoverAuthorizationServerMetadataForServer(pathServerUrl),
).resolves.toBeUndefined();
expect(discoverAuthorizationServerMetadata).toHaveBeenCalledTimes(2);
});
it("passes the caller's fetch through to every candidate", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue(
undefined,
);
const fetchFn = vi.fn<typeof fetch>();
await discoverAuthorizationServerMetadataForServer(
pathServerUrl,
undefined,
fetchFn,
);
expect(discoverAuthorizationServerMetadata).toHaveBeenCalledWith(
new URL(pathServerUrl),
{ fetchFn },
);
});
});
it("discoverScopes reaches a path-hosted authorization server", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue({
issuer: pathServerUrl,
authorization_endpoint: "https://misc.example.com/mod/authorize.php",
token_endpoint: "https://misc.example.com/mod/token.php",
response_types_supported: ["code"],
scopes_supported: ["read"],
});
await expect(discoverScopes(pathServerUrl)).resolves.toBe("read");
expect(discoverAuthorizationServerMetadata).toHaveBeenCalledWith(
new URL(pathServerUrl),
{ fetchFn: undefined },
);
});
});

View file

@ -1,9 +1,6 @@
import {
discoverAuthorizationServerMetadata,
discoverOAuthProtectedResourceMetadata,
} from "@modelcontextprotocol/client";
import { discoverOAuthProtectedResourceMetadata } from "@modelcontextprotocol/client";
import type { OAuthClientInformation } from "@modelcontextprotocol/client";
import { getAuthorizationServerUrl } from "./discovery.js";
import { discoverAuthorizationServerMetadataForServer } from "./discovery.js";
import type { BaseOAuthClientProvider } from "./providers.js";
/**
@ -49,14 +46,14 @@ export async function ensureCimdClientRegistration(params: {
resourceMetadata = undefined;
}
const authServerUrl = getAuthorizationServerUrl(
// Walks the path-scoped authorization-server URL before the bare origin, so a
// server hosted under a path is probed where it actually publishes its
// metadata rather than only at the domain root (#2110).
const metadata = await discoverAuthorizationServerMetadataForServer(
params.serverUrl,
resourceMetadata,
params.fetchFn,
);
const metadata = await discoverAuthorizationServerMetadata(authServerUrl, {
...(params.fetchFn && { fetchFn: params.fetchFn }),
});
if (!metadata?.client_id_metadata_document_supported) return;
const clientInformation: OAuthClientInformation = {

View file

@ -2,6 +2,38 @@ import { discoverAuthorizationServerMetadata } from "@modelcontextprotocol/clien
import type { OAuthProtectedResourceMetadata } from "@modelcontextprotocol/client";
import { parseHttpUrl } from "./utils.js";
type AuthorizationServerMetadata = Awaited<
ReturnType<typeof discoverAuthorizationServerMetadata>
>;
/**
* The MCP server's own URL, used as the authorization server when RFC 9728
* protected-resource metadata named none.
*
* The path is kept. Reducing it to the origin (`new URL("/", serverUrl)`)
* discards exactly the part that tells discovery where to look when the server
* is not hosted at the domain root: the SDK's `buildDiscoveryUrls` derives the
* path-scoped well-known locations — `/.well-known/oauth-authorization-server{path}`
* and `{path}/.well-known/openid-configuration` — from this URL's pathname, so
* an origin-only value can only ever probe the domain root (#2110).
*
* Query and fragment are stripped: an RFC 8414 issuer identifier carries
* neither, and the SDK compares the discovered `issuer` against this URL.
*/
function serverUrlAsAuthorizationServer(serverUrl: string): URL {
try {
const url = new URL(serverUrl);
url.search = "";
url.hash = "";
return url;
} catch (err) {
const detail = err instanceof Error ? err.message : String(err);
throw new Error(`Invalid MCP server URL: "${serverUrl}" (${detail})`, {
cause: err,
});
}
}
/**
* Returns the URL to use for OAuth authorization server metadata discovery.
* Uses resource metadata's authorization_servers[0] when present, otherwise the MCP server URL.
@ -15,14 +47,87 @@ export function getAuthorizationServerUrl(
if (first) {
return parseHttpUrl(first, "protected resource authorization_servers[0]");
}
try {
return new URL("/", serverUrl);
} catch (err) {
const detail = err instanceof Error ? err.message : String(err);
throw new Error(`Invalid MCP server URL: "${serverUrl}" (${detail})`, {
cause: err,
});
return serverUrlAsAuthorizationServer(serverUrl);
}
/**
* The authorization-server URLs to try, in order.
*
* When protected-resource metadata names an authorization server there is
* exactly one candidate — the server told us where to look, and probing past it
* would be guessing. Otherwise the MCP server URL itself stands in as the
* authorization server, and a path-hosted server has two plausible answers: the
* full URL, whose path-scoped well-known locations are what a server like
* `https://example.com/mod/minilesson/mcp.php` publishes, and the bare origin,
* used by a server that merely *lives* under a path while publishing its
* metadata at the domain root. Trying the path-scoped form first fixes #2110
* without regressing the root-hosted case, which is all the origin-only value
* ever served.
*/
export function getAuthorizationServerUrlCandidates(
serverUrl: string,
resourceMetadata?: OAuthProtectedResourceMetadata | null,
): URL[] {
const primary = getAuthorizationServerUrl(serverUrl, resourceMetadata);
const namedByMetadata = Boolean(resourceMetadata?.authorization_servers?.[0]);
if (namedByMetadata || primary.pathname === "/") return [primary];
return [primary, new URL("/", primary)];
}
export interface DiscoveredAuthorizationServer {
/** The candidate that answered — not necessarily the first one tried. */
authorizationServerUrl: URL;
metadata: NonNullable<AuthorizationServerMetadata>;
}
/**
* Walks `candidates` until one answers, and reports **which** one did.
*
* A candidate that fails — a 5xx, or an RFC 8414 §3.3 issuer mismatch, both of
* which the SDK raises rather than returning `undefined` — is not fatal while
* another candidate remains. If every candidate fails, the first error is
* rethrown, so a caller still sees the original diagnosis rather than a bare
* `undefined`.
*
* `discover` is injected rather than closed over so a caller that already owns
* a discovery function — the CLI's `refreshStoredAuthToken`, which takes one as
* a test seam — can walk the same candidates without giving that seam up.
*/
export async function discoverAuthorizationServerMetadataFromCandidates(
candidates: URL[],
discover: (url: URL) => Promise<AuthorizationServerMetadata>,
): Promise<DiscoveredAuthorizationServer | undefined> {
let firstError: unknown;
let sawError = false;
for (const candidate of candidates) {
try {
const metadata = await discover(candidate);
if (metadata) return { authorizationServerUrl: candidate, metadata };
} catch (err) {
if (!sawError) {
firstError = err;
sawError = true;
}
}
}
if (sawError) throw firstError;
return undefined;
}
/**
* Discovers authorization server metadata for an MCP server, walking the
* candidates above until one answers.
*/
export async function discoverAuthorizationServerMetadataForServer(
serverUrl: string,
resourceMetadata?: OAuthProtectedResourceMetadata | null,
fetchFn?: typeof fetch,
): Promise<AuthorizationServerMetadata> {
const found = await discoverAuthorizationServerMetadataFromCandidates(
getAuthorizationServerUrlCandidates(serverUrl, resourceMetadata),
(candidate) => discoverAuthorizationServerMetadata(candidate, { fetchFn }),
);
return found?.metadata;
}
/**
@ -38,13 +143,11 @@ export const discoverScopes = async (
fetchFn?: typeof fetch,
): Promise<string | undefined> => {
try {
const authServerUrl = getAuthorizationServerUrl(
const metadata = await discoverAuthorizationServerMetadataForServer(
serverUrl,
resourceMetadata,
);
const metadata = await discoverAuthorizationServerMetadata(authServerUrl, {
fetchFn,
});
);
// Prefer resource metadata scopes, but fall back to OAuth metadata if empty
const resourceScopes = resourceMetadata?.scopes_supported;