MCP Multiplexer/Demultiplexer (proto)

This extension has the qualified name envoy.filters.http.mcp_router

Note

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

This extension has an unknown security posture 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.filters.http

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

type.googleapis.com/envoy.extensions.filters.http.mcp_router.v3.McpRouter

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.

Configuration for the MCP Multiplexer/Demultiplexer.

This extension aggregates capabilities, tools and resources of remote MCP servers and presents Envoy as a singe MCP server to the client. This allows a unified policy to be applied to multiple remote servers and abstracts multiple MCP servers as a single one.

This filter must be a terminal filter in the filter chain and replaces the HTTP router filter.

Not all route level policies are applicable to this filter. Specifically the following policies are ignored: * route * redirect * direct_response

extensions.filters.http.mcp_router.v3.HeaderSource

[extensions.filters.http.mcp_router.v3.HeaderSource proto]

Extract identity from a request header.

{
  "name": ...
}

name: (string, REQUIRED) Header name to extract (e.g., “x-user-identity”).

extensions.filters.http.mcp_router.v3.DynamicMetadataSource

[extensions.filters.http.mcp_router.v3.DynamicMetadataSource proto]

Extract identity from dynamic metadata (e.g., populated by JWT or ext_authz filter).

{
  "key": {...}
}

key: (type.metadata.v3.MetadataKey, REQUIRED) The metadata key to retrieve the value from.

extensions.filters.http.mcp_router.v3.IdentityExtractor

[extensions.filters.http.mcp_router.v3.IdentityExtractor proto]

Defines how the identity (user/principal) is extracted from the request. Exactly one of header or dynamic_metadata must be set.

{
  "header": {...},
  "dynamic_metadata": {...}
}

header: (extensions.filters.http.mcp_router.v3.HeaderSource) Extract identity from a request header.

dynamic_metadata: (extensions.filters.http.mcp_router.v3.DynamicMetadataSource) Extract identity from dynamic metadata.

extensions.filters.http.mcp_router.v3.ValidationPolicy

[extensions.filters.http.mcp_router.v3.ValidationPolicy proto]

Specifies how to handle requests where the identity is missing or mismatched.

{
  "mode": ...
}

mode: (extensions.filters.http.mcp_router.v3.ValidationPolicy.Mode)

Enum extensions.filters.http.mcp_router.v3.ValidationPolicy.Mode

[extensions.filters.http.mcp_router.v3.ValidationPolicy.Mode proto]

MODE_UNSPECIFIED: (DEFAULT) ⁣Not specified. Defaults to DISABLED behavior.

DISABLED: ⁣Bind identity on Initialize if present, but do not validate subsequent requests. If extraction fails, the session proceeds anonymously.

ENFORCE: ⁣Reject the request (403) if the identity cannot be extracted or if the session identity does not match the request identity.

extensions.filters.http.mcp_router.v3.SessionIdentity

[extensions.filters.http.mcp_router.v3.SessionIdentity proto]

Session identity configuration.

{
  "identity": {...},
  "validation": {...}
}

identity: (extensions.filters.http.mcp_router.v3.IdentityExtractor, REQUIRED) Defines how the identity (user/principal) is extracted from the request.

validation: (extensions.filters.http.mcp_router.v3.ValidationPolicy) Specifies how to handle requests where the subject is missing or invalid. Defaults to DISABLED.

extensions.filters.http.mcp_router.v3.McpRouter

[extensions.filters.http.mcp_router.v3.McpRouter proto]

{
  "servers": [],
  "session_identity": {...}
}

servers: (repeated extensions.filters.http.mcp_router.v3.McpRouter.McpBackend) A list of remote MCP servers. 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.

session_identity: (extensions.filters.http.mcp_router.v3.SessionIdentity) If set, extracts a request “subject” and binds it into the MCP session. If not set, sessions are created without identity binding.

extensions.filters.http.mcp_router.v3.McpRouter.McpBackend

[extensions.filters.http.mcp_router.v3.McpRouter.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.filters.http.mcp_router.v3.McpRouter.McpCluster) Backend target specification.

extensions.filters.http.mcp_router.v3.McpRouter.McpCluster

[extensions.filters.http.mcp_router.v3.McpRouter.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.