十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Envoy MCP 过滤器新增 NOOP 流量模式:配置、实现原理与测试验证

Envoy MCP 过滤器新增 NOOP 流量模式:配置、实现原理与测试验证 Envoy MCP 过滤器新增 NOOP 流量模式配置、实现原理与测试验证【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy本文围绕 Envoy 仓库 changelog 条目 mcp__noop_mode.rstAdded aNOOPtraffic mode toMcpFilter展开深入剖析 Envoy MCP HTTP 过滤器Model Context Protocol Filter新增的NOOP流量模式它的语义定位、与既有PASS_THROUGH/REJECT_NO_MCP两种模式的差异、底层实现路径、全局与 per-route 两种配置方式以及仓库中对应的单元测试与集成测试验证。读完本文你将掌握如何在 Envoy 中通过traffic_mode: NOOP一键关闭 MCP 检查并理解该模式在灰度发布、性能兜底与按路由精细化管控中的实战用法。背景Enovy 的 MCP HTTP 过滤器是什么Model Context ProtocolMCP是 AI Agent 场景下客户端与工具/资源服务器之间通信的开放协议。Envoy 通过一个专用的 HTTP 过滤器原生支持 MCP 流量使 Envoy 可以作为 MCP 网关Gateway与策略执行点Policy Enforcement PointPEP工作。根据 mcp_filter.rst 的说明该过滤器承担三大核心职责MCP 策略执行解析 MCP 请求中的属性配合 RBAC 或外部授权服务ext_authz实现细粒度访问控制MCP 可观测性将解析出的 MCP 属性写入动态元数据dynamic metadata供访问日志或追踪器消费MCP 多路复用与聚合作为统一端点聚合多个后端 MCP 服务的能力、工具与资源该能力在文档中标注为 Pending。从源码结构看该过滤器由三个核心文件组成配置原型定义mcp.proto过滤器实现mcp_filter.h 与 mcp_filter.cc工厂注册config.cc通过REGISTER_FACTORY注册为envoy.filters.http.mcp。NOOP模式正是这一定位之下新增的流量处理开关它让运维人员可以在严格校验 MCP 规格与完全放行之间按需切换。TrafficMode 枚举三种流量模式的完整对照NOOP并非凭空新增而是与既有模式并列在Mcp消息的TrafficMode枚举中。完整的枚举定义位于 mcp.proto// Traffic handling mode for non-MCP traffic. enum TrafficMode { // Proxies the HTTP request and response without MCP spec check. // This is the default mode. PASS_THROUGH 0; // 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) // - DELETE requests for session termination (with MCP-Session-Id header) REJECT_NO_MCP 1; // Disables MCP processing entirely. The filter performs no inspection, // attribute extraction, trace context propagation, or rejection; all // traffic is proxied as-is. NOOP 2; }三种模式的核心差异可以用下表概括模式枚举值语义典型场景PASS_THROUGH0默认不做 MCP 规格校验按普通 HTTP 请求透传但仍会尽力解析属性默认兜底保证任何流量都能通过REJECT_NO_MCP1拒绝不符合 MCP 规格的请求非 JSON-RPC 2.0 POST、非 SSE GET、无 Session-Id 的 DELETE返回400 Bad Request强制 MCP 网关只放行合规 MCP 流量NOOP2完全禁用 MCP 处理不检查、不解析、不传播 trace context、不拒绝所有流量原样代理关闭 MCP 能力、性能兜底、按路由豁免注意PASS_THROUGH与NOOP的区别前者只是不校验过滤器仍然会缓冲并解析请求体、提取属性、写入动态元数据同时会受max_request_body_size限制后者则是完全不介入过滤器在解码请求头阶段就直接放行请求体处理、属性提取、trace context/baggage 传播全部跳过。NOOP 模式的实现原理请求头阶段的短路路径NOOP的底层实现非常简洁也最能体现其完全旁路的语义。在 mcp_filter.cc 的decodeHeaders入口处过滤器首先检查当前生效的流量模式Http::FilterHeadersStatus McpFilter::decodeHeaders(Http::RequestHeaderMap headers, bool end_stream) { if (trafficMode() envoy::extensions::filters::http::mcp::v3::Mcp::NOOP) { ENVOY_LOG(debug, MCP filter in NOOP mode, passing through without inspection); return Http::FilterHeadersStatus::Continue; } // ... 其余模式下的 MCP 请求识别、体缓冲、属性解析逻辑 }这一判断位于过滤器对请求做任何 MCP 识别SSE 检查、JSON-RPC POST 检查、DELETE 会话终止检查之前因此不缓冲请求体不会调用decoder_callbacks_-setBufferLimit(max_size)设置缓冲上限也不会因等待请求体完整而返回StopIteration不解析属性JSON-RPC 2.0 解析、JSONPath 属性提取、动态元数据写入全部跳过不传播上下文propagate_trace_context与propagate_baggage配置在 NOOP 下同样不生效不拒绝任何请求即使是完全不符合 MCP 规格的请求如纯GET /的 HTML 请求也会原样放行到上游。从 mcp_filter.h 可以看到trafficMode()的解析支持per-route override路由级覆盖并带有一处精心设计由于假设单个请求的生命周期内路由不会改变该值在decodeHeaders中首次访问时被 latch缓存到traffic_mode_成员变量后续访问不再重复查询路由envoy::extensions::filters::http::mcp::v3::Mcp::TrafficMode McpFilter::trafficMode() { if (!traffic_mode_.has_value()) { const auto* override_config Http::Utility::resolveMostSpecificPerFilterConfigMcpOverrideConfig(decoder_callbacks_); traffic_mode_ override_config ? override_config-trafficMode() : config_-trafficMode(); } return *traffic_mode_; }这段逻辑mcp_filter.cc清楚表明路由级McpOverride的优先级高于全局配置这也是本文后面 per-route NOOP 豁免方案的实现基础。如何配置 NOOP 模式全局配置NOOP 模式通过Mcp消息的traffic_mode字段配置该字段在 mcp.proto 中定义并带有defined_only校验规则即只能取枚举中已定义的值// Configures how the filter handles non-MCP traffic. TrafficMode traffic_mode 1 [(validate.rules).enum {defined_only: true}];在 HTTP 连接管理器HCM过滤器链中配置envoy.filters.http.mcp过滤器时将traffic_mode设为NOOP即可类型 URL 为type.googleapis.com/envoy.extensions.filters.http.mcp.v3.Mcp。仓库官方示例 mcp-filter.yaml 展示了过滤器链的编排方式将 MCP 过滤器置于 RBAC 过滤器之前供后者消费元数据其中默认使用traffic_mode: PASS_THROUGH如需关闭检查将其改为NOOP即可http_filters: - name: envoy.filters.http.mcp typed_config: type: type.googleapis.com/envoy.extensions.filters.http.mcp.v3.Mcp traffic_mode: NOOP - name: envoy.filters.http.rbac typed_config: type: type.googleapis.com/envoy.extensions.filters.http.rbac.v3.RBAC - name: envoy.filters.http.router typed_config: type: type.googleapis.com/envoy.extensions.filters.http.router.v3.RouterPer-route 覆盖仅对指定路由豁免NOOP 模式还可以通过McpOverride消息按路由覆盖全局配置。McpOverride定义于 mcp.proto其traffic_mode字段同样带有defined_only校验对应的路由级配置工厂在 config.cc 中注册createRouteSpecificFilterConfigTyped返回McpOverrideConfig。一个典型场景是全局配置REJECT_NO_MCP强制网关只放行合规 MCP 流量但某些路径如健康检查、静态资源或非 MCP 的调试端点需要豁免。此时可以在这些路由上叠加McpOverride将traffic_mode覆盖为NOOProute_config: name: route virtual_hosts: - domains: [*] routes: - match: prefix: /api/mcp route: cluster: mcp-backend typed_per_filter_config: envoy.filters.http.mcp: type: type.googleapis.com/envoy.extensions.filters.http.mcp.v3.McpOverride traffic_mode: NOOP结合上文trafficMode()的实现可以看到该覆盖生效的完整链路为路由配置中的typed_per_filter_config→createRouteSpecificFilterConfigTyped构造McpOverrideConfig→decodeHeaders中通过resolveMostSpecificPerFilterConfig解析出 override → 优先采用 override 的traffic_mode。测试验证NOOP 模式的四层行为保证仓库为 NOOP 模式编写了完整的单元测试与集成测试分别位于单元测试mcp_filter_test.cc集成测试mcp_filter_integration_test.cc。单元测试filter 行为层面mcp_filter_test.cc 中的三个用例精确刻画了 NOOP 模式的行为契约测试用例断言内容NoopModePassesThroughNonMcp非 MCP 请求GETaccept: text/html在 NOOP 模式下直接返回Continue且不触发任何本地拒绝响应sendLocalReply调用次数为 0NoopModeDoesNotInspectMcpPost合法的 MCP POST 请求在 NOOP 模式下同样立即Continue不缓冲请求体即使请求体是合法的 JSON-RPC 2.0 消息tools/call也断言不产生任何动态元数据写入setDynamicMetadata调用次数为 0NoopModePerRouteOverride全局配置为REJECT_NO_MCP时通过路由级McpOverride将traffic_mode覆盖为NOOP非 MCP 请求得以放行验证了 per-route 覆盖的优先级对照之下同文件中REJECT_NO_MCP模式的测试如 mcp_filter_test.cc会断言返回StopIteration并触发400 Bad Request本地响应Only MCP traffic is allowed与 NOOP 的行为形成鲜明对比。集成测试端到端行为层面mcp_filter_integration_test.cc 中的三个用例进一步验证了真实代理链路上的行为NoopModePassesThroughNonMcp配置traffic_mode: NOOP后普通GET /请求被完整转发到上游上游响应200请求体完整到达upstream_request_-complete()为真NoopModeIgnoresInvalidJsonRpc一个本应在 REJECT_NO_MCP 下被检查并拒绝的非 JSON-RPC POST 请求{invalid: not-jsonrpc}在 NOOP 模式下被原样转发且请求体与上游收到的字节完全一致EXPECT_EQ(request_body, upstream_request_-body().toString())证明过滤器既未缓冲也未解析请求体PerRouteOverrideToNoop全局REJECT_NO_MCP 路由级 NOOP 覆盖的组合下对/api/mcp路径的普通 GET 请求放行至上游端到端验证了按路由豁免的完整链路。这些测试从请求头阶段不拒绝、请求体阶段不解析、路由覆盖优先、端到端原样透传四个维度为 NOOP 模式的实现提供了可复现的行为证据。使用场景与注意事项基于源码实现与测试行为NOOP 模式适合以下场景灰度/应急兜底当 MCP 过滤器升级或配置变更导致误判时可快速将traffic_mode切换为NOOP关闭全部检查恢复流量这是比PASS_THROUGH更彻底的一键旁路开关连属性解析与 trace context 传播也一并关闭开销最低。按路由豁免在全局REJECT_NO_MCP的严格模式下通过McpOverride只对非 MCP 路径健康检查、调试端点等豁免实现严格为主、按需放行的精细化管控。性能敏感链路不需要 MCP 属性做策略或可观测性消费时NOOP 模式可以避免请求体缓冲与 JSON 解析带来的额外开销。需要留意的是在 NOOP 模式下下游过滤器RBAC、ext_authz无法再消费envoy.filters.http.mcp命名空间下的动态元数据相关策略会随之失效max_request_body_size、clear_route_cache、propagate_trace_context、propagate_baggage、attribute_source等配置在 NOOP 模式下均不会生效过滤器在到达这些逻辑之前已放行McpOverride的解析使用了resolveMostSpecificPerFilterConfigmcp_filter.cc实现注释也提示该解析尚未 latch、每次请求会重复查询路由因此在路由数量极大或路由缓存被频繁清除的场景下需关注其开销。总结NOOP流量模式为 Envoy 的 MCP 过滤器 补齐了第三种流量处置能力相比默认的PASS_THROUGH透传但照常解析与强制的REJECT_NO_MCP拒绝非 MCP 流量NOOP在请求头解码阶段即完全旁路不检查、不解析、不传播、不拒绝。其语义定义于 mcp.proto实现落点在 mcp_filter.cc 的decodeHeaders短路分支行为契约由 mcp_filter_test.cc 与 mcp_filter_integration_test.cc 双层测试锁定并支持通过McpOverride实现按路由精细化豁免。对于任何将 Envoy 作为 MCP 网关接入生产流量的团队这一模式都是一份低风险的安全阀。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表