Add Virtual MCP Server documentation #326
Merged
Conversation
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
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Copilot finished reviewing on behalf of
JAORMX
November 26, 2025 14:49
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation skeleton for the new Virtual MCP Server feature, which enables aggregation of multiple MCP servers into a unified endpoint. The documentation establishes the structure and key concepts while leaving detailed YAML examples to be filled in later via TODO markers.
Key changes:
- Creates a new
guides-vmcp/section with 7 guide pages covering introduction, quickstart, configuration, tool aggregation, authentication, and composite tools - Adds an architecture concept page explaining Virtual MCP internals
- Includes an end-to-end quickstart tutorial for deploying Virtual MCP in Kubernetes
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| sidebars.ts | Adds "Guides: Virtual MCP Server" category with 6 guide pages, adds vmcp-architecture to Concepts section, adds quickstart-vmcp to Tutorials section |
| docs/toolhive/tutorials/quickstart-vmcp.mdx | End-to-end tutorial showing how to deploy Virtual MCP Server, create MCPGroups, aggregate backend servers, and connect clients |
| docs/toolhive/guides-vmcp/index.mdx | Landing page for Virtual MCP guides section with DocCardList component |
| docs/toolhive/guides-vmcp/intro.mdx | Introduction explaining what Virtual MCP is, core capabilities, when to use it, and basic architecture diagram |
| docs/toolhive/guides-vmcp/quickstart.mdx | Step-by-step deployment guide for VirtualMCPServer CRD in Kubernetes (contains TODO placeholders for YAML examples) |
| docs/toolhive/guides-vmcp/configuration.mdx | Complete CRD configuration reference covering all spec and status fields (contains TODO placeholders for detailed examples) |
| docs/toolhive/guides-vmcp/tool-aggregation.mdx | Guide on conflict resolution strategies (prefix, priority, manual), tool filtering, and overrides |
| docs/toolhive/guides-vmcp/authentication.mdx | Explains two-boundary authentication model with incoming auth (OIDC, Kubernetes tokens) and outgoing auth (token exchange, pass-through) |
| docs/toolhive/guides-vmcp/composite-tools.mdx | Documents multi-step workflow capabilities including DAG execution, elicitation, error handling, and template syntax |
| docs/toolhive/concepts/vmcp-architecture.mdx | Architecture deep-dive covering aggregator, router, authentication layer, composer, request flow, and backend discovery |
danbarr
reviewed
Nov 26, 2025
danbarr
reviewed
Nov 26, 2025
jhrozek
reviewed
Nov 26, 2025
danbarr
reviewed
Nov 26, 2025
JAORMX
force-pushed
the
docs/vmcp-documentation-skeleton
branch
from
64a8357 to
7030ba5
Compare
jhrozek
reviewed
Nov 26, 2025
Contributor
jhrozek
left a comment
jhrozek
left a comment
There was a problem hiding this comment.
submitting vmcp-architecture.mdx comments while I read the rest
jhrozek
reviewed
Nov 26, 2025
JAORMX
force-pushed
the
docs/vmcp-documentation-skeleton
branch
from
4b2f1e0 to
da83beb
Compare
jhrozek
reviewed
Nov 27, 2025
3 tasks
jhrozek
reviewed
Dec 1, 2025
Derek2Tu
reviewed
Dec 4, 2025
Add documentation structure for the new Virtual MCP Server feature that aggregates multiple MCP servers into a single unified endpoint. New guides (docs/toolhive/guides-vmcp/): - index.mdx: Landing page - intro.mdx: Introduction and use cases - quickstart.mdx: Getting started with VirtualMCPServer CRD - configuration.mdx: CRD configuration reference - tool-aggregation.mdx: Conflict resolution strategies - authentication.mdx: Two-boundary auth model - composite-tools.mdx: Multi-step workflows New concept page: - concepts/vmcp-architecture.mdx: Architecture overview New tutorial: - tutorials/quickstart-vmcp.mdx: End-to-end tutorial The documentation contains placeholder TODOs for detailed examples and manifests to be filled in. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Changes based on review feedback: - Fix "VS Code" to "Visual Studio Code" on first use (style guide) - Fix link text to match page title in intro.mdx - Remove redundant guides-vmcp/quickstart.mdx (duplicates tutorial) - Update sidebars.ts to remove quickstart from guides section - Rewrite concepts/vmcp-architecture.mdx to be user-focused: - Explain "why" vMCP exists and when to use it - Cover key capabilities with practical examples - Follow Diataxis "Explanation" documentation style - Remove developer-focused architecture details 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Replace pass_through (not implemented) with actual implemented strategies: - unauthenticated: for backends requiring no auth - header_injection: for API keys and bearer tokens - token_exchange: for RFC 8693 token exchange The only implemented outgoing auth strategies are: - unauthenticated - header_injection - token_exchange pass_through is in the design but not yet implemented (see TODO in pkg/vmcp/config/validator.go). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Update configuration.mdx to link to intro.mdx instead of the deleted quickstart.mdx file. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Change title from "Virtual MCP architecture" to "Understanding Virtual MCP Server" to better reflect user-focused content - Remove specific percentages (90%, 87%) that sound LLM-generated - Simplify authentication section: reference MCP spec mechanism instead of specific implementation details like token exchange - Update related links to match new title 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- authentication.mdx: Fix outgoing auth types to use actual CRD values (discovered, pass_through, external_auth_config_ref) instead of fictional types (unauthenticated, token_exchange, header_injection) - authentication.mdx: Clarify that MCPExternalAuthConfig defines the actual auth strategies (tokenExchange, headerInjection) - composite-tools.mdx: Fix field names (dependsOn, onError, maxRetries) to match CRD; remove fictional elicitation fields (onDecline, onCancel) - configuration.mdx: Refactor from reference doc to how-to guide; link to autogenerated CRD spec; fix incoming auth types (anonymous, local, oidc with kubernetes/configMap/inline subtypes) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Replace TODO placeholders with actual working examples provided by jhrozek from testing: - MCPGroup manifest for demo-tools - MCPServer manifests for fetch and osv servers - VirtualMCPServer manifest with anonymous auth and prefix strategy 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Verified against VirtualMCPServer CRD (virtualmcpserver_types.go): - Remove pass_through from outgoing auth (CRD only has discovered, external_auth_config_ref) - Add Failed to status phase list (CRD has Pending, Ready, Degraded, Failed) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Based on PR review feedback: authentication.mdx: - Add OIDC inline configuration example with clientSecretRef - Add Kubernetes service account token example - REMOVE token caching section (not implemented per jhrozek) configuration.mdx: - REMOVE token caching section (not implemented) - Add link to quickstart for MCPGroup reference composite-tools.mdx: - Add info admonition noting elicitation has not been extensively tested 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
authentication.mdx: - Remove Cedar authorization section (not implemented for vMCP) - Remove Cedar policies link from related information tool-aggregation.mdx: - Add note that MCPToolConfig via toolConfigRef is in development - Add complete working example with MCPGroup, MCPServers, and VirtualMCPServer showing prefix-based conflict resolution Verified against CRD definitions in virtualmcpserver_types.go, mcpserver_types.go, and mcpgroup_types.go. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Replace TODO placeholders with working examples: - Incident investigation: parallel data gathering with dependsOn - Deployment with approval: elicitation step for human-in-the-loop - Cross-system data aggregation: template expansion between steps - Complete VirtualMCPServer manifest with inline composite tool Fixed parameter format to use JSON Schema (type: object, properties, required) instead of shorthand notation. Verified against CompositeToolSpec and WorkflowStep definitions in virtualmcpserver_types.go. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Adds VS Code/Copilot mcp.json configuration instructions to the Virtual MCP Server quickstart tutorial. Includes file paths for macOS and Linux, and links to client compatibility reference for other MCP clients. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
* Fix VirtualMCPServer output columns in quickstart Update expected kubectl output to match actual CRD printer columns: - Change STATUS to PHASE - Add BACKENDS and READY columns Verified by testing against live cluster. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * Fix minimal VirtualMCPServer config to include required incomingAuth The vMCP binary requires incomingAuth.type to be specified. Without it, the pod crashes with: "incoming_auth.type must be one of: oidc, local, anonymous" Verified by testing against live cluster. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * Add note about optional clientSecretRef for token introspection 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: Claude <[email protected]>
- Change fetch.fetch_url to fetch.fetch (correct tool name) - Add comment clarifying llm.summarize is a hypothetical backend 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <[email protected]>
- Add warning for anonymous incoming authentication - Simplify outgoing auth to discovery mode only (tested working) - Remove broken default config (CRD/binary type mismatch) - Remove external_auth_config_ref examples (pending code fixes) - Remove TODO placeholders - Add link to configuration guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <[email protected]>
* Simplify outgoing auth in configuration docs - Remove broken default.type: discovered config - Remove broken source: mixed with external_auth_config_ref example - Simplify to just source: discovered (tested working) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * Clarify OIDC clientSecretRef is for opaque tokens - Separate basic OIDC example (without clientSecretRef) - Add explanation for opaque OAuth token introspection - Show full example with clientSecretRef for that use case 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: Claude <[email protected]>
* Polish vMCP documentation
- Apply consistent terminology: 'Virtual MCP Server (vMCP)' on first
mention, then 'vMCP'
- Rewrite bullet lists with complete sentences
- Add MCPGroup context explanation on first use
- Expand outgoing auth configuration details
- Enhance experimental feature warning
- Improve language directness
* Add vMCP usage to style guide and LLM instructions
* Note that vMCP is part of the operator
* Add vMCP to nav menu
* Polish the intro
* Polish the config guide
- Add MCPGroup section since it doesn't have its own guide
- Remove redundant auth content, just point to auth guide
- Note that ClusterIP can be exposed via Ingress/Gateway
* Add vMCP CRDs to operator deployment guide
* Rename vMCP concepts file and re-order guides
Feels like the tool aggregation and composite guides logically belong
together.
* Polish auth guide
* Polish tool aggregation guide
* Polish composite tools guide
- Soften technical jargon ("DAG")
- Add basic info up front before the full use cases
- Make sure all YAML snippets have parent keys to make location
and indentation clear
* Polish the quickstart and concepts guides
* Add quickstart and concepts links to index
* Clarify inbound auth spec conformance
* Clarify service options
---------
Signed-off-by: Dan Barr <[email protected]>
Co-authored-by: Dan Barr <[email protected]>
JAORMX
force-pushed
the
docs/vmcp-documentation-skeleton
branch
from
159e964 to
68a1c38
Compare
JAORMX
force-pushed
the
docs/vmcp-documentation-skeleton
branch
from
68a1c38 to
d44013d
Compare
Signed-off-by: Juan Antonio Osorio <[email protected]>
danbarr
approved these changes
Dec 4, 2025
danbarr
changed the title
This was referenced Dec 4, 2025
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
guides-vmcp/section with 7 guide pagesNew documentation structure
Guides: Virtual MCP Server (
docs/toolhive/guides-vmcp/)index.mdxintro.mdxquickstart.mdxconfiguration.mdxtool-aggregation.mdxauthentication.mdxcomposite-tools.mdxAdditional pages
concepts/vmcp-architecture.mdx- Architecture deep-divetutorials/quickstart-vmcp.mdx- End-to-end tutorialNotes
{/* TODO */}placeholders for detailed YAML examplespkg/vmcpTest plan
🤖 Generated with Claude Code