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]>

Author: danbarr

.github/copilot-instructions.md

@@ -107,6 +107,7 @@ Common terms used in this project:
 - open source (not "open-source")
 - large language model (LLM)
 - Visual Studio Code ("VS Code" after first use)
+- Virtual MCP Server (vMCP) - a feature of ToolHive that aggregates multiple MCP servers into a single endpoint; use "Virtual MCP Server (vMCP)" on first use, "vMCP" thereafter
 
 Check this list for consistent use within the documentation. If you find inconsistencies, update the text to match the preferred term. If you find a term that is not listed here, consider adding it to the list for future reference.
 

AGENTS.md

@@ -107,6 +107,7 @@ Common terms used in this project:
 - open source (not "open-source")
 - large language model (LLM)
 - Visual Studio Code ("VS Code" after first use)
+- Virtual MCP Server (vMCP) - a feature of ToolHive that aggregates multiple MCP servers into a single endpoint; use "Virtual MCP Server (vMCP)" on first use, "vMCP" thereafter
 
 Check this list for consistent use within the documentation. If you find inconsistencies, update the text to match the preferred term. If you find a term that is not listed here, consider adding it to the list for future reference.
 

STYLE-GUIDE.md

@@ -263,6 +263,11 @@ all caps. Written out, it is lower-cased.
 applications provide context to LLMs. MCP is an abbreviation, so it's written in
 all caps. Written out, it is proper-cased.
 
+**vMCP**: Virtual MCP Server, a feature of ToolHive that aggregates multiple MCP
+servers into a single endpoint. It's written with a lowercase "v" followed by
+"MC" in all caps and a capital "P" (not "VMCP" or "Vmcp"). Use "Virtual MCP
+Server (vMCP)" on first use, "vMCP" thereafter.
+
 **npm**: the registry for JavaScript packages (the "npm registry"), and the
 default package manager for JavaScript. Since it's both the registry _and_ the
 package manager, it may be useful to disambiguate "the npm registry". It's not

docs/toolhive/concepts/vmcp-architecture.mdx renamed to docs/toolhive/concepts/vmcp.mdx

@@ -1,12 +1,14 @@
 ---
 title: Understanding Virtual MCP Server
+sidebar_label: Virtual MCP Server (vMCP)
 description:
   Learn what Virtual MCP Server does, why it exists, and when to use it.
 ---
 
-This document explains Virtual MCP Server (vMCP), why it exists, and when you
-should use it. You'll learn how vMCP simplifies managing multiple MCP servers
-and enables powerful multi-system workflows.
+This document explains Virtual MCP Server (vMCP), a feature of the ToolHive
+Kubernetes Operator. You'll learn why it exists, when to use it, and how it
+simplifies managing multiple MCP servers while enabling powerful multi-system
+workflows.
 
 ## The problem vMCP solves
 
@@ -20,7 +22,7 @@ tools with sensible defaults.
 
 ## Core value propositions
 
-Virtual MCP Server delivers four key benefits:
+vMCP delivers four key benefits:
 
 1. **Reduce complexity**: Many connections become one, dramatically simplifying
    configuration
@@ -39,8 +41,8 @@ own configuration, authentication, and maintenance. vMCP aggregates all backends
 into one endpoint with automatic conflict resolution.
 
 **Example scenario**: An engineering team needs access to 8 backend servers
-(GitHub, Jira, Slack, Confluence, PagerDuty, Datadog, AWS, Internal Docs).
-Instead of configuring 8 separate connections, they configure one vMCP
+(GitHub, Jira, Slack, Confluence, PagerDuty, Datadog, AWS, and internal company
+docs). Instead of configuring 8 separate connections, they configure one vMCP
 connection with SSO. This significantly reduces configuration complexity and
 makes onboarding new team members much easier.
 
@@ -57,14 +59,15 @@ error handling, and human-in-the-loop approval gates.
 
 **Example scenario**: During an incident investigation, you need logs from your
 logging system, metrics from your monitoring platform, traces from your tracing
