Add Virtual MCP Server documentation #326

JAORMX · 2025-11-26T14:47:10Z

Summary

Add documentation skeleton for the new Virtual MCP Server feature
Create new guides-vmcp/ section with 7 guide pages
Add architecture concept page and quickstart tutorial
Update sidebar navigation

New documentation structure

Guides: Virtual MCP Server (`docs/toolhive/guides-vmcp/`)

File	Description
`index.mdx`	Landing page with DocCardList
`intro.mdx`	What/why Virtual MCP, when to use it
`quickstart.mdx`	Getting started with VirtualMCPServer CRD
`configuration.mdx`	Full CRD configuration reference
`tool-aggregation.mdx`	Conflict resolution strategies
`authentication.mdx`	Two-boundary auth model
`composite-tools.mdx`	Multi-step workflows

Additional pages

concepts/vmcp-architecture.mdx - Architecture deep-dive
tutorials/quickstart-vmcp.mdx - End-to-end tutorial

Notes

Documentation focuses on Kubernetes deployment (VirtualMCPServer CRD)
Contains {/* TODO */} placeholders for detailed YAML examples
Based on THV-2106 proposal and implementation in pkg/vmcp

Test plan

Build site locally and verify new pages render correctly
Check sidebar navigation works as expected
Verify all internal links resolve

🤖 Generated with Claude Code

vercel · 2025-11-26T14:47:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
docs-website	Ready	Preview	Comment	Dec 4, 2025 6:34pm

Copilot

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

docs/toolhive/tutorials/quickstart-vmcp.mdx

docs/toolhive/guides-vmcp/intro.mdx

docs/toolhive/guides-vmcp/quickstart.mdx

sidebars.ts

docs/toolhive/concepts/vmcp-architecture.mdx

docs/toolhive/concepts/vmcp.mdx

jhrozek

submitting vmcp-architecture.mdx comments while I read the rest

docs/toolhive/concepts/vmcp-architecture.mdx

sidebars.ts

docs/toolhive/guides-vmcp/authentication.mdx

docs/toolhive/guides-vmcp/composite-tools.mdx

docs/toolhive/guides-vmcp/configuration.mdx

jhrozek

some more comments

docs/toolhive/guides-vmcp/authentication.mdx

docs/toolhive/guides-vmcp/configuration.mdx

docs/toolhive/guides-vmcp/authentication.mdx

docs/toolhive/tutorials/quickstart-vmcp.mdx

docs/toolhive/guides-vmcp/configuration.mdx

docs/toolhive/concepts/vmcp.mdx

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 <noreply@anthropic.com>

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 <noreply@anthropic.com>

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 <noreply@anthropic.com>

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 <noreply@anthropic.com>

- 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 <noreply@anthropic.com>

- 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 <noreply@anthropic.com>

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 <noreply@anthropic.com>

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 <noreply@anthropic.com>

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 <noreply@anthropic.com>

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 <noreply@anthropic.com>

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 <noreply@anthropic.com>

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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com> * 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 <noreply@anthropic.com> * Add note about optional clientSecretRef for token introspection 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>

- 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 <noreply@anthropic.com>

- 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com> * 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 <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>

* 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 <6922515+danbarr@users.noreply.github.com> Co-authored-by: Dan Barr <6922515+danbarr@users.noreply.github.com>

Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com>

Copilot AI review requested due to automatic review settings November 26, 2025 14:47

vercel bot deployed to Preview November 26, 2025 14:47 View deployment

Copilot started reviewing on behalf of JAORMX November 26, 2025 14:47 View session

Copilot finished reviewing on behalf of JAORMX November 26, 2025 14:49

Copilot AI reviewed Nov 26, 2025

View reviewed changes

docs/toolhive/tutorials/quickstart-vmcp.mdx Outdated Show resolved Hide resolved

docs/toolhive/guides-vmcp/intro.mdx Outdated Show resolved Hide resolved

danbarr reviewed Nov 26, 2025

View reviewed changes

docs/toolhive/guides-vmcp/quickstart.mdx Outdated Show resolved Hide resolved

danbarr reviewed Nov 26, 2025

View reviewed changes

