feat(test-servers): a CIMD showcase fixture that serves its own client metadata document

In CIMD (SEP-991) the `client_id` *is* a URL the authorization server
dereferences to learn the client's metadata. Nothing in this repo served such a
document, so a fixture could advertise `client_id_metadata_document_supported`
and still be unusable — exercising CIMD meant standing up a second host by hand.

That is why #2242 shipped verified by its tests alone, and why the v2.6.0
release smoke recorded it as the one contribution with an observable UI surface
that could not be reached.

The composable server now hosts the document itself when `oauth.clientMetadata`
is set, gated on `supportCIMD` — advertising a client the server would then
refuse to honour is a worse fixture than serving nothing. The document's
`client_id` is derived from the **request** rather than from a configured
issuer, so it stays correct when the harness picks the port, as the integration
test does.

`supportDCR: false` in the fixture is load-bearing rather than incidental. With
DCR available a CIMD failure silently succeeds via dynamic registration and the
reproduction proves nothing — during development a misconfigured run connected
happily and reported `Dynamic (DCR)` with a `test_client_…` id, which reads as
success until you check the client id. With DCR off, CIMD is the only path that
can complete, so reaching a connected state is itself the assertion; the test
pins the absent `registration_endpoint` so it stays that way.

Verified end to end against the fixture: Connection Info read
`Client registration — Client ID Metadata (CIMD)` with the client id equal to
the metadata URL. That drive needed a self-signed HTTPS listener, because the
Inspector requires the CIMD metadata URL to be HTTPS with no loopback
exemption — filed separately as #2305, since it is a validation gap rather than
a fixture one.

Closes #2306

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RsmR1iQstcrEzJFmgZXGLi
Signed-off-by: cliffhall <cliff@futurescale.com>

clients/web/src/test/integration/mcp/oauth-cimd-fixture.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, afterEach } from "vitest";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  createTestServerHttp,
+  type TestServerHttp,
+  createTestServerInfo,
+  loadConfig,
+  resolveConfig,
+} from "@modelcontextprotocol/inspector-test-server";
+
+/**
+ * Live coverage of `test-servers/configs/oauth-cimd-http.json` — the fixture
+ * that makes #2242 reproducible by hand.
+ *
+ * #2242 (CIMD provenance surviving the SDK's issuer-binding write) shipped
+ * verified by its own end-to-end tests, because nothing in this repo served a
+ * **client metadata document**: in CIMD the `client_id` is a URL the
+ * authorization server dereferences, so exercising it meant standing up a
+ * second host. The v2.6.0 release ledger recorded that as the one row with an
+ * observable UI surface and no way to reach it.
+ *
+ * What this file protects is the fixture itself, not the fix. The manual
+ * reproduction depends on three things being true of the served document, and
+ * each of them is the kind of thing that breaks silently:
+ *
+ *  - the AS advertises `client_id_metadata_document_supported`, or the
+ *    Inspector's CIMD pre-registration bails out before storing anything;
+ *  - it advertises **no** `registration_endpoint`, or a CIMD failure quietly
+ *    falls back to DCR and the repro passes while proving nothing (this is
+ *    exactly how the fixture first fooled its own author);
+ *  - the document's `client_id` equals the URL it was fetched from, which is
+ *    what makes it a legal CIMD client id rather than an arbitrary blob.
+ *
+ * The document is served over plain HTTP here. That is deliberate and is *not*
+ * a usable `clientMetadataUrl` for the Inspector, which requires HTTPS with no
+ * loopback exemption (#2305) — driving the UI needs a self-signed HTTPS
+ * listener, as `docs/test-servers.md` describes. This endpoint exists for the
+ * authorization-server side of the flow and for exactly these assertions.
+ */
+describe("CIMD showcase fixture (#2242)", () => {
+  let server: TestServerHttp | null = null;
+
+  const configPath = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "../../../../../../test-servers/configs/oauth-cimd-http.json",
+  );
+
+  afterEach(async () => {
+    if (server) {
+      try {
+        await server.stop();
+      } catch {
+        // ignore
+      }
+      server = null;
+    }
+  });
+
+  /**
+   * Boot the showcase config on a harness-chosen port, so this cannot collide
+   * with a showcase server someone is running by hand.
+   */
+  async function startShowcase(): Promise<TestServerHttp> {
+    const resolved = resolveConfig(loadConfig(configPath));
+    const started = createTestServerHttp({
+      ...resolved,
+      serverInfo: createTestServerInfo("oauth-cimd-test", "1.0.0"),
+      port: undefined,
+    });
+    await started.start();
+    server = started;
+    return started;
+  }
+
+  /** The MCP endpoint's origin, which is also the AS and the document host. */
+  function originOf(started: TestServerHttp): string {
+    return new URL(started.url).origin;
+  }
+
+  it("resolves the config with CIMD on and DCR deliberately off", () => {
+    const resolved = resolveConfig(loadConfig(configPath));
+    expect(resolved.oauth?.supportCIMD).toBe(true);
+    // Not an oversight: with DCR available a CIMD failure silently succeeds
+    // via dynamic registration, and the repro stops proving anything.
+    expect(resolved.oauth?.supportDCR).toBe(false);
+    expect(resolved.oauth?.clientMetadata?.redirectUris).toContain(
+      "http://127.0.0.1:6276/oauth/callback",
+    );
+  });
+
+  it("advertises CIMD support and no registration endpoint", async () => {
+    const started = await startShowcase();
+    const res = await fetch(
+      `${originOf(started)}/.well-known/oauth-authorization-server`,
+    );
+    expect(res.ok).toBe(true);
+    const metadata = await res.json();
+
+    expect(metadata.client_id_metadata_document_supported).toBe(true);
+    // The half that keeps the repro honest.
+    expect(metadata.registration_endpoint).toBeUndefined();
+  });
+
+  it("serves a client metadata document whose client_id is its own URL", async () => {
+    const started = await startShowcase();
+    const documentUrl = `${originOf(started)}/client-metadata.json`;
+
+    const res = await fetch(documentUrl);
+    expect(res.ok).toBe(true);
+    const doc = await res.json();
+
+    // A CIMD client id IS the document's URL. Deriving it from the request
+    // rather than from a configured issuer is what keeps this true when the
+    // harness picks the port, as it does here.
+    expect(doc.client_id).toBe(documentUrl);
+    expect(doc.redirect_uris).toContain("http://127.0.0.1:6276/oauth/callback");
+    // CIMD clients are public; the server's own CIMD branch issues no secret.
+    expect(doc.token_endpoint_auth_method).toBe("none");
+  });
+
+  it("does not serve the document when CIMD is switched off", async () => {
+    const resolved = resolveConfig(loadConfig(configPath));
+    const started = createTestServerHttp({
+      ...resolved,
+      oauth: { ...resolved.oauth!, supportCIMD: false },
+      serverInfo: createTestServerInfo("oauth-cimd-off-test", "1.0.0"),
+      port: undefined,
+    });
+    await started.start();
+    server = started;
+
+    const res = await fetch(`${originOf(started)}/client-metadata.json`);
+    // Advertising a client this server would then refuse to honour is a worse
+    // fixture than serving nothing at all.
+    expect(res.status).toBe(404);
+  });
+});

