document vMCP remote server support

docs/toolhive/concepts/vmcp.mdx

@@ -40,11 +40,22 @@ 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)
+
+This means you can combine 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 MCPServers 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 +130,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 +146,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,115 @@ 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 aggregated by a
+VirtualMCPServer, enabling you to combine remote MCP servers with local
+container-based MCPServer resources into a single unified endpoint.
+
+### Add remote proxy to a group
+
+To include a remote proxy in vMCP aggregation, add the `groupRef` field to your
+MCPRemoteProxy spec:
+
+```yaml
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPRemoteProxy
+metadata:
+  name: analytics-proxy
+  namespace: toolhive-system
+spec:
+  groupRef: my-group # Reference to an MCPGroup
+  remoteURL: https://mcp.analytics.example.com
+  transport: streamable-http
+  port: 8080
+  oidcConfig:
+    type: inline
+    inline:
+      issuer: https://auth.company.com/realms/production
+      audience: analytics-proxy
+```
+
+### Benefits of vMCP aggregation
+
+When remote proxies are part of a vMCP group:
+
+- **Unified endpoint**: Clients connect to one vMCP URL instead of multiple
+  proxy endpoints
+- **Centralized authentication**: vMCP handles client authentication; remote
+  proxies validate the forwarded tokens
+- **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
+
+### Complete example
+
+This example creates a vMCP that aggregates a local Fetch server with a remote
+analytics proxy:
+
+```yaml
+# 1. Create the group
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPGroup
+metadata:
+  name: dev-tools
+  namespace: toolhive-system
+spec:
+  description: Development tools group
+---
+# 2. Local MCP Server
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPServer
+metadata:
+  name: fetch
+  namespace: toolhive-system
+spec:
+  groupRef: dev-tools
+  image: ghcr.io/stackloklabs/gofetch/server
+  transport: streamable-http
+---
+# 3. Remote MCP Proxy
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPRemoteProxy
+metadata:
+  name: analytics-proxy
+  namespace: toolhive-system
+spec:
+  groupRef: dev-tools
+  remoteURL: https://mcp.analytics.example.com
+  transport: streamable-http
+  port: 8080
+  oidcConfig:
+    type: inline
+    inline:
+      issuer: https://auth.company.com
+      audience: analytics-proxy
+---
+# 4. Virtual MCP Server
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: VirtualMCPServer
+metadata:
+  name: dev-vmcp
+  namespace: toolhive-system
+spec:
+  groupRef:
+    name: dev-tools
+  incomingAuth:
+    type: oidc
+    oidcConfig:
+      type: inline
+      inline:
+        issuer: https://auth.company.com
+        audience: dev-vmcp
+```
+
+Clients connect to the VirtualMCPServer endpoint and see tools from both the
+local Fetch server and the remote analytics proxy.
+
+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,56 @@ 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, allowing you to
+include SaaS MCP endpoints in your vMCP aggregation:
+
+```yaml
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPRemoteProxy
+metadata:
+  name: analytics-proxy
+  namespace: toolhive-system
+spec:
+  groupRef: my-group # Reference to the MCPGroup
+  remoteURL: https://mcp.analytics.example.com
+  transport: streamable-http
+  port: 8080
+
+  # OIDC authentication for incoming requests
+  oidcConfig:
+    type: inline
+    inline:
+      issuer: https://auth.company.com/realms/production
+      audience: analytics-proxy
+```
+
+For complete MCPRemoteProxy configuration options, see
+[Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx).
 
 ## Create a VirtualMCPServer
 
@@ -49,7 +97,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 +159,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,16 @@ 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)
+
 ## 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 +31,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
 
@@ -37,32 +45,39 @@ through a single endpoint.
 
 ## Architecture overview
 
-```mermaid
-flowchart TB
-    Client[MCP Client] --> vMCP[Virtual MCP Server]
+\`\`\`mermaid 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]
+        Github-Remote[Github Remote 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)