-service, and infrastructure status from your cloud provider. With vMCP, you
-fetch all of this in parallel (4x faster than sequential), automatically
-aggregate it into a formatted report, and create a Jira ticket with all the
-data. This workflow is reusable for every incident.
-
-**Example scenario**: For a PR deployment, you might want to merge the PR, wait
-for tests, ask a human for approval, deploy only if approved, and notify Slack.
-vMCP handles this entire flow declaratively, with automatic rollback on
+service, and infrastructure status from your cloud provider. Without vMCP, an
+engineer manually runs 4 commands sequentially and aggregates results. With
+vMCP, you fetch all of this in parallel, automatically aggregate it into a
+formatted report, and create a Jira ticket with all the data. This workflow is
+reusable for every incident.
+
+**Example scenario**: For an app deployment, merge the pull request, wait for
+tests, ask a human for approval, deploy only if approved, and notify the team in
+Slack. vMCP handles this entire flow declaratively, with automatic rollback on
 deployment failure.
 
 ### Tool customization and overrides
@@ -88,24 +91,26 @@ Generic servers require repetitive parameter specification. You always use the
 same repo, channel, or database. vMCP lets you create specialized instances with
 pre-configured defaults.
 
-**Example scenario**: All GitHub queries for your team should default to the
-`stacklok/toolhive` repo. Engineers never need to specify the repo parameter,
-and they can't accidentally query the wrong repository.
+**Example scenario**: Without vMCP, every GitHub query requires specifying
+`repo: stacklok/toolhive`. With vMCP, you pre-configure this default - engineers
+never specify the repo parameter, and they can't accidentally query the wrong
+repository. This eliminates hundreds of repetitive parameter entries per week.
 
-**Example scenario**: Staging database is the default (safe for development),
-while production queries require an explicit approval gate. Connection details
-are centralized in the vMCP configuration.
+**Example scenario**: Configure staging database as the default (safe for
+development), while production queries require an explicit approval gate.
+Connection details are centralized in vMCP configuration instead of scattered
+across individual tool configurations.
 
 ### Authentication boundary separation
 
 Different auth is needed for clients versus backends, and managing credentials
 across multiple systems is complex. vMCP implements a two-boundary auth model
 that separates these concerns.
 
-**How it works**: Clients authenticate to vMCP using the mechanism defined in
-the MCP specification. vMCP then handles authentication to each backend MCP
-server independently. Revoking access is simple: disable the user in your
-identity provider and all backend access is revoked instantly.
+**How it works**: Clients authenticate to vMCP using OAuth 2.1 authorization as
+defined in the MCP specification. vMCP then handles authentication to each
+backend MCP server independently. Revoking access is simple: disable the user in
+your identity provider and all backend access is revoked instantly.
 
 This approach provides single sign-on for users, centralized access control, and
 a complete audit trail.
@@ -128,14 +133,13 @@ a complete audit trail.
 
 ## Summary
 
-Virtual MCP Server transforms MCP from individual servers into a unified
-orchestration platform. The use cases range from simple aggregation to complex
-workflows with approval gates, making it valuable for teams managing multiple
-MCP servers.
+vMCP transforms MCP from individual servers into a unified orchestration
+platform. The use cases range from simple aggregation to complex workflows with
+approval gates, making it valuable for teams managing multiple MCP servers.
 
 ## Related information
 
-- [Deploy Virtual MCP Server](../guides-vmcp/intro.mdx)
+- [Deploy vMCP](../guides-vmcp/intro.mdx)
+- [Configure authentication](../guides-vmcp/authentication.mdx)
 - [Tool aggregation and conflict resolution](../guides-vmcp/tool-aggregation.mdx)
-- [Authentication](../guides-vmcp/authentication.mdx)
 - [Composite tools and workflows](../guides-vmcp/composite-tools.mdx)

docs/toolhive/guides-k8s/deploy-operator-helm.mdx

@@ -33,7 +33,7 @@ chart. To install a specific version, append `--version <VERSION>` to the
 command, for example:
 
 ```bash
-helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.52
+helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.73
 ```
 
 ## Install the operator
