diff --git a/docs/toolhive/concepts/vmcp.mdx b/docs/toolhive/concepts/vmcp.mdx index b3287f55..40b0894a 100644 --- a/docs/toolhive/concepts/vmcp.mdx +++ b/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,8 +154,10 @@ 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 @@ -143,3 +165,4 @@ approval gates, making it valuable for teams managing multiple MCP servers. - [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) diff --git a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx b/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx index b179074a..1063f0d7 100644 --- a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx +++ b/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 diff --git a/docs/toolhive/guides-vmcp/configuration.mdx b/docs/toolhive/guides-vmcp/configuration.mdx index 5480a04b..317755ce 100644 --- a/docs/toolhive/guides-vmcp/configuration.mdx +++ b/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) diff --git a/docs/toolhive/guides-vmcp/intro.mdx b/docs/toolhive/guides-vmcp/intro.mdx index d36eb8b5..77e5e438 100644 --- a/docs/toolhive/guides-vmcp/intro.mdx +++ b/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)