Restructure vMCP authentication docs around scenarios#1023
Merged
Conversation
Split the 1009-line authentication.mdx into a scenario-first entry point plus a dedicated embedded-auth-server-vmcp.mdx deep-dive, mirroring the Kubernetes auth restructure. Both nest under a new "Authentication and authorization" sidebar category. The entry point leads with a "Choose a backend authentication pattern" decision table and covers incoming auth, authorization, and the standalone backend strategies. The embedded auth server page holds the strategies that depend on it (upstream injection, token exchange with subjectProviderName, XAA) plus the complete example. Re-validate against the CRD schemas and document previously missing surface: passthroughHeaders, outgoingAuth.default, oidcConfigRef resourceUrl/scopes, AWS STS backend auth, and vMCP Cedar authorization via authzConfig/authzConfigRef. Cross-link the full AWS STS tutorial. Fix inbound links in concept, K8s, and integration docs that pointed at moved or renamed anchors. All YAML dry-run validated against a live cluster; site builds with no broken links. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add two mermaid diagrams and tighten the existing one: - "How the resources connect" on the entry page, showing the backend's own oidcConfigRef and the shared MCPExternalAuthConfig referenced inline or via discovery. - "How the references link by name" on the embedded auth server page, showing the issuer and providerName/subjectProviderName string matches that trip people up. - Simplify the two-boundary diagram (boundary labels become subgraph titles, collapse the backend API boxes into one). - Convert the stacked "non-standard provider responses" tips into prose subsections, and note the backend-linkage rules apply to the embedded strategies too. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
From an independent editorial pass:
- Elevate MCPServerEntry as a first-class backend shape. "How the
resources connect" now contrasts ToolHive-managed backends (own
oidcConfigRef) with remote MCPServerEntry pointers (no oidcConfigRef;
the remote validates), the diagram shows both, and the upstream
injection section adds a remote-SaaS MCPServerEntry example since that
is its typical use.
- Match cross-link text to the "Authentication and authorization" page
title.
- Replace a spaced double-hyphen with a semicolon.
- Trim the duplicated passthroughHeaders precedence explanation to a
pointer, keeping the full version in its own section.
- Reword the front-matter description ("backend auth" ->
"backend authentication").
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR continues the scenario-first authentication docs restructure for Virtual MCP Server (vMCP), splitting embedded-auth-server content into a dedicated deep-dive page, reorganizing navigation under a new “Authentication and authorization” category, and updating cross-doc links to the new locations.
Changes:
- Reorganizes the vMCP auth docs into an entry-point page plus a new embedded-auth-server-vMCP deep-dive.
- Updates the vMCP sidebar structure to group auth docs under a dedicated category.
- Fixes inbound links/anchors across integrations and concepts to point at the new pages/sections.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| sidebars.ts | Adds an “Authentication and authorization” category under vMCP and nests the new embedded-auth page beneath it. |
| docs/toolhive/integrations/vmcp-okta.mdx | Updates the embedded-auth-server link to the new vMCP embedded auth server page/anchor. |
| docs/toolhive/integrations/vmcp-entra-id.mdx | Updates the embedded-auth-server link to the new vMCP embedded auth server page/anchor. |
| docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx | Introduces a new dedicated deep-dive page for the vMCP embedded authorization server. |
| docs/toolhive/guides-vmcp/configuration.mdx | Updates link text/anchor to the renamed “Backend authentication” section. |
| docs/toolhive/guides-vmcp/authentication.mdx | Restructures the page around incoming auth, authorization, and backend auth, with updated diagrams and strategy guidance. |
| docs/toolhive/guides-k8s/remote-mcp-proxy.mdx | Updates a link to the new “Backend authentication” anchor in the vMCP auth page. |
| docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx | Updates the vMCP embedded-auth-server cross-link to point to the new dedicated page. |
| docs/toolhive/concepts/vmcp.mdx | Updates the embedded-auth-server setup link to the new dedicated vMCP page. |
| docs/toolhive/concepts/embedded-auth-server.mdx | Updates links/anchors for vMCP embedded-auth-server strategies to the new dedicated vMCP page. |
- Use a unique URL-like audience in the first OIDC example instead of the generic "vmcp", matching the uniqueness guidance below it. - Standardize the passthrough header example on X-API-Key casing. - Trim the Next steps list to three links (the IdP overview is already linked earlier on the page). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
rdimitrov
approved these changes
Jul 9, 2026
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.
Description
Continues the auth-docs restructure from #1014 (which did the Kubernetes side), now applied to the vMCP authentication docs. Same goal: lead with scenarios instead of an approach-by-approach enumeration, split the oversized page, and re-validate every field against the authoritative CRD schemas.
Highlights:
guides-vmcp/authentication.mdxinto a scenario-first entry point plus a dedicatedembedded-auth-server-vmcp.mdxdeep-dive, mirroring the Kubernetesembedded-auth-server-k8s.mdxsibling. Both nest under a new "Authentication and authorization" sidebar category.subjectProviderName, XAA) from the standalone ones.passthroughHeaders,outgoingAuth.default,oidcConfigRefresourceUrl/scopes, AWS STS backend auth, and vMCP Cedar authorization viaauthzConfig/authzConfigRef. Adds an enterprise admonition for the Entraobotype and a one-liner forunauthenticated.oidcConfigRefof their own), and an embedded-page diagram of the issuer /providerNamestring matches that trip people up.Verification: full editorial pass by an independent review agent (fresh context, no visibility into the rest of this work) checking IA, clarity, and style-guide compliance, with findings addressed. All YAML examples across both pages were dry-run validated against a live cluster's CRDs (the one exception is the XAA block, which is correct per the authoritative auto-generated schema but fails on the local demo cluster whose operator predates the
xaafield). Site builds with no broken links or anchors.Type of change
Related issues/PRs
Continuation of #1014 (Kubernetes auth restructure). Same auth-docs audit effort.
Screenshots
N/A. No UI changes; the new sidebar category and mermaid diagrams are described above and visible in the Vercel preview.
Submitter checklist
Content and formatting
Navigation
sidebars.ts) updated for added, deleted, reordered, or renamed filesauthentication.mdxkeeps its URL andembedded-auth-server-vmcp.mdxis a new URL, so novercel.jsonredirects are neededReviewer checklist
Content