From 11a65a9bb676eb8f32e5012ee4f04cbae4ab255d Mon Sep 17 00:00:00 2001 From: amirejaz Date: Thu, 18 Dec 2025 16:04:33 +0000 Subject: [PATCH 1/4] document vMCP support for MCPRemoteProxy backends --- docs/toolhive/concepts/vmcp.mdx | 27 ++++- docs/toolhive/guides-k8s/remote-mcp-proxy.mdx | 109 ++++++++++++++++++ docs/toolhive/guides-vmcp/configuration.mdx | 60 +++++++++- docs/toolhive/guides-vmcp/intro.mdx | 49 +++++--- 4 files changed, 217 insertions(+), 28 deletions(-) diff --git a/docs/toolhive/concepts/vmcp.mdx b/docs/toolhive/concepts/vmcp.mdx index b3287f55..797bd570 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 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,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..6d3adeaf 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 @@ -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) From 9d9a221cd2f793cef0e215606c4d608d9507074e Mon Sep 17 00:00:00 2001 From: amirejaz Date: Thu, 18 Dec 2025 16:31:35 +0000 Subject: [PATCH 2/4] fix copilot feedback --- docs/toolhive/concepts/vmcp.mdx | 10 +++++----- docs/toolhive/guides-vmcp/intro.mdx | 11 ++++++----- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/toolhive/concepts/vmcp.mdx b/docs/toolhive/concepts/vmcp.mdx index 797bd570..4878fef5 100644 --- a/docs/toolhive/concepts/vmcp.mdx +++ b/docs/toolhive/concepts/vmcp.mdx @@ -51,11 +51,11 @@ 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). 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. +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: diff --git a/docs/toolhive/guides-vmcp/intro.mdx b/docs/toolhive/guides-vmcp/intro.mdx index 6d3adeaf..36b4354e 100644 --- a/docs/toolhive/guides-vmcp/intro.mdx +++ b/docs/toolhive/guides-vmcp/intro.mdx @@ -45,7 +45,9 @@ vMCP supports two types of backends: ## Architecture overview -\`\`\`mermaid flowchart TB Client[MCP Client] --> vMCP[Virtual MCP Server] +```mermaid +flowchart TB + Client[MCP Client] --> vMCP[Virtual MCP Server] subgraph LocalBackends[Local MCP Servers] GitHub[GitHub MCP] @@ -54,20 +56,19 @@ vMCP supports two types of backends: subgraph RemoteBackends[Remote MCP Proxies] Notion[Notion MCP] - Github-Remote[Github Remote 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) -2. Backend resources reference the group using \`groupRef\`: +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 From 48ba98325ffe7fc70100f0b0a4c00c37275230ae Mon Sep 17 00:00:00 2001 From: amirejaz Date: Fri, 16 Jan 2026 14:20:26 +0000 Subject: [PATCH 3/4] fix: update vMCP + MCPRemoteProxy docs for accurate auth flow Address reviewer feedback: - Replace fictional "analytics-proxy" with "context7-proxy" (real MCP server) - Add section on authenticating to upstream servers using headerInjection - Clarify that oidcConfig validates incoming requests (not a token vMCP sends) - Remove misleading claim about "forwarded tokens" - Use kubernetes oidcConfig type for in-cluster vMCP communication - Add externalAuthConfigRef example for upstream authentication --- docs/toolhive/guides-k8s/remote-mcp-proxy.mdx | 78 +++++++++++++++---- docs/toolhive/guides-vmcp/configuration.mdx | 21 ++--- 2 files changed, 74 insertions(+), 25 deletions(-) diff --git a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx b/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx index 0c0e4abf..d8987706 100644 --- a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx +++ b/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx @@ -656,18 +656,15 @@ MCPRemoteProxy spec: apiVersion: toolhive.stacklok.dev/v1alpha1 kind: MCPRemoteProxy metadata: - name: analytics-proxy + name: context7-proxy namespace: toolhive-system spec: groupRef: my-group # Reference to an MCPGroup - remoteURL: https://mcp.analytics.example.com + remoteURL: https://mcp.context7.com/mcp transport: streamable-http port: 8080 oidcConfig: - type: inline - inline: - issuer: https://auth.company.com/realms/production - audience: analytics-proxy + type: kubernetes # Use Kubernetes service account for in-cluster auth ``` ### Benefits of vMCP aggregation @@ -676,17 +673,69 @@ 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 +- **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 +### Authenticate to upstream remote servers + +When the upstream remote MCP server requires authentication (such as an API key +or bearer token), use `externalAuthConfigRef` with header injection to provide +credentials: + +```yaml +# Secret containing the API token +apiVersion: v1 +kind: Secret +metadata: + name: context7-api-token + namespace: toolhive-system +type: Opaque +stringData: + token: "Bearer your-api-token-here" +--- +# MCPExternalAuthConfig for header injection +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPExternalAuthConfig +metadata: + name: context7-auth + namespace: toolhive-system +spec: + type: headerInjection + headerInjection: + headerName: Authorization + valueSecretRef: + name: context7-api-token + key: token +--- +# MCPRemoteProxy with upstream authentication +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRemoteProxy +metadata: + name: context7-proxy + namespace: toolhive-system +spec: + groupRef: dev-tools + remoteURL: https://mcp.context7.com/mcp + transport: streamable-http + port: 8080 + oidcConfig: + type: kubernetes + externalAuthConfigRef: + name: context7-auth # Injects the token when calling the upstream server +``` + +The `externalAuthConfigRef` configures how the proxy authenticates to the +upstream remote server. The `oidcConfig` configures how the proxy validates +incoming requests from clients (including vMCP). + ### Complete example This example creates a vMCP that aggregates a local Fetch server with a remote -analytics proxy: +MCP proxy: ```yaml # 1. Create the group @@ -713,18 +762,15 @@ spec: apiVersion: toolhive.stacklok.dev/v1alpha1 kind: MCPRemoteProxy metadata: - name: analytics-proxy + name: context7-proxy namespace: toolhive-system spec: groupRef: dev-tools - remoteURL: https://mcp.analytics.example.com + remoteURL: https://mcp.context7.com/mcp transport: streamable-http port: 8080 oidcConfig: - type: inline - inline: - issuer: https://auth.company.com - audience: analytics-proxy + type: kubernetes # Validates requests using Kubernetes service accounts --- # 4. Virtual MCP Server apiVersion: toolhive.stacklok.dev/v1alpha1 @@ -745,7 +791,7 @@ spec: ``` Clients connect to the VirtualMCPServer endpoint and see tools from both the -local Fetch server and the remote analytics proxy. +local Fetch server and the remote Context7 proxy. See [Configure vMCP servers](../guides-vmcp/configuration.mdx) for more vMCP configuration options. diff --git a/docs/toolhive/guides-vmcp/configuration.mdx b/docs/toolhive/guides-vmcp/configuration.mdx index 19a4c52a..49293abd 100644 --- a/docs/toolhive/guides-vmcp/configuration.mdx +++ b/docs/toolhive/guides-vmcp/configuration.mdx @@ -59,24 +59,27 @@ include SaaS MCP endpoints in your vMCP aggregation: apiVersion: toolhive.stacklok.dev/v1alpha1 kind: MCPRemoteProxy metadata: - name: analytics-proxy + name: context7-proxy namespace: toolhive-system spec: groupRef: my-group # Reference to the MCPGroup - remoteURL: https://mcp.analytics.example.com + remoteURL: https://mcp.context7.com/mcp transport: streamable-http port: 8080 - # OIDC authentication for incoming requests + # Validate incoming requests using Kubernetes service accounts oidcConfig: - type: inline - inline: - issuer: https://auth.company.com/realms/production - audience: analytics-proxy + type: kubernetes ``` -For complete MCPRemoteProxy configuration options, see -[Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx). +The `oidcConfig` field configures how the proxy validates incoming requests. When +using `type: kubernetes`, the proxy trusts requests authenticated via Kubernetes +service accounts, which is suitable for in-cluster communication with vMCP. + +If the upstream remote server requires authentication, use `externalAuthConfigRef` +to configure credentials. See +[Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx#authenticate-to-upstream-remote-servers) +for examples. ## Create a VirtualMCPServer From e990ffc768a2e7a53fd8a2d910b21d2f5693f01f Mon Sep 17 00:00:00 2001 From: amirejaz Date: Fri, 16 Jan 2026 14:49:01 +0000 Subject: [PATCH 4/4] docs: add limitation notes for vMCP + MCPRemoteProxy auth Document the current limitation where vMCP can discover MCPRemoteProxy backends but cannot authenticate to them because: - MCPRemoteProxy requires oidcConfig to validate incoming requests - vMCP does not yet forward authentication tokens to backends Changes: - Add caution callouts explaining the limitation - Remove misleading complete examples that suggest full functionality - Simplify the "Use with Virtual MCP Server" section - Note that this will be addressed in a future release --- docs/toolhive/concepts/vmcp.mdx | 12 +- docs/toolhive/guides-k8s/remote-mcp-proxy.mdx | 142 +++--------------- docs/toolhive/guides-vmcp/configuration.mdx | 29 ++-- docs/toolhive/guides-vmcp/intro.mdx | 10 ++ 4 files changed, 61 insertions(+), 132 deletions(-) diff --git a/docs/toolhive/concepts/vmcp.mdx b/docs/toolhive/concepts/vmcp.mdx index 4878fef5..40b0894a 100644 --- a/docs/toolhive/concepts/vmcp.mdx +++ b/docs/toolhive/concepts/vmcp.mdx @@ -46,8 +46,16 @@ vMCP supports two types of backends: - **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. +:::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 diff --git a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx b/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx index d8987706..1063f0d7 100644 --- a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx +++ b/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx @@ -643,14 +643,27 @@ 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 +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 vMCP aggregation, add the `groupRef` field to your -MCPRemoteProxy spec: +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 @@ -664,12 +677,16 @@ spec: transport: streamable-http port: 8080 oidcConfig: - type: kubernetes # Use Kubernetes service account for in-cluster auth + type: inline + inline: + issuer: https://auth.company.com + audience: context7-proxy ``` -### Benefits of vMCP aggregation +### Planned benefits of vMCP aggregation -When remote proxies are part of a vMCP group: +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 @@ -680,119 +697,6 @@ When remote proxies are part of a vMCP group: - **Unified toolset**: Combine tools from container-based servers and external SaaS MCP services -### Authenticate to upstream remote servers - -When the upstream remote MCP server requires authentication (such as an API key -or bearer token), use `externalAuthConfigRef` with header injection to provide -credentials: - -```yaml -# Secret containing the API token -apiVersion: v1 -kind: Secret -metadata: - name: context7-api-token - namespace: toolhive-system -type: Opaque -stringData: - token: "Bearer your-api-token-here" ---- -# MCPExternalAuthConfig for header injection -apiVersion: toolhive.stacklok.dev/v1alpha1 -kind: MCPExternalAuthConfig -metadata: - name: context7-auth - namespace: toolhive-system -spec: - type: headerInjection - headerInjection: - headerName: Authorization - valueSecretRef: - name: context7-api-token - key: token ---- -# MCPRemoteProxy with upstream authentication -apiVersion: toolhive.stacklok.dev/v1alpha1 -kind: MCPRemoteProxy -metadata: - name: context7-proxy - namespace: toolhive-system -spec: - groupRef: dev-tools - remoteURL: https://mcp.context7.com/mcp - transport: streamable-http - port: 8080 - oidcConfig: - type: kubernetes - externalAuthConfigRef: - name: context7-auth # Injects the token when calling the upstream server -``` - -The `externalAuthConfigRef` configures how the proxy authenticates to the -upstream remote server. The `oidcConfig` configures how the proxy validates -incoming requests from clients (including vMCP). - -### Complete example - -This example creates a vMCP that aggregates a local Fetch server with a remote -MCP 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: context7-proxy - namespace: toolhive-system -spec: - groupRef: dev-tools - remoteURL: https://mcp.context7.com/mcp - transport: streamable-http - port: 8080 - oidcConfig: - type: kubernetes # Validates requests using Kubernetes service accounts ---- -# 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 Context7 proxy. - See [Configure vMCP servers](../guides-vmcp/configuration.mdx) for more vMCP configuration options. diff --git a/docs/toolhive/guides-vmcp/configuration.mdx b/docs/toolhive/guides-vmcp/configuration.mdx index 49293abd..317755ce 100644 --- a/docs/toolhive/guides-vmcp/configuration.mdx +++ b/docs/toolhive/guides-vmcp/configuration.mdx @@ -52,8 +52,8 @@ spec: ### MCPRemoteProxy (remote servers) -MCPRemoteProxy resources proxy external remote MCP servers, allowing you to -include SaaS MCP endpoints in your vMCP aggregation: +MCPRemoteProxy resources proxy external remote MCP servers. They can be added to +an MCPGroup for discovery by vMCP: ```yaml apiVersion: toolhive.stacklok.dev/v1alpha1 @@ -67,19 +67,26 @@ spec: transport: streamable-http port: 8080 - # Validate incoming requests using Kubernetes service accounts + # Validate incoming requests oidcConfig: - type: kubernetes + type: inline + inline: + issuer: https://auth.company.com + audience: context7-proxy ``` -The `oidcConfig` field configures how the proxy validates incoming requests. When -using `type: kubernetes`, the proxy trusts requests authenticated via Kubernetes -service accounts, which is suitable for in-cluster communication with vMCP. +:::caution Current limitation -If the upstream remote server requires authentication, use `externalAuthConfigRef` -to configure credentials. See -[Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx#authenticate-to-upstream-remote-servers) -for examples. +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 diff --git a/docs/toolhive/guides-vmcp/intro.mdx b/docs/toolhive/guides-vmcp/intro.mdx index 36b4354e..77e5e438 100644 --- a/docs/toolhive/guides-vmcp/intro.mdx +++ b/docs/toolhive/guides-vmcp/intro.mdx @@ -17,6 +17,16 @@ vMCP supports two types of backends: - **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,