docs/test-servers.md

@@ -55,6 +55,7 @@ as a missing capability rather than an error.
 | `oauth-revocation-http.json` / `oauth-no-revocation-http.json` **(legacy era)** | RFC 7009 token revocation on clear, with and without a `revocation_endpoint` | [#2144](https://github.com/modelcontextprotocol/inspector/issues/2144) |
 | `oauth-rfc8414-at-oidc-path-http.json` **(legacy era)** | Plain OAuth 2.0 AS metadata served at the OIDC well-known path | [#2172](https://github.com/modelcontextprotocol/inspector/issues/2172) |
 | `oauth-insecure-token-endpoint-http.json` **(legacy era)** | A token endpoint the SDK refuses to post credentials to | [#2280](https://github.com/modelcontextprotocol/inspector/issues/2280) |
+| `oauth-cimd-http.json` **(legacy era)** | URL-based client IDs (CIMD / SEP-991), DCR deliberately off | [#2242](https://github.com/modelcontextprotocol/inspector/issues/2242) |
 | `logging-{legacy,modern}-http.json` **(era per file)** | Logging, both eras                                  | [#1629](https://github.com/modelcontextprotocol/inspector/issues/1629) |
 | `subscriptions-{legacy,modern}-http.json` **(era per file)** | Resource subscriptions, both eras                   | [#1630](https://github.com/modelcontextprotocol/inspector/issues/1630) |
 | `subscriptions-never-acknowledged-http.json` **(modern era)** | A `subscriptions/listen` answered with a bare result  | [#2097](https://github.com/modelcontextprotocol/inspector/issues/2097) |
@@ -534,6 +535,60 @@ On the broken build you got a **"Re-authentication required"** banner with a **R
 
 Note that the fix here is presentational only. Making a `*.localhost` token endpoint actually **work** has to land in the SDK — the assertion runs inside `executeTokenRequest`, takes no options, and there is no hook the Inspector could reach.
 
+## URL-based client IDs (CIMD / SEP-991)
+
+`oauth-cimd-http.json` is a combined AS + resource server that advertises
+`client_id_metadata_document_supported: true` and — the part that makes it usable — **hosts the client
+metadata document itself**, at `/client-metadata.json`. Plain streamable-HTTP; connect with the
+**default (legacy)** protocol era.
+
+Hosting the document is the whole reason this fixture exists. In CIMD the `client_id` *is* a URL that
+the authorization server dereferences to learn the client's metadata, so a server that merely
+advertises support is only half a fixture: exercising it still meant standing up a second host by
+hand. That is why [#2242](https://github.com/modelcontextprotocol/inspector/issues/2242) shipped
+verified by its tests alone, and the v2.6.0 release ledger recorded it as the one row that had an
+observable UI surface but no way to reach it.
+
+**`supportDCR` is `false` on purpose.** With both registration paths available a successful connection
+proves nothing about which one ran — precisely the confusion #2242 was about, where Connection Info
+reported `Dynamic (DCR)` for a connection that never issued a `POST /oauth/register`. With DCR off,
+CIMD is the only way the flow can complete, so reaching a connected state *is* the assertion.
+
+⚠️ **CIMD is configured install-wide, not per server.** It lives in `client.json`
+(`~/.mcp-inspector/storage/client.json`) as `cimd: { enabled: true, clientMetadataUrl }`, reachable
+from **Client settings**, not from a server's own OAuth settings. A `clientMetadataUrl` written into a
+catalog entry's `oauth` block is silently ignored — and with `supportDCR: true` the connection then
+succeeds *via DCR*, which looks like CIMD working until you read the client id.
+
+⚠️ **The Inspector requires that URL to be HTTPS, and there is no loopback exemption**
+(`getCimdClientMetadataUrlError` in `core/client/config-parse.ts`, applied to `client.json` on disk as
+well as to the settings form). So this server's own `http://` document is **not** usable as a
+`clientMetadataUrl`: it exists for the authorization-server side of the flow and for tests that drive
+the AS directly. To drive the Inspector end to end you need the document served over HTTPS —
+`https://127.0.0.1:8443/client-metadata.json` from a throwaway self-signed listener works, with
+`NODE_TLS_REJECT_UNAUTHORIZED=0` in the *test server's* environment so its own fetch of that document
+succeeds. That asymmetry is tracked in
+[#2305](https://github.com/modelcontextprotocol/inspector/issues/2305); it is the same over-narrow
+allow-list shape as the token-endpoint exemption above.
+
+With that in place: set the metadata URL in Client settings, connect, and open **Connection Info**.
+It should read `Client registration — Client ID Metadata (CIMD)` with the **client id equal to the
+metadata URL**, which is what CIMD means and what distinguishes it from a DCR-issued
+`test_client_…`. On the broken build it read `Dynamic (DCR)` for exactly this flow
+([#2242](https://github.com/modelcontextprotocol/inspector/issues/2242)).
+
+⚠️ **`clientMetadata.redirectUris` must list the callback for the port you are running.** The
+Inspector's browser redirect is `<web origin>/oauth/callback` and the CLI/TUI's is
+`http://127.0.0.1:6276/oauth/callback`; the authorization server checks the incoming `redirect_uri`
+against this list. The shipped fixture lists **6274** (the default), **6330** and **6276**; on any
+other port the flow fails with `Invalid redirect_uri`, which reads like a CIMD problem and is not one.
+Add your port to the config rather than debugging the registration path.
+
+⚠️ **The same fixed-`issuerUrl` hazard as the fixture above applies**, for the same reason: the
+`client_id` this server publishes is derived from its issuer URL, so a server that walked to another
+port on `EADDRINUSE` publishes a `client_id` pointing at whatever process holds 8092. Check with
+`lsof -nP -iTCP:8092 -sTCP:LISTEN` before believing a failure.
+
 ## Revoking tokens on clear (RFC 7009)
 
 `oauth-revocation-http.json` and `oauth-no-revocation-http.json` are the same OAuth-protected server (combined AS + resource, DCR, refresh tokens) differing in one thing: the first advertises a `revocation_endpoint`, the second advertises none. Plain streamable-HTTP — connect with the **default (legacy)** protocol era.

test-servers/configs/oauth-cimd-http.json

@@ -0,0 +1,37 @@
+{
+  "serverInfo": {
+    "name": "oauth-cimd-showcase",
+    "version": "1.0.0"
+  },
+  "tools": [
+    {
+      "preset": "echo"
+    }
+  ],
+  "oauth": {
+    "enabled": true,
+    "mode": "combined",
+    "requireAuth": true,
+    "scopesSupported": [
+      "mcp"
+    ],
+    "supportCIMD": true,
+    "supportDCR": false,
+    "supportRefreshTokens": true,
+    "clientMetadata": {
+      "clientName": "MCP Inspector (CIMD test fixture)",
+      "scope": "mcp",
+      "redirectUris": [
+        "http://127.0.0.1:6274/oauth/callback",
+        "http://localhost:6274/oauth/callback",
+        "http://127.0.0.1:6330/oauth/callback",
+        "http://localhost:6330/oauth/callback",
+        "http://127.0.0.1:6276/oauth/callback"
+      ]
+    }
+  },
+  "transport": {
+    "type": "streamable-http",
+    "port": 8092
+  }
+}

test-servers/src/composable-test-server.ts

@@ -734,6 +734,34 @@ export interface ServerConfig {
      */
     supportCIMD?: boolean;
 
+    /**
+     * Serve a CIMD client metadata document from this server, so a CIMD
+     * fixture is self-contained.
+     *
+     * CIMD makes the `client_id` a URL that the authorization server fetches
+     * to learn the client's metadata (SEP-991). Nothing in this repo served
+     * such a document, so exercising CIMD meant standing up a second host by
+     * hand — which is why #2242 shipped verified only by its tests. With this
+     * set, the server hosts the document at `clientMetadataPath` (default
+     * `/client-metadata.json`) and that URL is a usable `client_id`.
+     *
+     * `redirectUris` MUST list the Inspector's callback for the port you run
+     * it on (`<web origin>/oauth/callback`) — the authorization server checks
+     * the incoming `redirect_uri` against this list, and a mismatch fails the
+     * flow with `Invalid redirect_uri` rather than anything CIMD-specific.
+     *
+     * Only served when `supportCIMD` is true: a document advertising a client
+     * the server would then refuse is a worse fixture than none.
+     */
+    clientMetadata?: {
+      redirectUris: string[];
+      clientName?: string;
+      scope?: string;
+    };
+
+    /** Where to serve `clientMetadata` (default `/client-metadata.json`). */
+    clientMetadataPath?: string;
+
     /**
      * Token expiration time in seconds (default: 3600)
      */

test-servers/src/load-config.ts

@@ -37,6 +37,18 @@ export interface ConfigFileOAuth {
   }>;
   supportDCR?: boolean;
   supportCIMD?: boolean;
+  /**
+   * Serve a CIMD client metadata document, making a CIMD fixture
+   * self-contained. `redirectUris` must list the Inspector callback for the
+   * web port under test. See the field's doc comment in
+   * `composable-test-server.ts`.
+   */
+  clientMetadata?: {
+    redirectUris: string[];
+    clientName?: string;
+    scope?: string;
+  };
+  clientMetadataPath?: string;
   tokenExpirationSeconds?: number;
   supportRefreshTokens?: boolean;
   /** RFC 7009 revocation endpoint; default true (#2144). */

test-servers/src/test-server-oauth.ts

@@ -283,6 +283,38 @@ function setupMetadataEndpoints(
     });
   }
 
+  // CIMD client metadata document (SEP-991). The `client_id` in a CIMD flow is
+  // a URL the authorization server dereferences, so a fixture that advertises
+  // `client_id_metadata_document_supported` without hosting a document
+  // anywhere is only half a fixture — it needs a second host to be usable at
+  // all. Serving it here makes a CIMD run self-contained.
+  //
+  // Gated on `supportCIMD` as well as on the document's presence: advertising
+  // a client this server would then refuse to honour is worse than serving
+  // nothing.
+  if (config.supportCIMD && config.clientMetadata) {
+    const doc = config.clientMetadata;
+    const metadataPath = config.clientMetadataPath ?? "/client-metadata.json";
+    app.get(metadataPath, (req: Request, res: Response) => {
+      // Derived from the request rather than from `issuerUrl`, so the
+      // document's own `client_id` always equals the URL it was fetched from
+      // — which is what CIMD requires, and what stays true if the server
+      // walked to another port on EADDRINUSE.
+      const requestBaseUrl = `${req.protocol}://${req.get("host")}`;
+      res.json({
+        client_id: new URL(metadataPath, requestBaseUrl).href,
+        client_name: doc.clientName ?? "MCP Inspector (CIMD test fixture)",
+        redirect_uris: doc.redirectUris,
+        // CIMD clients are public and authenticate with nothing; the server's
+        // own CIMD branch assumes exactly this (no client_secret is issued).
+        token_endpoint_auth_method: "none",
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        ...(doc.scope ? { scope: doc.scope } : {}),
+      });
+    });
+  }
+
   // OAuth Protected Resource Metadata. `resourceMetadataPath` moves the
   // document off the well-known path entirely (rather than serving both), so
   // a client that ignores the advertised `resource_metadata` URL gets a 404