Add CIMD support documentation#911
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
Adds ToolHive documentation for Client ID Metadata Documents (CIMD), covering both ToolHive-as-client behavior (thv run) and ToolHive-as-server behavior (embedded authorization server in Kubernetes), and wires the new pages into the docs navigation.
Changes:
- Add a new CIMD concept page describing the protocol, ToolHive behavior, architecture, and security model.
- Add a new Kubernetes how-to guide for enabling CIMD on the embedded authorization server via
MCPExternalAuthConfig. - Update embedded authorization server concept docs and the sidebar to cross-link and expose the new pages.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
sidebars.ts |
Adds the new CIMD concept page and Kubernetes guide to the Concepts and Kubernetes Operator sidebars. |
docs/toolhive/guides-k8s/cimd-embedded-as.mdx |
New how-to guide describing how to enable CIMD and tune caching for the embedded authorization server. |
docs/toolhive/concepts/embedded-auth-server.mdx |
Adds a CIMD support section with links to the new concept and how-to pages. |
docs/toolhive/concepts/cimd.mdx |
New concept doc explaining CIMD, ToolHive’s two usage directions, and the embedded AS security/caching model. |
| kubectl port-forward svc/my-mcp-server 8443:443 & | ||
| curl -s https://localhost:8443/.well-known/oauth-authorization-server | \ | ||
| python3 -m json.tool | grep client_id_metadata_document |
| - The document declares `grant_types` that do not include `authorization_code`, | ||
| or declares a `response_type` other than `code`. |
|
|
||
| ::: | ||
|
|
||
| ## Troubleshooting |
| - The document must declare at least one `redirect_uri`, and all redirect URIs | ||
| must pass strict validation (RFC 8252). |
- Fix namespace: default → toolhive-system to match operator convention - Fix verification command: use correct proxy port (8080) and service name pattern instead of placeholder 8443/443 - Add version availability notice (cimd field requires specific operator version) to both the concept doc and the k8s guide - Fix prerequisite anchor to match exact heading in auth-k8s.mdx - Add -n toolhive-system to kubectl describe command in troubleshooting
danbarr
left a comment
danbarr
left a comment
There was a problem hiding this comment.
Content here is accurate and well-written, but before the line-level notes, one process point that should gate the merge.
Hold this until CIMD is actually released. When the release is cut, the automated release-docs generation PR will fire, and if it correctly picks up the completed CIMD work it'll regenerate the MCPExternalAuthConfig CRD reference (adding the cimd, cacheMaxSize, and cacheFallbackTtl fields) and likely some accompanying prose. That will overlap with what's in this PR. Rather than merge now and reconcile later, this content should be laid on top of the release-docs PR when it lands, so we resolve any duplication once instead of fixing it twice. Right now the cimd block isn't in the committed schema (static/api-specs/crds/mcpexternalauthconfigs.schema.json) yet, which confirms we're ahead of the release.
With that settled, the content notes:
1. This is over-built for the feature; slim the concept rather than keep a full standalone guide. The one genuinely cross-cutting, homeless idea is the client-side direction (thv run against Linear, automatic with DCR fallback), plus the dual-direction / two-layer architecture diagram. That's the concept-worthy core (~400 words). Most of the rest is implementation detail that duplicates the how-to.
2. Cross-document duplication. The cache table, the document-validation rules, and the Cache-Control limitation are each documented in both cimd.mdx and cimd-embedded-as.mdx (the Cache-Control caveat appears in four places across the two files). Pick one home for each: cache config and validation belong in the how-to; the concept should summarize and link.
3. SSRF internals are too low-level for user docs. cimd.mdx lines 141-151 (keep-alive disabled, DNS-first resolution, body caps) read like engineering notes a reader can't act on. Cut to a sentence or move to reference.
4. Buried lede. For thv run users the headline is "it's automatic, nothing to configure." cimd.mdx opens with two paragraphs of IETF-draft definition first. Lead with what it does for the reader.
5. The how-to is missing a "Next steps" section, and its closing order is wrong. cimd-embedded-as.mdx ends Troubleshooting then Related information. The pattern is Next steps > Related information > Troubleshooting.
6. Cross-cutting content is only reachable through Kubernetes entry points. cimd.mdx is linked only from the embedded-AS concept and the K8s how-to, so a CLI user connecting to Linear has no path to it. Add an inbound link from a CLI remote-auth or backend-auth context.
Secondary: cimd.mdx description runs ~165 chars (over the 160 SEO limit); tighten. Otherwise the prose, the mermaid diagram, and the real Linear example all hold up well.
- Fix redirect_uri → redirect_uris (plural) in concept doc - Fix response_type → response_types (plural) in guide troubleshooting - Restructure guide closing sections to match established pattern: Next steps → Related information → Troubleshooting - Add Next steps section with 3 links
Summary
Documents the Client ID Metadata Document (CIMD) feature shipped in toolhive#5320, #5343, and #5348.
CIMD eliminates OAuth app pre-registration in two directions:
thv run): automatically useshttps://toolhive.dev/oauth/client-metadata.jsonwhen the remote AS advertises CIMD support (e.g. Linear), falls back to DCR otherwiseclient_idfrom clients like VS Code without prior DCR registrationFiles changed
docs/toolhive/concepts/cimd.mdxdocs/toolhive/concepts/embedded-auth-server.mdxdocs/toolhive/guides-k8s/cimd-embedded-as.mdxMCPExternalAuthConfigCRD, cache config, verification, troubleshootingsidebars.tsGenerated with Claude Code