Commit 49ce724
Add Virtual MCP Server documentation (#326)
* Add Virtual MCP Server documentation skeleton
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]>
* Address PR feedback for Virtual MCP documentation
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]>
* Fix unimplemented pass_through auth strategy references
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]>
* Fix broken link to deleted quickstart.mdx
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]>
* Address PR feedback for Virtual MCP documentation
- 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]>
* Fix vMCP docs to match actual CRD field names
- 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]>
* Add working YAML examples to vMCP quickstart tutorial
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]>
* Fix vMCP docs: remove non-existent CRD features
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]>
* Address jhrozek's PR feedback on vMCP documentation
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]>
* Remove unimplemented features, add tool aggregation example
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]>
* Add workflow examples to composite-tools.mdx
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]>
* Add VS Code configuration to vMCP quickstart
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 vMCP documentation based on cluster testing (#331)
* 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]>
* Fix composite tools example tool reference (#337)
- 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]>
* Simplify authentication docs to tested configurations (#343)
- 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]>
* Fix outgoing auth and clarify OIDC clientSecretRef (#344)
* 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 docs (#347)
* 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]>
* Address feedback about terminology
Signed-off-by: Juan Antonio Osorio <[email protected]>
---------
Signed-off-by: Dan Barr <[email protected]>
Signed-off-by: Juan Antonio Osorio <[email protected]>
Co-authored-by: Claude <[email protected]>
Co-authored-by: Jakub Hrozek <[email protected]>
Co-authored-by: Dan Barr <[email protected]>
Co-authored-by: Dan Barr <[email protected]>1 parent d351ac7 commit 49ce724
File tree
14 files changed
+1442
-11
lines changed- .github
- docs/toolhive
- concepts
- guides-k8s
- guides-vmcp
- tutorials
14 files changed
+1442
-11
lines changed| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
107 | 107 | | |
108 | 108 | | |
109 | 109 | | |
| 110 | + | |
110 | 111 | | |
111 | 112 | | |
112 | 113 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
107 | 107 | | |
108 | 108 | | |
109 | 109 | | |
| 110 | + | |
110 | 111 | | |
111 | 112 | | |
112 | 113 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
263 | 263 | | |
264 | 264 | | |
265 | 265 | | |
| 266 | + | |
| 267 | + | |
| 268 | + | |
| 269 | + | |
| 270 | + | |
266 | 271 | | |
267 | 272 | | |
268 | 273 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
33 | 33 | | |
34 | 34 | | |
35 | 35 | | |
36 | | - | |
| 36 | + | |
37 | 37 | | |
38 | 38 | | |
39 | 39 | | |
| |||
52 | 52 | | |
53 | 53 | | |
54 | 54 | | |
55 | | - | |
| 55 | + | |
56 | 56 | | |
57 | 57 | | |
58 | 58 | | |
| |||
237 | 237 | | |
238 | 238 | | |
239 | 239 | | |
240 | | - | |
| 240 | + | |
241 | 241 | | |
242 | 242 | | |
243 | 243 | | |
244 | 244 | | |
245 | 245 | | |
246 | | - | |
247 | | - | |
248 | | - | |
249 | | - | |
250 | | - | |
251 | | - | |
| 246 | + | |
| 247 | + | |
| 248 | + | |
| 249 | + | |
| 250 | + | |
| 251 | + | |
| 252 | + | |
| 253 | + | |
252 | 254 | | |
253 | 255 | | |
254 | | - | |
| 256 | + | |
255 | 257 | | |
256 | 258 | | |
257 | 259 | | |
| |||
267 | 269 | | |
268 | 270 | | |
269 | 271 | | |
270 | | - | |
| 272 | + | |
271 | 273 | | |
272 | 274 | | |
273 | 275 | | |
| |||
302 | 304 | | |
303 | 305 | | |
304 | 306 | | |
| 307 | + | |
| 308 | + | |
305 | 309 | | |
306 | 310 | | |
307 | 311 | | |
| |||
0 commit comments