@@ -52,7 +52,7 @@ chart. To install a specific version, append `--version <VERSION>` to the
 command, for example:
 
 ```bash
-helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace --version 0.3.7
+helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace --version 0.5.6
 ```
 
 Verify the installation:
@@ -237,21 +237,23 @@ and then apply the CRDs using `kubectl`.
 First, upgrade the CRD Helm chart to match your target operator version:
 
 ```bash
-helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.52
+helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version 0.0.73
 ```
 
 Then apply the CRDs from the same version tag:
 
 ```bash
-kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpexternalauthconfigs.yaml
-kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcptoolconfigs.yaml
-kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpremoteproxies.yaml
-kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpservers.yaml
-kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpgroups.yaml
-kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.52/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpregistries.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.73/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpexternalauthconfigs.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.73/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcptoolconfigs.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.73/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpremoteproxies.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.73/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpservers.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.73/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpgroups.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.73/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_mcpregistries.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.73/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_virtualmcpcompositetooldefinitions.yaml
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/tags/toolhive-operator-crds-0.0.73/deploy/charts/operator-crds/crds/toolhive.stacklok.dev_virtualmcpservers.yaml
 ```
 
-Replace `0.0.52` in both commands with your target CRD version.
+Replace `0.0.73` in both commands with your target CRD version.
 
 ### Upgrade the operator Helm release
 
@@ -267,7 +269,7 @@ This upgrades the operator to the latest version available in the OCI registry.
 To upgrade to a specific version, add the `--version` flag:
 
 ```bash
-helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values --version 0.3.7
+helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --reuse-values --version 0.5.6
 ```
 
 If you have a custom `values.yaml` file, include it with the `-f` flag:
@@ -302,6 +304,8 @@ kubectl delete crd mcpremoteproxies.toolhive.stacklok.dev
 kubectl delete crd mcpservers.toolhive.stacklok.dev
 kubectl delete crd mcpgroups.toolhive.stacklok.dev
 kubectl delete crd mcpregistries.toolhive.stacklok.dev
+kubectl delete crd virtualmcpcompositetooldefinitions.toolhive.stacklok.dev
+kubectl delete crd virtualmcpservers.toolhive.stacklok.dev
 ```
 
 Finally, uninstall the CRD Helm chart metadata:

docs/toolhive/guides-vmcp/authentication.mdx

@@ -1,10 +1,10 @@
 ---
 title: Authentication
-description: Configure client and backend authentication for Virtual MCP Server.
+description: Configure client and backend authentication for vMCP.
 ---
 
-Virtual MCP implements a two-boundary authentication model that separates client
-authentication from backend authentication, giving you centralized control over
+Virtual MCP Server (vMCP) implements a two-boundary authentication model that
+separates client and backend authentication, giving you centralized control over
 access while supporting diverse backend requirements.
 
 ## Two-boundary authentication model
@@ -14,83 +14,86 @@ flowchart LR
     subgraph Boundary1[" "]
         direction TB
         Client[MCP Client]
-        B1Label["**Boundary 1**<br>Client → Virtual MCP"]
+        B1Label["**Boundary 1**<br>Client → vMCP"]
     end
 
-    subgraph vMCP[Virtual MCP Server]
-        Auth[Token Validation]
-        Backend[Backend Auth]
+    subgraph vMCP["Virtual MCP Server (vMCP)"]
+        Auth[Token validation]
+        Backend[Backend auth]
     end
 
     subgraph Boundary2[" "]
         direction TB
-        B2Label["**Boundary 2**<br>Virtual MCP → Backend APIs"]
+        B2Label["**Boundary 2**<br>vMCP → Backend APIs"]
         GitHub[GitHub API]
         Jira[Jira API]
     end
 
-    Client -->|"vMCP-scoped token"| Auth
+    Client -->|"vMCP-scoped<br>token"| Auth
     Auth --> Backend
-    Backend -->|"Backend-scoped token"| GitHub
-    Backend -->|"Backend-scoped token"| Jira
+    Backend -->|"Backend-scoped<br>token"| GitHub
+    Backend -->|"Backend-scoped<br>token"| Jira
 ```
 
