MCP (proto)

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

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:

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

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.

MCP filter configuration overview.

extensions.filters.http.mcp.v3.Mcp

[extensions.filters.http.mcp.v3.Mcp proto]

This filter will inspect and get attributes from MCP traffic.

{
  "traffic_mode": ...,
  "clear_route_cache": ...,
  "max_request_body_size": {...},
  "parser_config": {...}
}
traffic_mode

(extensions.filters.http.mcp.v3.Mcp.TrafficMode) Configures how the filter handles non-MCP traffic.

clear_route_cache

(bool) When set to true, the filter will clear the route cache after setting dynamic metadata. This allows the route to be re-selected based on the MCP metadata (e.g., method, params). Defaults to false.

max_request_body_size

(UInt32Value) Maximum size of the request body to buffer for JSON-RPC validation. If the request body exceeds this size, the request is rejected with 413 Payload Too Large. This limit applies to both REJECT_NO_MCP and PASS_THROUGH modes to prevent unbounded buffering.

It defaults to 8KB (8192 bytes) and the maximum allowed value is 10MB (10485760 bytes).

Setting it to 0 would disable the limit. It is not recommended to do so in production.

parser_config

(extensions.filters.http.mcp.v3.ParserConfig) Parser configuration, this provide the attribute extraction override.

Enum extensions.filters.http.mcp.v3.Mcp.TrafficMode

[extensions.filters.http.mcp.v3.Mcp.TrafficMode proto]

Traffic handling mode for non-MCP traffic.

PASS_THROUGH

(DEFAULT) ⁣Proxies the HTTP request and response without MCP spec check. This is the default mode.

REJECT_NO_MCP

⁣Reject requests that are not following MCP spec. Valid MCP requests are: - POST requests with JSON-RPC 2.0 messages - GET requests for SSE streams (with Accept: text/event-stream)

extensions.filters.http.mcp.v3.ParserConfig

[extensions.filters.http.mcp.v3.ParserConfig proto]

Parser configuration with method-specific rules. This configuration allows overriding the default attribute extraction behavior for specific MCP methods.

{
  "methods": []
}
methods

(repeated extensions.filters.http.mcp.v3.ParserConfig.MethodConfig) Method-specific configurations. These rules override or supplement the default extraction logic for the specified methods.

extensions.filters.http.mcp.v3.ParserConfig.AttributeExtractionRule

[extensions.filters.http.mcp.v3.ParserConfig.AttributeExtractionRule proto]

A single attribute extraction rule.

{
  "path": ...
}
path

(string, REQUIRED) JSON path to extract (e.g., “params.name”, “params.uri”). The path is a dot-separated string representing the location of the field in the JSON payload. For example, “params.name” extracts the “name” field from the “params” object.

extensions.filters.http.mcp.v3.ParserConfig.MethodConfig

[extensions.filters.http.mcp.v3.ParserConfig.MethodConfig proto]

Configuration for a specific MCP method.

{
  "method": ...,
  "extraction_rules": []
}
method

(string, REQUIRED) Method name (e.g., “tools/call”, “resources/read”, “initialize”). This matches the “method” field in the JSON-RPC request.

extraction_rules

(repeated extensions.filters.http.mcp.v3.ParserConfig.AttributeExtractionRule) Attributes to extract for this method. If empty, no attributes will be extracted for this method beyond the default ones (jsonrpc, method).

extensions.filters.http.mcp.v3.McpOverride

[extensions.filters.http.mcp.v3.McpOverride proto]

Per-route override configuration for MCP filter

{
  "traffic_mode": ...,
  "max_request_body_size": {...}
}
traffic_mode

(extensions.filters.http.mcp.v3.Mcp.TrafficMode) Optional per-route traffic mode override

max_request_body_size

(UInt32Value) Optional per-route max request body size override. When set, this overrides the global max_request_body_size for this route. It defaults to 8KB (8192 bytes) and the maximum allowed value is 10MB (10485760 bytes).