sidebars.ts Outdated Show resolved Hide resolved

jhrozek reviewed Nov 26, 2025

View reviewed changes

docs/toolhive/concepts/vmcp-architecture.mdx Outdated Show resolved Hide resolved

danbarr reviewed Nov 26, 2025

View reviewed changes

docs/toolhive/concepts/vmcp.mdx Show resolved Hide resolved

vercel bot had a problem deploying to Preview November 26, 2025 15:24 Failure

vercel bot had a problem deploying to Preview November 26, 2025 15:43 Failure

JAORMX force-pushed the docs/vmcp-documentation-skeleton branch from 64a8357 to 7030ba5 Compare November 26, 2025 16:05

vercel bot deployed to Preview November 26, 2025 16:05 View deployment

jhrozek reviewed Nov 26, 2025

View reviewed changes

vercel bot deployed to Preview November 26, 2025 17:12 View deployment

jhrozek reviewed Nov 26, 2025

View reviewed changes

JAORMX force-pushed the docs/vmcp-documentation-skeleton branch from 4b2f1e0 to da83beb Compare November 26, 2025 21:50

vercel bot deployed to Preview November 26, 2025 21:51 View deployment

jhrozek reviewed Nov 27, 2025

View reviewed changes

docs/toolhive/tutorials/quickstart-vmcp.mdx Outdated Show resolved Hide resolved

vercel bot deployed to Preview November 27, 2025 17:09 View deployment

vercel bot deployed to Preview November 27, 2025 17:14 View deployment

vercel bot deployed to Preview November 27, 2025 17:32 View deployment

vercel bot deployed to Preview November 27, 2025 17:48 View deployment

vercel bot deployed to Preview November 27, 2025 17:53 View deployment

vercel bot deployed to Preview November 27, 2025 17:55 View deployment

jhrozek mentioned this pull request Nov 28, 2025

Fix vMCP documentation based on cluster testing #331

Merged

3 tasks

vercel bot deployed to Preview November 28, 2025 22:04 View deployment

jhrozek reviewed Dec 1, 2025

View reviewed changes

docs/toolhive/guides-vmcp/configuration.mdx Outdated Show resolved Hide resolved

Derek2Tu reviewed Dec 4, 2025

View reviewed changes

docs/toolhive/concepts/vmcp.mdx Outdated Show resolved Hide resolved

JAORMX and others added 17 commits December 4, 2025 11:41

Fix broken link to deleted quickstart.mdx

e275eb3

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 <noreply@anthropic.com>

JAORMX force-pushed the docs/vmcp-documentation-skeleton branch from 159e964 to 68a1c38 Compare December 4, 2025 18:12

vercel bot deployed to Preview December 4, 2025 18:14 View deployment

JAORMX force-pushed the docs/vmcp-documentation-skeleton branch from 68a1c38 to d44013d Compare December 4, 2025 18:27

vercel bot deployed to Preview December 4, 2025 18:28 View deployment

Address feedback about terminology

78b46a3

Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com>

vercel bot deployed to Preview December 4, 2025 18:34 View deployment

danbarr approved these changes Dec 4, 2025

View reviewed changes

danbarr changed the title ~~Add Virtual MCP Server documentation skeleton~~ Add Virtual MCP Server documentation Dec 4, 2025

JAORMX merged commit 49ce724 into main Dec 4, 2025
8 checks passed

JAORMX deleted the docs/vmcp-documentation-skeleton branch December 4, 2025 21:14

This was referenced Dec 4, 2025

Replace fake llm.summarize tool with real example in composite tools docs #367

Open

Add ToolHive CLI and UI connection options to vMCP quickstart #368

Open

Add Virtual MCP Server documentation #326

Add Virtual MCP Server documentation #326

Conversation

JAORMX commented Nov 26, 2025

Summary

New documentation structure

Guides: Virtual MCP Server (docs/toolhive/guides-vmcp/)

Additional pages

Notes

Test plan

Uh oh!

vercel bot commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jhrozek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jhrozek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Guides: Virtual MCP Server (`docs/toolhive/guides-vmcp/`)

vercel bot commented Nov 26, 2025 •

edited

Loading