MCP multi cluster configuration (proto)

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

extensions.clusters.mcp_multicluster.v3.ClusterConfig

[extensions.clusters.mcp_multicluster.v3.ClusterConfig proto]

Configuration for the MCP multi cluster. See the architecture overview for more information. This cluster type allows aggregation of multiple clusters into one, providing metadata with the list of aggregated clusters. Use the attemptCount property of the request StreamInfo object to select host in a specific subcluster. If the attemptCount value is greater than the number of aggregated clusters, the host selection will fail.

The primary purpose of this cluster extension is to provide the list of servers for the MCP router configured for tool and resource aggregation. For details of how tools and resource are aggregated see MCP router documentation.

Example configuration:

name: mcp_multicluster
connect_timeout: 0.25s
lb_policy: CLUSTER_PROVIDED
cluster_type:
  name: envoy.clusters.mcp_multicluster
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.clusters.mcp_multicluster.v3.ClusterConfig
    servers:
    - name: build_tools
      mcp_cluster:
        cluster: build_tools
    - name: review_tools
       mcp_cluster:
         cluster: review_tools
         host_rewrite_literal: "mcp.review_tools.acme.com"

This extension has the qualified name envoy.clusters.mcp_multicluster

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension is not hardened and should only be used in deployments where both the downstream and upstream are trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.clusters

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.extensions.clusters.mcp_multicluster.v3.ClusterConfig

{
  "servers": []
}

servers: (repeated extensions.clusters.mcp_multicluster.v3.ClusterConfig.McpBackend, REQUIRED) A list of remote MCP servers. Based on the MCP multi cluster configuration the MCP router aggregates capabilities, tools and resources from remote MCP servers and presents itself as single MCP server to the client. All remote MCP servers are sent the same capabilities that the client presented to Envoy. MCP router prefixes tool names and resource path with the server name to resolve naming collisions.

extensions.clusters.mcp_multicluster.v3.ClusterConfig.McpCluster

[extensions.clusters.mcp_multicluster.v3.ClusterConfig.McpCluster proto]

Cluster-based backend configuration.

{
  "cluster": ...,
  "path": ...,
  "timeout": {...},
  "host_rewrite_literal": ...
}

cluster: (string, REQUIRED) Cluster name to route requests to.

path: (string) Path to use for MCP requests. Defaults to “/mcp”.

timeout: (Duration) Request timeout. If not set, uses cluster’s timeout configuration.

host_rewrite_literal: (string) Indicates that during forwarding, the host header will be swapped with this value.

extensions.clusters.mcp_multicluster.v3.ClusterConfig.McpBackend

[extensions.clusters.mcp_multicluster.v3.ClusterConfig.McpBackend proto]

Specification of the MCP server.

{
  "name": ...,
  "mcp_cluster": {...}
}

name: (string) Unique name for this backend. Used for: - Tool name prefixing (e.g., “time__get_current_time”) - Session ID composition - Logging and error messages. Default will be the cluster name if not specified.

mcp_cluster: (extensions.clusters.mcp_multicluster.v3.ClusterConfig.McpCluster) Backend target specification.