document vMCP remote server support

docs/toolhive/concepts/vmcp.mdx

@@ -40,11 +40,30 @@ Managing 10-20+ MCP server connections is overwhelming. Each server needs its
 own configuration, authentication, and maintenance. vMCP aggregates all backend
 MCP servers into one endpoint with automatic conflict resolution.
 
+vMCP supports two types of backends:
+
+- **MCPServer**: Container-based MCP servers running in your Kubernetes cluster
+- **MCPRemoteProxy**: Proxies to external remote MCP servers (SaaS platforms,
+  third-party services, or MCP servers hosted outside your cluster)
+
+:::note MCPRemoteProxy support
+
+MCPRemoteProxy support in vMCP is currently in development. vMCP can discover
+MCPRemoteProxy backends, but authentication between vMCP and MCPRemoteProxy is
+not yet fully implemented. MCPServer backends work fully with vMCP.
+
+:::
+
+This architecture enables combining internal tools with external SaaS MCP
+endpoints in a single unified interface.
+
 **Example scenario**: An engineering team needs access to 8 backend servers
 (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.
+docs). Some are container-based MCPServer resources running in the cluster,
+while others are remote SaaS MCP endpoints accessed via MCPRemoteProxy. 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.
 
 When multiple backend MCP servers have tools with the same name (for example,
 both GitHub and Jira have `create_issue`), vMCP automatically prefixes them:
@@ -119,11 +138,12 @@ a complete audit trail.
 
 ### Good fit
 
-- Teams managing 5+ MCP servers
+- Teams managing 5+ MCP servers (local or remote)
 - Tasks requiring coordination across multiple systems
 - Centralized authentication and authorization requirements
 - Workflows that should be reusable across the team
 - Security policies that need centralized enforcement
+- Aggregating external SaaS MCP servers with internal tools
 
 ### Not needed
 
@@ -134,12 +154,15 @@ a complete audit trail.
 ## Summary
 
 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.
+platform. It aggregates both container-based MCPServer resources and remote
+MCPRemoteProxy backends into a single endpoint. 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 vMCP](../guides-vmcp/intro.mdx)
 - [Configure authentication](../guides-vmcp/authentication.mdx)
 - [Tool aggregation and conflict resolution](../guides-vmcp/tool-aggregation.mdx)
 - [Composite tools and workflows](../guides-vmcp/composite-tools.mdx)
+- [Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx)

docs/toolhive/guides-k8s/remote-mcp-proxy.mdx

@@ -641,6 +641,65 @@ spec:
 
 See [Telemetry and metrics](./telemetry-and-metrics.mdx) for more information.
 
+## Use with Virtual MCP Server
+
+MCPRemoteProxy resources can be added to an MCPGroup and discovered by a
+VirtualMCPServer, enabling you to combine remote MCP servers with local
+container-based MCPServer resources into a single unified endpoint.
+
+:::caution Current limitation
+
+vMCP can discover MCPRemoteProxy backends in a group, but authentication between
+vMCP and MCPRemoteProxy is not yet fully implemented. Since MCPRemoteProxy
+requires `oidcConfig` to validate incoming requests, and vMCP does not currently
+forward authentication tokens to backends, vMCP cannot communicate with
+MCPRemoteProxy backends that require authentication.
+
+This limitation will be addressed in a future release. For now, MCPRemoteProxy
+works best when accessed directly by clients rather than through vMCP aggregation.
+
+:::
+
+### Add remote proxy to a group
+
+To include a remote proxy in an MCPGroup for future vMCP aggregation, add the
+`groupRef` field to your MCPRemoteProxy spec:
+
+```yaml
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPRemoteProxy
+metadata:
+  name: context7-proxy
+  namespace: toolhive-system
+spec:
+  groupRef: my-group # Reference to an MCPGroup
+  remoteURL: https://mcp.context7.com/mcp
+  transport: streamable-http
+  port: 8080
+  oidcConfig:
+    type: inline
+    inline:
+      issuer: https://auth.company.com
+      audience: context7-proxy
+```
+
+### Planned benefits of vMCP aggregation
+
+When vMCP authentication to MCPRemoteProxy is implemented, the following
+benefits will be available:
+
+- **Unified endpoint**: Clients connect to one vMCP URL instead of multiple
+  proxy endpoints
+- **Centralized authentication**: vMCP handles client authentication at the
+  entry point
+- **Tool namespacing**: Tools from remote proxies are automatically prefixed to
+  avoid conflicts with local MCP servers
+- **Unified toolset**: Combine tools from container-based servers and external
+  SaaS MCP services
+
+See [Configure vMCP servers](../guides-vmcp/configuration.mdx) for more vMCP
+configuration options.
+
 ## Next steps
 
 See the [Client compatibility](../reference/client-compatibility.mdx) reference

docs/toolhive/guides-vmcp/configuration.mdx