-**Boundary 1 (Incoming):** Clients authenticate to Virtual MCP using the
-mechanism defined in the MCP specification. This is your organization's identity
-layer.
+**Boundary 1 (Incoming):** Clients authenticate to vMCP using OAuth 2.1
+authorization as defined in the
+[MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
+This is your organization's identity layer.
 
-**Boundary 2 (Outgoing):** Virtual MCP obtains appropriate credentials for each
+**Boundary 2 (Outgoing):** vMCP obtains appropriate credentials for each
 backend. Each backend API receives a token or credential scoped to its
 requirements.
 
 ## Incoming authentication
 
-Configure how clients authenticate to Virtual MCP.
+Configure how clients authenticate to vMCP.
 
 ### Anonymous (development only)
 
-No authentication required. Use only for local development.
+No authentication required:
 
-```yaml
+```yaml title="VirtualMCPServer resource"
 spec:
   incomingAuth:
     type: anonymous
 ```
 
 :::warning
 
-Never use `anonymous` incoming authentication in production environments.
+Do not use `anonymous` authentication in production environments. This setting
+disables all access control, allowing anyone to use the vMCP without
+credentials.
 
 :::
 
 ### OIDC authentication
 
 Validate tokens from an external identity provider:
 
-```yaml
+```yaml title="VirtualMCPServer resource"
 spec:
   incomingAuth:
     type: oidc
     oidcConfig:
       type: inline
       inline:
         issuer: https://auth.example.com
-        clientId: your-client-id
+        clientId: <YOUR_CLIENT_ID>
         audience: vmcp
 ```
 
 When using an identity provider that issues opaque OAuth tokens, add a
 `clientSecretRef` referencing a Kubernetes Secret to enable token introspection:
 
-```yaml
+```yaml title="VirtualMCPServer resource"
 spec:
   incomingAuth:
     type: oidc
     oidcConfig:
       type: inline
       inline:
         issuer: https://auth.example.com
-        clientId: your-client-id
+        clientId: <YOUR_CLIENT_ID>
         audience: vmcp
         clientSecretRef:
           name: oidc-client-secret
@@ -107,14 +110,14 @@ metadata:
   namespace: toolhive-system
 type: Opaque
 stringData:
-  clientSecret: your-client-secret
+  clientSecret: <YOUR_CLIENT_SECRET>
 ```
 
 ### Kubernetes service account tokens
 
 Authenticate using Kubernetes service account tokens for in-cluster clients:
 
-```yaml
+```yaml title="VirtualMCPServer resource"
 spec:
   incomingAuth:
     type: oidc
@@ -132,15 +135,15 @@ validates service account tokens. The defaults work for most clusters:
 
 ## Outgoing authentication
 
-Configure how Virtual MCP authenticates to backend MCP servers.
+Configure how vMCP authenticates to backend MCP servers.
 
 ### Discovery mode
 
-When using discovery mode, Virtual MCP checks each backend MCPServer's
+When using discovery mode, vMCP checks each backend MCPServer's
 `externalAuthConfigRef` to determine how to authenticate. If a backend has no
-auth config, Virtual MCP connects without authentication.
+auth config, vMCP connects without authentication.
 
-```yaml
+```yaml title="VirtualMCPServer resource"
 spec:
   outgoingAuth:
     source: discovered
@@ -150,6 +153,10 @@ This is the recommended approach for most deployments. Backends that don't
 require authentication work automatically, while backends with
 `externalAuthConfigRef` configured use their specified authentication method.
 
+See
+[Configure token exchange for backend authentication](../guides-k8s/token-exchange-k8s.mdx)
+for details on using service account token exchange for backend authentication.
+
 ## Related information
 
 - [Authentication framework concepts](../concepts/auth-framework.mdx)