Fix CIMD documentation gaps#920
Open
amirejaz wants to merge 2 commits into
Open
Conversation
- 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.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
Updates ToolHive documentation to reflect that Client ID Metadata Document (CIMD) support shipped in v0.29.0, correcting prior DCR-only framing and filling UI/Kubernetes guidance gaps so readers understand the CIMD-first, DCR-fallback behavior.
Changes:
- Corrects authentication framework/concept docs to describe CIMD and DCR as supported mechanisms.
- Expands embedded authorization server documentation with CIMD architecture, validation/SSRF notes, and a verification command.
- Updates UI and Kubernetes guides to document CIMD-first behavior and add CIMD troubleshooting.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/toolhive/concepts/auth-framework.mdx | Reframes embedded auth server client registration to include CIMD alongside DCR. |
| docs/toolhive/concepts/embedded-auth-server.mdx | Updates OAuth flow framing and adds CIMD details (architecture, validation, verification). |
| docs/toolhive/concepts/backend-auth.mdx | Adds CIMD mention to embedded auth server overview in backend-auth concept. |
| docs/toolhive/concepts/vmcp.mdx | Updates vMCP concept to note CIMD as an alternative to DCR for clients. |
| docs/toolhive/guides-vmcp/authentication.mdx | Updates embedded auth server guide text to include CIMD support. |
| docs/toolhive/guides-ui/run-mcp-servers.mdx | Updates “Auto-Discovered” remote auth description to CIMD-first then DCR-fallback (two occurrences). |
| docs/toolhive/guides-k8s/auth-k8s.mdx | Adds Kubernetes-specific CIMD troubleshooting guidance. |
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.
danbarr
requested changes
Jun 5, 2026
Collaborator
danbarr
left a comment
danbarr
left a comment
There was a problem hiding this comment.
Thanks for turning this around so quickly. This closes out #919 cleanly.
Coverage check, all accounted for:
auth-framework.mdx: the "is planned" claim is gone and the DCR/CIMD relationship reads accurately.embedded-auth-server.mdx: flow step 1 and "Key characteristics" both reconciled with the CIMD section, plus the two-layer architecture, validation rules, and SSRF summary are good conceptual additions.backend-auth.mdx,vmcp.mdx,guides-vmcp/authentication.mdx: DCR-only framing corrected.guides-ui/run-mcp-servers.mdx: both occurrences updated and now consistent with the CLI guide.auth-k8s.mdx: CIMD troubleshooting landed in the right place.
I left two inline comments: one blocker on the guides-vmcp/authentication.mdx sentence, and one on the verify section's placement.
One more minor thing, non-blocking: in vmcp.mdx, "register or identify themselves automatically through Client ID Metadata Documents (CIMD) or Dynamic Client Registration (DCR)" pairs the verbs against the mechanisms in the opposite order (register maps to DCR, identify to CIMD). Reordering to "identify themselves or register automatically through Client ID Metadata Documents (CIMD) or Dynamic Client Registration (DCR)" lines them up.
Comment on lines
+255
to
+268
| ### Verify CIMD is enabled | ||
|
|
||
| After applying the configuration, confirm that the discovery document advertises | ||
| CIMD support: | ||
|
|
||
| ```bash | ||
| curl -s https://<YOUR_ISSUER_URL>/.well-known/oauth-authorization-server | \ | ||
| python3 -m json.tool | grep client_id_metadata_document | ||
| ``` | ||
|
|
||
| Replace `<YOUR_ISSUER_URL>` with the `issuer` value from your | ||
| `MCPExternalAuthConfig`. You should see | ||
| `"client_id_metadata_document_supported": true`. | ||
|
|
Collaborator
There was a problem hiding this comment.
This is procedural/how-to content in a concepts page, and it also duplicates the content from the actual guide. I would drop it from here.
Suggested change
| ### Verify CIMD is enabled | |
| After applying the configuration, confirm that the discovery document advertises | |
| CIMD support: | |
| ```bash | |
| curl -s https://<YOUR_ISSUER_URL>/.well-known/oauth-authorization-server | \ | |
| python3 -m json.tool | grep client_id_metadata_document | |
| ``` | |
| Replace `<YOUR_ISSUER_URL>` with the `issuer` value from your | |
| `MCPExternalAuthConfig`. You should see | |
| `"client_id_metadata_document_supported": true`. |
Comment on lines
+400
to
+406
| 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 | ||
| ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)), so MCP clients can | ||
| register automatically without manual client configuration in ToolHive. | ||
| identify themselves or register automatically without manual client | ||
| configuration in ToolHive. |
Collaborator
There was a problem hiding this comment.
Looks like this got garbled in an edit and now DCR is listed twice.
Suggested change
| 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 | |
| ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)), so MCP clients can | |
| register automatically without manual client configuration in ToolHive. | |
| identify themselves or register automatically without manual client | |
| configuration in ToolHive. | |
| exists between your identity provider and those services. It also supports OAuth | |
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #919. Corrects factual errors and fills the documentation gaps identified by @danbarr after the v0.29.0 release.
Incorrect claim fixed:
concepts/auth-framework.mdx: removes "Support for CIMD is planned" — CIMD shipped in v0.29.0. Both DCR and CIMD are now described as supported mechanisms.DCR-only framing corrected:
concepts/embedded-auth-server.mdx: "How the OAuth flow works" step 1 and "Key characteristics" now present CIMD alongside DCR. The existing CIMD section (from Update stacklok/toolhive to v0.29.0 #915) is expanded with the two-layer architecture (mermaid diagram), document validation rules, SSRF protections, and a verification command.concepts/backend-auth.mdx,concepts/vmcp.mdx,guides-vmcp/authentication.mdx: one-line additions of CIMD alongside DCR.UI guide gap fixed:
guides-ui/run-mcp-servers.mdx: "Auto-Discovered" now matches the CLI guide — describes CIMD-first then DCR-fallback, applied to both occurrences in the file.Salvaged content from #911:
K8s troubleshooting:
guides-k8s/auth-k8s.mdx: CIMD troubleshooting added inside the Kubernetes-specific details block.Type of change
Generated with Claude Code