@@ -11,8 +11,8 @@ VirtualMCPServer resource. For a complete field reference, see the
 
 Before creating a VirtualMCPServer, you need an
 [MCPGroup](../reference/crd-spec.mdx#mcpgroup) to organize the backend MCP
-servers. An MCPGroup is a logical container that groups related MCPServer
-resources together.
+servers. An MCPGroup is a logical container that groups related MCPServer and
+MCPRemoteProxy resources together.
 
 Create a basic MCPGroup:
 
@@ -27,8 +27,66 @@ spec:
 ```
 
 The MCPGroup must exist in the same namespace as your VirtualMCPServer and be in
-a Ready state before the VirtualMCPServer can start. Backend MCPServers
-reference this group using the `groupRef` field in their spec.
+a Ready state before the VirtualMCPServer can start. Backend resources reference
+this group using the `groupRef` field in their spec.
+
+## Add backends to a group
+
+vMCP supports two types of backends that can be added to an MCPGroup:
+
+### MCPServer (local containers)
+
+MCPServer resources run container-based MCP servers in your cluster:
+
+```yaml
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPServer
+metadata:
+  name: fetch
+  namespace: toolhive-system
+spec:
+  groupRef: my-group # Reference to the MCPGroup
+  image: ghcr.io/stackloklabs/gofetch/server
+  transport: streamable-http
+```
+
+### MCPRemoteProxy (remote servers)
+
+MCPRemoteProxy resources proxy external remote MCP servers. They can be added to
+an MCPGroup for discovery by vMCP:
+
+```yaml
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPRemoteProxy
+metadata:
+  name: context7-proxy
+  namespace: toolhive-system
+spec:
+  groupRef: my-group # Reference to the MCPGroup
+  remoteURL: https://mcp.context7.com/mcp
+  transport: streamable-http
+  port: 8080
+
+  # Validate incoming requests
+  oidcConfig:
+    type: inline
+    inline:
+      issuer: https://auth.company.com
+      audience: context7-proxy
+```
+
+:::caution Current limitation
+
+vMCP can discover MCPRemoteProxy backends in a group, but authentication between
+vMCP and MCPRemoteProxy is not yet fully implemented. This limitation will be
+addressed in a future release. See
+[Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx#use-with-virtual-mcp-server)
+for details.
+
+:::
+
+For complete MCPRemoteProxy configuration options, see
+[Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx).
 
 ## Create a VirtualMCPServer
 
@@ -49,7 +107,8 @@ spec:
 ```
 
 The MCPGroup must exist in the same namespace and be in a Ready state before the
-VirtualMCPServer can start.
+VirtualMCPServer can start. The VirtualMCPServer automatically discovers and
+aggregates all MCPServer and MCPRemoteProxy resources in the group.
 
 ## Configure authentication
 
@@ -110,3 +169,4 @@ feature in the ToolHive Registry Server.
 - [Introduction to vMCP](./intro.mdx)
 - [Tool aggregation](./tool-aggregation.mdx)
 - [Authentication](./authentication.mdx)
+- [Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx)

docs/toolhive/guides-vmcp/intro.mdx

@@ -11,9 +11,26 @@ single unified interface. Instead of configuring clients to connect to each MCP
 server individually, you connect once to vMCP and access all backend tools
 through a single endpoint.
 
+vMCP supports two types of backends:
+
+- **MCPServer**: Container-based MCP servers running in your cluster
+- **MCPRemoteProxy**: Proxies to external remote MCP servers (such as Notion,
+  analytics platforms, or other SaaS MCP endpoints)
+
+:::note MCPRemoteProxy support
+
+vMCP can discover MCPRemoteProxy backends in a group, but authentication between
+vMCP and MCPRemoteProxy is not yet fully implemented. MCPServer backends work
+fully with vMCP. See
+[Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx#use-with-virtual-mcp-server)
+for details on the current limitations.
+
+:::
+
 ## Core capabilities
 
-- **Multi-server aggregation**: Connect to one endpoint instead of many
+- **Multi-server aggregation**: Connect to one endpoint instead of many,
+  including both local container-based servers and remote MCP proxies
 - **Tool conflict resolution**: Automatic namespacing when backend MCP servers
   have overlapping tool names
 - **Centralized authentication**: Single sign-on with per-backend token exchange
@@ -24,10 +41,11 @@ through a single endpoint.
 
 ### Good fit
 
-- You manage 5+ MCP servers
+- You manage 5+ MCP servers (local or remote)
 - You need cross-system workflows requiring coordination
 - You have centralized authentication and authorization requirements
 - You need reusable workflow definitions
+- You want to aggregate external SaaS MCP servers with internal tools
 
 ### Not needed
 
@@ -41,28 +59,36 @@ through a single endpoint.
 flowchart TB
     Client[MCP Client] --> vMCP[Virtual MCP Server]
 
-    subgraph Backends[Backend MCP Servers]
+    subgraph LocalBackends[Local MCP Servers]
         GitHub[GitHub MCP]
-        Jira[Jira MCP]
         Fetch[Fetch MCP]
     end
 
-    vMCP --> GitHub
-    vMCP --> Jira
-    vMCP --> Fetch
+    subgraph RemoteBackends[Remote MCP Proxies]
+        Notion[Notion MCP]
+        Neon[Neon MCP]
+    end
+
+    vMCP --> LocalBackends
+    vMCP --> RemoteBackends
+
+    RemoteBackends -->|proxied| ExternalServices[External Services]
 ```
 
 ## How it works
 
 1. You define an MCPGroup (a resource that organizes related MCP servers)
-   containing your backend MCPServer resources
-2. You create a VirtualMCPServer that references the group
-3. The operator discovers all backend MCP servers in the group and aggregates
-   their capabilities
-4. Clients connect to the VirtualMCPServer endpoint and see a unified view of
-   all tools
+2. Backend resources reference the group using `groupRef`:
+   - **MCPServer** resources for container-based MCP servers
+   - **MCPRemoteProxy** resources for external remote MCP servers
+3. You create a VirtualMCPServer that references the group
+4. The operator discovers all MCPServer and MCPRemoteProxy backends in the group
+   and aggregates their capabilities
+5. Clients connect to the VirtualMCPServer endpoint and see a unified view of
+   all tools from both local and remote backends
 
 ## Related information
 
 - [Understanding Virtual MCP Server](../concepts/vmcp.mdx)
 - [Quickstart: Virtual MCP Server](../tutorials/quickstart-vmcp.mdx)
+- [Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx)