Model Context Protocol (MCP)

The MCP HTTP filter enables native Model Context Protocol support within Envoy.

  • This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.http.mcp.v3.Mcp.

  • v3 API reference

Attention

The MCP filter is actively under development.

This filter allows Envoy to function as an MCP gateway, enabling two deployment patterns:

Pass-Through MCP Gateway

Envoy’s primary role is a Policy Enforcement Point (PEP) for policies defined in either HTTP or MCP formats.

  • It supports Streamable-HTTP transport.

  • Service selection is handled via standard virtual host (vhost) / route configuration or through a dynamic forwarding proxy.

Aggregating MCP mode

Attention

This functionality is pending with the multi-route filter.

Envoy functions as a unified aggregating MCP server.

  • It combines the capabilities, tools, and resources of multiple backend MCP servers and presents them to clients as a single logical MCP server.

  • It supports Streamable-HTTP transport.

Key Capabilities

Within these patterns, the filter facilitates three essential functions:

  • MCP Policy Enforcement: Extracts MCP attributes to enforce fine-grained access control using either RBAC or an external authorization service.

  • MCP Observability: Extracts MCP attributes to populate dynamic metadata, which is then consumed by access logs or tracers for enhanced monitoring and debugging.

  • MCP Multiplexing and Aggregation: Acts as a unified endpoint that aggregates tools and resources originating from multiple backend services (Feature Pending).

MCP Policy Enforcement Examples

A common usage of the MCP filter is to enforce policies based on MCP payload attributes. The filter parses MCP JSON_RPC messages and populates the dynamic metadata, which subsequent filters in the chain can use for decision-making.

This enables scenarios such as:

  • Per-route Policy: Applying specific RBAC rules for different routes or MCP methods.

  • Egress Traffic Control: Using the filter with a dynamic forward proxy to secure outbound traffic for AI agents.

Integration with RBAC

To apply RBAC rules based on MCP attributes, place the MCP filter before the RBAC filter in the HTTP connection manager chain:

mcp-filter.yaml
78          - name: envoy.filters.http.mcp
79            typed_config:
80              '@type': type.googleapis.com/envoy.extensions.filters.http.mcp.v3.Mcp
81              traffic_mode: PASS_THROUGH
82          - name: envoy.filters.http.rbac
83            typed_config:
84              '@type': type.googleapis.com/envoy.extensions.filters.http.rbac.v3.RBAC

The RBAC filter is then configured with a per-route policy to match against the metadata extracted by the MCP filter:

mcp-filter.yaml
234                                allow-users-to-call-safe-tools:
235                                  permissions:
236                                  - and_rules:
237                                      rules:
238                                      - sourced_metadata:
239                                          metadata_matcher:
240                                            filter: mcp_proxy
241                                            path:
242                                            - key: method
243                                            value:
244                                              string_match:
245                                                exact: tools/call
246                                      - sourced_metadata:
247                                          metadata_matcher:
248                                            filter: mcp_proxy
249                                            path:
250                                            - key: params
251                                            - key: name
252                                            value:
253                                              string_match:
254                                                exact: get_weather
255                                  principals:
256                                  - any: true

Integration with External Authorization

The MCP filter can also function alongside the ext_authz filter. By default, the MCP filter exports metadata under the mcp_proxy namespace. An external authorization service can evaluate this metadata to approve or deny requests.

mcp-filter.yaml
85          # Example: ext_authz filter can consume MCP metadata
86          # - name: envoy.filters.http.ext_authz
87          #   typed_config:
88          #     '@type': type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
89          #     grpc_service:
90          #       envoy_grpc:
91          #         cluster_name: ext-authz
92          #     metadata_context_namespaces:
93          #     - mcp_proxy

Full Example

A complete example configuration is available for download: mcp-filter.yaml