diff --git a/docs/toolhive/concepts/vmcp.mdx b/docs/toolhive/concepts/vmcp.mdx index b3287f55..4878fef5 100644 --- a/docs/toolhive/concepts/vmcp.mdx +++ b/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 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 +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,8 +146,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 +157,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..0c0e4abf 100644 --- a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx +++ b/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 diff --git a/docs/toolhive/guides-vmcp/configuration.mdx b/docs/toolhive/guides-vmcp/configuration.mdx index 5480a04b..19a4c52a 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,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) diff --git a/docs/toolhive/guides-vmcp/intro.mdx b/docs/toolhive/guides-vmcp/intro.mdx index d36eb8b5..36b4354e 100644 --- a/docs/toolhive/guides-vmcp/intro.mdx +++ b/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 @@ -41,28 +49,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)