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.HeaderForwarding

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

Specifies which downstream request headers are allowed to be forwarded to an MCP backend. Modeled after ext_proc’s HeaderForwardingRules, but MCP-local and secure-by-default: unlike ext_proc, an unset/empty policy forwards nothing rather than everything, because MCP requires audience-bound tokens and prohibits implicit token passthrough between a client and a backend it did not authenticate to.

Evaluation order per header:

If the header matches disallowed_headers, it is never forwarded — this takes precedence over everything below, including forward_all.

Otherwise, if forward_all is true, the header is forwarded.

Otherwise, if the header matches allowed_headers, it is forwarded.

Otherwise, the header is not forwarded.

This does not cover header mutation or credential injection, which remain a separate concern from this policy.

{
  "forward_all": ...,
  "allowed_headers": {...},
  "disallowed_headers": {...}
}

forward_all: (bool) If true, forward all downstream request headers to this backend (subject to disallowed_headers above), matching the legacy forward-everything behavior. Defaults to false. Users relying on the legacy behavior must set this explicitly.

allowed_headers: (type.matcher.v3.ListStringMatcher) If set, specifically allow any header in this list to be forwarded. Ignored for a header that also matches disallowed_headers, and redundant (but harmless) for any header covered by forward_all.

disallowed_headers: (type.matcher.v3.ListStringMatcher) If set, specifically disallow any header in this list from being forwarded. This takes precedence over both forward_all and allowed_headers.

extensions.clusters.mcp_multicluster.v3.ClusterConfig.McpBackend

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

Specification of the MCP server.

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

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.

header_forwarding: (extensions.clusters.mcp_multicluster.v3.ClusterConfig.HeaderForwarding) Controls which downstream request headers are forwarded to this backend. If not set, no downstream-controlled headers are forwarded beyond those the router itself must synthesize (e.g. content-type, accept, the session header) — in particular, a client’s authorization header is NOT forwarded by default. Router-owned, framing, session, and hop-by-hop headers are never affected by this policy; they are handled separately and can never be forwarded via this mechanism.