From 962c17c67813940fd09bb7ed28b85df9bbba4cb6 Mon Sep 17 00:00:00 2001 From: amirejaz Date: Sat, 6 Jun 2026 01:04:33 +0500 Subject: [PATCH 1/3] Fix CIMD documentation gaps (issue #919) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - auth-framework.mdx: remove incorrect "Support for CIMD is planned" claim; CIMD shipped in v0.29.0. Describe DCR and CIMD as both supported mechanisms. - embedded-auth-server.mdx: update "How the OAuth flow works" and "Key characteristics" to present CIMD alongside DCR. Expand the existing CIMD section with the two-layer architecture (mermaid diagram), document validation rules, SSRF protections, and a verification command. - backend-auth.mdx, vmcp.mdx, guides-vmcp/authentication.mdx: add CIMD alongside DCR where the embedded AS client registration mechanisms are described. - guides-ui/run-mcp-servers.mdx: align "Auto-Discovered" description with the CLI guide — describe the CIMD-first, DCR-fallback priority order that ToolHive actually implements (applied to both occurrences). - guides-k8s/auth-k8s.mdx: add CIMD troubleshooting inside the Kubernetes-specific details block (not using CIMD, invalid_client causes, egress/timeout failures). Fixes #919. --- docs/toolhive/concepts/auth-framework.mdx | 12 ++- docs/toolhive/concepts/backend-auth.mdx | 7 +- .../concepts/embedded-auth-server.mdx | 76 ++++++++++++++++++- docs/toolhive/concepts/vmcp.mdx | 6 +- docs/toolhive/guides-k8s/auth-k8s.mdx | 31 ++++++++ docs/toolhive/guides-ui/run-mcp-servers.mdx | 34 +++++---- docs/toolhive/guides-vmcp/authentication.mdx | 7 +- 7 files changed, 143 insertions(+), 30 deletions(-) diff --git a/docs/toolhive/concepts/auth-framework.mdx b/docs/toolhive/concepts/auth-framework.mdx index e93d3559..b48a9120 100644 --- a/docs/toolhive/concepts/auth-framework.mdx +++ b/docs/toolhive/concepts/auth-framework.mdx @@ -83,10 +83,14 @@ clients a spec-compliant OAuth experience while centralizing the complexity of token acquisition and management. To eliminate the client registration burden, the embedded authorization server -currently implements Dynamic Client Registration (DCR), which the MCP -specification lists as the backward compatibility fallback. Support for Client -ID Metadata Documents, the spec's preferred mechanism for clients and servers -without an existing relationship, is planned. +supports two client registration mechanisms. **Dynamic Client Registration (DCR, +RFC 7591)** is the backward-compatibility fallback — MCP clients call +`/oauth/register` to receive a `client_id` automatically. **Client ID Metadata +Documents (CIMD)**, the MCP specification's preferred mechanism for clients and +servers without a prior relationship, are also supported: a client presents a +public HTTPS URL as its `client_id`, and the embedded AS fetches and validates +the metadata document at that URL. Clients such as VS Code support CIMD and will +use it automatically when the embedded AS advertises support. ## Authentication framework diff --git a/docs/toolhive/concepts/backend-auth.mdx b/docs/toolhive/concepts/backend-auth.mdx index 3c3c8f89..6e71468b 100644 --- a/docs/toolhive/concepts/backend-auth.mdx +++ b/docs/toolhive/concepts/backend-auth.mdx @@ -162,9 +162,10 @@ the external service, obtains tokens on behalf of the user, and automatically forwards the upstream token to the MCP server on each subsequent request. The embedded authorization server runs in-process within the ToolHive proxy with -no separate infrastructure needed. It supports Dynamic Client Registration -(DCR), so MCP clients can register automatically with ToolHive. No manual client -configuration in ToolHive is required. +no separate infrastructure needed. It supports Dynamic Client Registration (DCR) +and Client ID Metadata Documents (CIMD), so MCP clients can register or identify +themselves automatically with ToolHive. No manual client configuration in +ToolHive is required. For a full explanation of how the OAuth flow works, token storage and forwarding, automatic token refresh, session storage options, and differences diff --git a/docs/toolhive/concepts/embedded-auth-server.mdx b/docs/toolhive/concepts/embedded-auth-server.mdx index 6b4d17df..4ee8841f 100644 --- a/docs/toolhive/concepts/embedded-auth-server.mdx +++ b/docs/toolhive/concepts/embedded-auth-server.mdx @@ -43,9 +43,14 @@ identity provider and those services. From the client's perspective, the embedded authorization server provides a standard OAuth 2.0 experience: -1. If the client is not yet registered, it registers via Dynamic Client - Registration (DCR, RFC 7591), receiving a `client_id` and `client_secret`. No - manual client registration in ToolHive is required. +1. The client identifies itself using one of two mechanisms, with no manual + registration in ToolHive required: + - **Client ID Metadata Document (CIMD):** If CIMD is enabled on the embedded + AS and the client supports it (for example, VS Code), the client presents + its public HTTPS metadata URL as its `client_id`. The embedded AS fetches + and validates the document. + - **Dynamic Client Registration (DCR, RFC 7591):** The client calls + `/oauth/register` to receive a `client_id` dynamically. 2. The client is directed to the ToolHive authorization endpoint. 3. ToolHive redirects the client to the upstream identity provider for authentication (for example, signing in with GitHub or Atlassian). @@ -135,6 +140,10 @@ the OAuth flow. - **Dynamic Client Registration (DCR):** Supports OAuth 2.0 DCR (RFC 7591), allowing MCP clients to register automatically. No manual client registration in ToolHive is required. +- **Client ID Metadata Documents (CIMD):** When enabled, accepts HTTPS URLs as + `client_id` values and resolves client metadata on demand. Clients that + support CIMD (such as VS Code) use it automatically; other clients fall back + to DCR. - **Direct upstream redirect:** Redirects clients directly to the upstream provider for authentication (for example, GitHub or Atlassian). - **Configurable signing keys:** JWTs are signed with keys you provide, @@ -196,6 +205,67 @@ If you also set `baselineClientScopes`, those scopes apply to CIMD-resolved clients too. Because CIMD clients can be resolved from arbitrary HTTPS URLs, keep the baseline narrow. +### Two-layer architecture + +The client's CIMD identity is used only within the embedded AS. The embedded AS +uses its own pre-configured upstream credentials when redirecting to the +upstream identity provider. + +```mermaid +sequenceDiagram + participant Client as VS Code
(CIMD client_id) + participant EmbeddedAS as Embedded AS + participant IDP as Upstream IDP + + Note over Client,EmbeddedAS: Leg 1 — CIMD + Client->>EmbeddedAS: client_id = https://vscode.dev/oauth/client-metadata.json + EmbeddedAS->>EmbeddedAS: Fetch and validate CIMD document + EmbeddedAS-->>Client: Redirect to upstream IDP + + Note over EmbeddedAS,IDP: Leg 2 — AS's own credentials + Client->>IDP: Authenticate + IDP-->>EmbeddedAS: Authorization code + EmbeddedAS->>IDP: Exchange (AS's own client_id + secret) + EmbeddedAS-->>Client: Issue ToolHive JWT +``` + +The upstream IDP never sees the client's CIMD URL. This means you must still +configure an upstream client ID and secret for the embedded AS regardless of +whether clients use CIMD or DCR. + +### Document validation + +The embedded AS enforces the following rules on fetched CIMD documents: + +- The URL must use `https` (loopback `http://localhost` is accepted in + development environments only). +- The `client_id` field inside the document must exactly match the URL it was + fetched from. +- `redirect_uris` must be present and pass strict validation. +- Symmetric shared-secret `token_endpoint_auth_method` values are forbidden. +- `grant_types` must include `authorization_code` and be a subset of + `[authorization_code, refresh_token]`. +- `response_types` must be a subset of `[code]`. +- Declared scopes must be a subset of the AS's configured `scopes_supported` + list (when set). + +The fetcher also applies SSRF protection: DNS resolution runs before dialing, +private IP ranges are blocked, redirects are not followed, and each fetch is +subject to a five-second timeout and a 10 KB response cap. + +### Verify CIMD is enabled + +After applying the configuration, confirm that the discovery document advertises +CIMD support: + +```bash +kubectl port-forward -n toolhive-system svc/mcp--proxy 8080:8080 & +curl -s http://localhost:8080/.well-known/oauth-authorization-server | \ + python3 -m json.tool | grep client_id_metadata_document +``` + +You should see `"client_id_metadata_document_supported": true`. + ## Session storage By default, session storage is in-memory. Upstream tokens are lost when pods diff --git a/docs/toolhive/concepts/vmcp.mdx b/docs/toolhive/concepts/vmcp.mdx index 992c805c..61eb6789 100644 --- a/docs/toolhive/concepts/vmcp.mdx +++ b/docs/toolhive/concepts/vmcp.mdx @@ -142,9 +142,9 @@ vMCP can also run an embedded authorization server that handles the full OAuth flow with multiple upstream identity providers (such as GitHub, Google, or Okta). This enables per-user backend authentication: when a user logs in, the auth server acquires tokens from each upstream provider and injects them into -requests to the appropriate backends. MCP clients register automatically through -Dynamic Client Registration (DCR), so no manual client configuration is needed. -See +requests to the appropriate backends. MCP clients register or identify +themselves automatically through Dynamic Client Registration (DCR) or Client ID +Metadata Documents (CIMD), so no manual client configuration is needed. See [Authentication](../guides-vmcp/authentication.mdx#embedded-authorization-server) for setup details. diff --git a/docs/toolhive/guides-k8s/auth-k8s.mdx b/docs/toolhive/guides-k8s/auth-k8s.mdx index 2a05570f..24cdb0eb 100644 --- a/docs/toolhive/guides-k8s/auth-k8s.mdx +++ b/docs/toolhive/guides-k8s/auth-k8s.mdx @@ -1185,6 +1185,37 @@ kubectl describe mcpserver -n toolhive-system `kubectl logs -n toolhive-system -l app.kubernetes.io/name=toolhive-operator` - Verify the operator is running: `kubectl get pods -n toolhive-system` +**CIMD client not using CIMD (falling back to DCR):** + +- Verify `cimd.enabled: true` is set in the `MCPExternalAuthConfig` and the + operator has reconciled the change: + `kubectl describe mcpexternalauthconfig -n toolhive-system` +- Confirm the discovery document advertises CIMD support: + ```bash + kubectl port-forward -n toolhive-system svc/mcp--proxy 8080:8080 & + curl -s http://localhost:8080/.well-known/oauth-authorization-server | python3 -m json.tool | grep client_id_metadata_document + ``` + You should see `"client_id_metadata_document_supported": true`. +- Restart the proxy runner pod after updating an existing resource. + +**CIMD authentication failing with `invalid_client`:** + +- The `client_id` field inside the fetched document must exactly match the URL + used to fetch it. +- Documents must not declare `token_endpoint_auth_method` values that use a + symmetric shared secret (`client_secret_post`, `client_secret_basic`, + `client_secret_jwt`). +- `grant_types` must include `authorization_code`. `response_types` must only + contain `code`. +- `redirect_uris` must be present and valid. + +**CIMD fetch failing (egress / timeout):** + +- The proxy runner pod needs outbound HTTPS access to the client's metadata URL + (for example, `https://vscode.dev`). Check cluster egress policies. +- Fetches time out after five seconds. Ensure the metadata host is reachable + from within the cluster. +
diff --git a/docs/toolhive/guides-ui/run-mcp-servers.mdx b/docs/toolhive/guides-ui/run-mcp-servers.mdx index 73e3f740..b969bf99 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/run-mcp-servers.mdx @@ -151,13 +151,16 @@ remaining required information and adjust any optional settings as needed: 1. **Authorization method**: Choose how ToolHive should authenticate with the remote server.\ The default is **Auto-Discovered**. Use this option for MCP servers that - fully implement the MCP authorization spec including dynamic client - registration (RFC7591) or for servers that do not require authentication. - ToolHive automatically: - - Discovers OAuth/OIDC endpoints - - Registers a new OAuth client - - Obtains and manages client credentials - - Handles token lifecycle automatically + implement the MCP authorization spec or for servers that do not require + authentication. ToolHive automatically discovers OAuth/OIDC endpoints and + identifies itself using whichever mechanism the server supports: + - **Client ID Metadata Document (CIMD):** If the server's discovery document + sets `client_id_metadata_document_supported: true`, ToolHive presents its + metadata URL as the `client_id`. No registration round-trip is needed. + - **Dynamic Client Registration (DCR, RFC 7591):** When CIMD is unavailable + or rejected, ToolHive registers an OAuth client dynamically. + + Either path handles token acquisition and lifecycle automatically. For MCP servers that accept a bearer token in the `Authorization` header, select **Bearer Token**. ToolHive stores the token securely and sends it as @@ -459,13 +462,16 @@ On the configuration form, enter: 6. **Authorization method**: Choose how ToolHive should authenticate with the remote server.\ The default is **Auto-Discovered**. Use this option for MCP servers that - fully implement the MCP authorization spec including dynamic client - registration (RFC7591) or for servers that do not require authentication. - ToolHive automatically: - - Discovers OAuth/OIDC endpoints - - Registers a new OAuth client - - Obtains and manages client credentials - - Handles token lifecycle automatically + implement the MCP authorization spec or for servers that do not require + authentication. ToolHive automatically discovers OAuth/OIDC endpoints and + identifies itself using whichever mechanism the server supports: + - **Client ID Metadata Document (CIMD):** If the server's discovery document + sets `client_id_metadata_document_supported: true`, ToolHive presents its + metadata URL as the `client_id`. No registration round-trip is needed. + - **Dynamic Client Registration (DCR, RFC 7591):** When CIMD is unavailable + or rejected, ToolHive registers an OAuth client dynamically. + + Either path handles token acquisition and lifecycle automatically. For MCP servers that accept a bearer token in the `Authorization` header, select **Bearer Token**. ToolHive stores the token securely and sends it as diff --git a/docs/toolhive/guides-vmcp/authentication.mdx b/docs/toolhive/guides-vmcp/authentication.mdx index ecea981e..d277f141 100644 --- a/docs/toolhive/guides-vmcp/authentication.mdx +++ b/docs/toolhive/guides-vmcp/authentication.mdx @@ -397,10 +397,11 @@ stored upstream tokens for backends. Use the embedded authorization server when your backend MCP servers call external APIs on behalf of individual users and no federation relationship -exists between your identity provider and those services. It also provides OAuth +exists between your identity provider and those services. It also supports OAuth 2.0 Dynamic Client Registration -([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)), so MCP clients can -register automatically without manual client configuration in ToolHive. +([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) and Client ID +Metadata Documents (CIMD), so MCP clients can register or identify themselves +automatically without manual client configuration in ToolHive. :::info From 388f494121fd118170659fdb59c77eb1582841d0 Mon Sep 17 00:00:00 2001 From: amirejaz Date: Sat, 6 Jun 2026 01:35:16 +0500 Subject: [PATCH 2/3] Address Copilot review comments and reorder CIMD before DCR MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Copilot fixes: - Replace em dashes with periods or colons throughout (style guide forbids em dashes) - Mermaid note labels use colons instead of em dashes - "Documents" → "Document" (singular) in Key characteristics bullet - Replace port-forward snippets with direct curl against the issuer URL, consistent with existing auth-k8s.mdx pattern - Include the actual ToolHive CIMD URL (toolhive.dev/oauth/client-metadata.json) in the UI guide instead of "metadata URL" Ordering: - List CIMD before DCR throughout, matching the MCP spec priority order and the existing CLI guide. CIMD is the preferred mechanism; DCR is the fallback. --- docs/toolhive/concepts/auth-framework.mdx | 14 ++++++------ docs/toolhive/concepts/backend-auth.mdx | 8 +++---- .../concepts/embedded-auth-server.mdx | 22 +++++++++---------- docs/toolhive/concepts/vmcp.mdx | 4 ++-- docs/toolhive/guides-k8s/auth-k8s.mdx | 8 ++++--- docs/toolhive/guides-ui/run-mcp-servers.mdx | 10 +++++---- docs/toolhive/guides-vmcp/authentication.mdx | 6 +++-- 7 files changed, 39 insertions(+), 33 deletions(-) diff --git a/docs/toolhive/concepts/auth-framework.mdx b/docs/toolhive/concepts/auth-framework.mdx index b48a9120..740cdb07 100644 --- a/docs/toolhive/concepts/auth-framework.mdx +++ b/docs/toolhive/concepts/auth-framework.mdx @@ -83,14 +83,14 @@ clients a spec-compliant OAuth experience while centralizing the complexity of token acquisition and management. To eliminate the client registration burden, the embedded authorization server -supports two client registration mechanisms. **Dynamic Client Registration (DCR, -RFC 7591)** is the backward-compatibility fallback — MCP clients call -`/oauth/register` to receive a `client_id` automatically. **Client ID Metadata -Documents (CIMD)**, the MCP specification's preferred mechanism for clients and -servers without a prior relationship, are also supported: a client presents a +supports two client registration mechanisms. **Client ID Metadata Document +(CIMD)** is the MCP specification's preferred mechanism: a client presents a public HTTPS URL as its `client_id`, and the embedded AS fetches and validates -the metadata document at that URL. Clients such as VS Code support CIMD and will -use it automatically when the embedded AS advertises support. +the metadata document at that URL. Clients such as VS Code support CIMD and use +it automatically when the embedded AS advertises support. **Dynamic Client +Registration (DCR, RFC 7591)** is the backward-compatibility fallback. MCP +clients that do not support CIMD call `/oauth/register` to receive a `client_id` +automatically. ## Authentication framework diff --git a/docs/toolhive/concepts/backend-auth.mdx b/docs/toolhive/concepts/backend-auth.mdx index 6e71468b..84206a6a 100644 --- a/docs/toolhive/concepts/backend-auth.mdx +++ b/docs/toolhive/concepts/backend-auth.mdx @@ -162,10 +162,10 @@ the external service, obtains tokens on behalf of the user, and automatically forwards the upstream token to the MCP server on each subsequent request. The embedded authorization server runs in-process within the ToolHive proxy with -no separate infrastructure needed. It supports Dynamic Client Registration (DCR) -and Client ID Metadata Documents (CIMD), so MCP clients can register or identify -themselves automatically with ToolHive. No manual client configuration in -ToolHive is required. +no separate infrastructure needed. It supports Client ID Metadata Documents +(CIMD) and Dynamic Client Registration (DCR), so MCP clients can identify +themselves or register automatically with ToolHive. No manual client +configuration in ToolHive is required. For a full explanation of how the OAuth flow works, token storage and forwarding, automatic token refresh, session storage options, and differences diff --git a/docs/toolhive/concepts/embedded-auth-server.mdx b/docs/toolhive/concepts/embedded-auth-server.mdx index 4ee8841f..1f62bcba 100644 --- a/docs/toolhive/concepts/embedded-auth-server.mdx +++ b/docs/toolhive/concepts/embedded-auth-server.mdx @@ -137,13 +137,12 @@ the OAuth flow. - **In-process execution:** The authorization server runs within the ToolHive proxy with no separate infrastructure or sidecar containers. -- **Dynamic Client Registration (DCR):** Supports OAuth 2.0 DCR (RFC 7591), - allowing MCP clients to register automatically. No manual client registration - in ToolHive is required. -- **Client ID Metadata Documents (CIMD):** When enabled, accepts HTTPS URLs as +- **Client ID Metadata Document (CIMD):** When enabled, accepts HTTPS URLs as `client_id` values and resolves client metadata on demand. Clients that - support CIMD (such as VS Code) use it automatically; other clients fall back - to DCR. + support CIMD (such as VS Code) use it automatically. +- **Dynamic Client Registration (DCR):** Supports OAuth 2.0 DCR (RFC 7591) as a + fallback for clients that do not support CIMD. MCP clients register + automatically with no manual configuration in ToolHive. - **Direct upstream redirect:** Redirects clients directly to the upstream provider for authentication (for example, GitHub or Atlassian). - **Configurable signing keys:** JWTs are signed with keys you provide, @@ -217,12 +216,12 @@ sequenceDiagram participant EmbeddedAS as Embedded AS participant IDP as Upstream IDP - Note over Client,EmbeddedAS: Leg 1 — CIMD + Note over Client,EmbeddedAS: Leg 1: CIMD Client->>EmbeddedAS: client_id = https://vscode.dev/oauth/client-metadata.json EmbeddedAS->>EmbeddedAS: Fetch and validate CIMD document EmbeddedAS-->>Client: Redirect to upstream IDP - Note over EmbeddedAS,IDP: Leg 2 — AS's own credentials + Note over EmbeddedAS,IDP: Leg 2: AS own credentials Client->>IDP: Authenticate IDP-->>EmbeddedAS: Authorization code EmbeddedAS->>IDP: Exchange (AS's own client_id + secret) @@ -259,12 +258,13 @@ After applying the configuration, confirm that the discovery document advertises CIMD support: ```bash -kubectl port-forward -n toolhive-system svc/mcp--proxy 8080:8080 & -curl -s http://localhost:8080/.well-known/oauth-authorization-server | \ +curl -s https:///.well-known/oauth-authorization-server | \ python3 -m json.tool | grep client_id_metadata_document ``` -You should see `"client_id_metadata_document_supported": true`. +Replace `` with the `issuer` value from your +`MCPExternalAuthConfig`. You should see +`"client_id_metadata_document_supported": true`. ## Session storage diff --git a/docs/toolhive/concepts/vmcp.mdx b/docs/toolhive/concepts/vmcp.mdx index 61eb6789..3ca0361c 100644 --- a/docs/toolhive/concepts/vmcp.mdx +++ b/docs/toolhive/concepts/vmcp.mdx @@ -143,8 +143,8 @@ flow with multiple upstream identity providers (such as GitHub, Google, or Okta). This enables per-user backend authentication: when a user logs in, the auth server acquires tokens from each upstream provider and injects them into requests to the appropriate backends. MCP clients register or identify -themselves automatically through Dynamic Client Registration (DCR) or Client ID -Metadata Documents (CIMD), so no manual client configuration is needed. See +themselves automatically through Client ID Metadata Documents (CIMD) or Dynamic +Client Registration (DCR), so no manual client configuration is needed. See [Authentication](../guides-vmcp/authentication.mdx#embedded-authorization-server) for setup details. diff --git a/docs/toolhive/guides-k8s/auth-k8s.mdx b/docs/toolhive/guides-k8s/auth-k8s.mdx index 24cdb0eb..d87af2c6 100644 --- a/docs/toolhive/guides-k8s/auth-k8s.mdx +++ b/docs/toolhive/guides-k8s/auth-k8s.mdx @@ -1192,10 +1192,12 @@ kubectl describe mcpserver -n toolhive-system `kubectl describe mcpexternalauthconfig -n toolhive-system` - Confirm the discovery document advertises CIMD support: ```bash - kubectl port-forward -n toolhive-system svc/mcp--proxy 8080:8080 & - curl -s http://localhost:8080/.well-known/oauth-authorization-server | python3 -m json.tool | grep client_id_metadata_document + curl -s https:///.well-known/oauth-authorization-server | \ + python3 -m json.tool | grep client_id_metadata_document ``` - You should see `"client_id_metadata_document_supported": true`. + Replace `` with the `issuer` value from your + `MCPExternalAuthConfig`. You should see + `"client_id_metadata_document_supported": true`. - Restart the proxy runner pod after updating an existing resource. **CIMD authentication failing with `invalid_client`:** diff --git a/docs/toolhive/guides-ui/run-mcp-servers.mdx b/docs/toolhive/guides-ui/run-mcp-servers.mdx index b969bf99..c224384d 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/run-mcp-servers.mdx @@ -155,8 +155,9 @@ remaining required information and adjust any optional settings as needed: authentication. ToolHive automatically discovers OAuth/OIDC endpoints and identifies itself using whichever mechanism the server supports: - **Client ID Metadata Document (CIMD):** If the server's discovery document - sets `client_id_metadata_document_supported: true`, ToolHive presents its - metadata URL as the `client_id`. No registration round-trip is needed. + sets `client_id_metadata_document_supported: true`, ToolHive presents + [`https://toolhive.dev/oauth/client-metadata.json`](https://toolhive.dev/oauth/client-metadata.json) + as the `client_id`. No registration round-trip is needed. - **Dynamic Client Registration (DCR, RFC 7591):** When CIMD is unavailable or rejected, ToolHive registers an OAuth client dynamically. @@ -466,8 +467,9 @@ On the configuration form, enter: authentication. ToolHive automatically discovers OAuth/OIDC endpoints and identifies itself using whichever mechanism the server supports: - **Client ID Metadata Document (CIMD):** If the server's discovery document - sets `client_id_metadata_document_supported: true`, ToolHive presents its - metadata URL as the `client_id`. No registration round-trip is needed. + sets `client_id_metadata_document_supported: true`, ToolHive presents + [`https://toolhive.dev/oauth/client-metadata.json`](https://toolhive.dev/oauth/client-metadata.json) + as the `client_id`. No registration round-trip is needed. - **Dynamic Client Registration (DCR, RFC 7591):** When CIMD is unavailable or rejected, ToolHive registers an OAuth client dynamically. diff --git a/docs/toolhive/guides-vmcp/authentication.mdx b/docs/toolhive/guides-vmcp/authentication.mdx index d277f141..7ce9c0d0 100644 --- a/docs/toolhive/guides-vmcp/authentication.mdx +++ b/docs/toolhive/guides-vmcp/authentication.mdx @@ -400,8 +400,10 @@ external APIs on behalf of individual users and no federation relationship exists between your identity provider and those services. It also supports OAuth 2.0 Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) and Client ID -Metadata Documents (CIMD), so MCP clients can register or identify themselves -automatically without manual client configuration in ToolHive. +Metadata Documents (CIMD) and Dynamic Client Registration +([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)), so MCP clients can +identify themselves or register automatically without manual client +configuration in ToolHive. :::info From 22386a5f5c8f17fdfa48061cd4adf61a8adbfa5e Mon Sep 17 00:00:00 2001 From: amirejaz Date: Mon, 8 Jun 2026 14:51:06 +0500 Subject: [PATCH 3/3] Address Dan's review feedback on PR 920 - Drop 'Verify CIMD is enabled' subsection from embedded-auth-server.mdx: procedural content belongs in guides, not concept pages, and the steps already exist in auth-k8s.mdx. - Fix garbled paragraph in guides-vmcp/authentication.mdx where the DCR link was listed twice due to a bad edit. --- docs/toolhive/concepts/embedded-auth-server.mdx | 14 -------------- docs/toolhive/guides-vmcp/authentication.mdx | 4 +--- 2 files changed, 1 insertion(+), 17 deletions(-) diff --git a/docs/toolhive/concepts/embedded-auth-server.mdx b/docs/toolhive/concepts/embedded-auth-server.mdx index 1f62bcba..de8a11f3 100644 --- a/docs/toolhive/concepts/embedded-auth-server.mdx +++ b/docs/toolhive/concepts/embedded-auth-server.mdx @@ -252,20 +252,6 @@ The fetcher also applies SSRF protection: DNS resolution runs before dialing, private IP ranges are blocked, redirects are not followed, and each fetch is subject to a five-second timeout and a 10 KB response cap. -### Verify CIMD is enabled - -After applying the configuration, confirm that the discovery document advertises -CIMD support: - -```bash -curl -s https:///.well-known/oauth-authorization-server | \ - python3 -m json.tool | grep client_id_metadata_document -``` - -Replace `` with the `issuer` value from your -`MCPExternalAuthConfig`. You should see -`"client_id_metadata_document_supported": true`. - ## Session storage By default, session storage is in-memory. Upstream tokens are lost when pods diff --git a/docs/toolhive/guides-vmcp/authentication.mdx b/docs/toolhive/guides-vmcp/authentication.mdx index 7ce9c0d0..567d0903 100644 --- a/docs/toolhive/guides-vmcp/authentication.mdx +++ b/docs/toolhive/guides-vmcp/authentication.mdx @@ -398,9 +398,7 @@ stored upstream tokens for backends. Use the embedded authorization server when your backend MCP servers call external APIs on behalf of individual users and no federation relationship exists between your identity provider and those services. It also supports OAuth -2.0 Dynamic Client Registration -([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) and Client ID -Metadata Documents (CIMD) and Dynamic Client Registration +2.0 Client ID Metadata Documents (CIMD) and Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)), so MCP clients can identify themselves or register automatically without manual client configuration in ToolHive.