Higress MCP 协议桥接实战新版无状态客户端如何调用 Legacy MCP Server2025-03-26【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higressMCPModel Context Protocol协议在快速演进当客户端已采用2026-07-28新版无状态交互方式而上游服务仍是2025-03-26旧版时中间层网关必须完成协议代差桥接。本指南基于 Higress 仓库中的可运行实验 03-modern-to-legacy仓库内亦提供中文版演示 Higress 如何在每个下游请求内部执行隔离的 legacy 握手、将新版结果合同适配给旧版上游并阻止敏感下游 Header 穿越协议边界。读完本文你将掌握完整的部署、验证、事件级证据检查与清理流程并理解protocolStrategy: legacy的底层实现原理。场景与核心问题2026-07-28版本的 MCP 协议强调无状态 HTTP 交换客户端无需先initialize每个 RPC 请求独立携带协议版本、方法等元数据即可完成发现与调用对应 Demo 01 Stateless HTTP。而2025-03-26的 Legacy Server 仍遵循先握手、再通信的会话式流程其initialize响应还会签发一个Mcp-Session-Id供后续请求携带。当这两者直接对接时存在三个障碍握手缺失新版请求不会先发initialize旧版 Server 无法识别结果合同不一致新版要求resultType、ttlMs、cacheScope等字段旧版响应没有敏感头越界下游的Cookie、会话 ID、Last-Event-ID、Authorization、无关凭据等一旦被透传给旧版上游可能造成凭据泄露或协议污染。Higress 的mcp-server插件以mcp-proxy类型承担桥接职责对上游声明protocolStrategy: legacy并在单次下游交换内部自动完成握手 → 转发 RPC → 适配结果的完整闭环。前置条件与实验环境准备实验在 Higress 仓库根目录开始首先进入samples/mcp并完成两件事构建插件、启动共享环境。cd samples/mcp ./protocol/2026-07-28/plugin/build.sh ./environment/scripts/up.sh cd protocol/2026-07-28/03-modern-to-legacy export GATEWAY_URLhttp://127.0.0.1:18080/mcp export MCP_HOSTlegacy-bridge.mcp.demo环境说明插件构建build.sh 会优先使用 Docker、其次 Podman 构建镜像然后基于 Dockerfile 从固定 commit 拉取 Higress 源码以GOOSwasip1 GOARCHwasm编译mcp-server扩展并输出到.runtime/plugins/mcp-server/2026-07-28/plugin.wasm同时生成source-commit.txt与SHA256SUMS两份可审计产物源码版本锁定默认构建源与固定 commit 定义在 source.env 中如需更换可参考版本目录 README_EN 通过MCP_DEMO_HIGRESS_REPOSITORY、MCP_DEMO_HIGRESS_REF环境变量覆盖共享环境up.sh 负责把构建出的 wasm 文件暴露给 Kind 节点与 Higress Gateway所有 Demo 统一通过file:///opt/plugins/mcp-server/2026-07-28/plugin.wasm引用两个环境变量GATEWAY_URL指向网关入口路径/mcpMCP_HOST指定本实验的路由 Host后续 curl 均依赖它们。Step 1部署 Legacy MCP fixturefixture 是一个可观测的2025-03-26服务它记录收到的每个 RPC 事件及关键 Header便于实验后核对握手序列与隔离效果。Python 源码通过 ConfigMap 挂载到python:3.12-alpine容器见 deployment.yaml含/healthz就绪探针kubectl -n mcp-demo create configmap legacy-mcp-fixture \ --from-fileserver.pyfixture/legacy_server.py \ --dry-runclient -o yaml | kubectl apply -f - kubectl apply -f fixture/deployment.yaml kubectl -n mcp-demo rollout status deployment/legacy-mcp --timeout180s接着部署 Higress 路由与 MCP Proxy 配置kubectl apply -f resources.yaml清空 fixture 的事件台账确保实验从干净状态开始kubectl -n mcp-demo exec deployment/legacy-mcp -- python -c \ import urllib.request; urllib.request.urlopen(urllib.request.Request(http://127.0.0.1:8080/__reset, datab, methodPOST))resources.yaml 中的桥接配置解读resources.yaml 包含两部分是整个桥接能力的落点IngressingressClassName: higressHost 为legacy-bridge.mcp.demo路径/mcp前缀路由到legacy-mcp服务WasmPlugin挂载本实验的 wasm 插件并通过matchRules[].config声明上游 profileserver: name: legacy-bridge-demo type: mcp-proxy transport: http protocolStrategy: legacy mcpServerURL: http://legacy-mcp.mcp-demo.svc.cluster.local:8080/legacy tools: - name: proxy_echo description: Echo a deterministic value through a legacy MCP server args: - name: value description: Value to echo type: string required: true要点type: mcp-proxy表明插件以代理模式转发到mcpServerURL注意路径末尾的/legacy是 fixture 的 RPC 端点protocolStrategy: legacy是本次桥接的关键开关它声明上游遵循旧版会话式协议插件据此在每次下游交换内插入隔离握手tools中显式声明的proxy_echo描述与参数 schema供新版客户端通过server/discover与tools/list直接发现defaultConfigDisable: true表示本规则配置完全由 matchRules 提供不叠加全局默认配置。Step 2用新版请求列出 Legacy Tool客户端完全以2026-07-28无状态方式发起请求同时故意携带一批敏感的、与旧版协议无关的 Header用于验证隔离效果curl -sS -D /tmp/mcp-bridge-list-headers \ $GATEWAY_URL \ -H Host: $MCP_HOST \ -H Origin: http://$MCP_HOST \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -H MCP-Protocol-Version: 2026-07-28 \ -H Mcp-Method: tools/list \ -H Cookie: downstream-cookiesecret \ -H Mcp-Session-Id: downstream-session \ -H Last-Event-ID: downstream-event \ -H Authorization: Bearer downstream-not-policy \ -H x-unrelated-credential: should-not-pass \ -H Mcp-Param-Future: must-not-cross-era \ -H X-Request-ID: demo-bridge-list \ --data-binary requests/list-tools.json | jq请求体 list-tools.json 是标准新版工具列表请求_meta中声明io.modelcontextprotocol/protocolVersion: 2026-07-28、客户端信息与能力。预期返回工具proxy_echo可见且结果遵循新版合同——resultType: complete、ttlMs: 0、cacheScope: private。这三个字段是该里程碑的线上合同约定详见 mcp-server 扩展文档server/discover与tools/list携带ttlMs: 0与cacheScope: private表示本里程碑不含响应/描述缓存引擎同时每个成功结果都会在_meta.io.modelcontextprotocol/serverInfo中携带服务身份。紧接着验证响应头没有暴露上游会话grep -i ^Mcp-Session-Id: /tmp/mcp-bridge-list-headers || echo upstream session is hiddenlegacy 握手在initialize响应中会签发Mcp-Session-Id但该 ID 只在上游交换内部使用绝不应返回给下游——这条 grep 即用于确认上游会话被隐藏。Step 3调用 Legacy Tool以相同方式发起tools/call调用proxy_echo并传入参数valuebridgecurl -sS -D /tmp/mcp-bridge-call-headers \ $GATEWAY_URL \ -H Host: $MCP_HOST \ -H Origin: http://$MCP_HOST \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -H MCP-Protocol-Version: 2026-07-28 \ -H Mcp-Method: tools/call \ -H Mcp-Name: proxy_echo \ -H Cookie: downstream-cookiesecret \ -H Mcp-Session-Id: downstream-session \ -H Last-Event-ID: downstream-event \ -H Authorization: Bearer downstream-not-policy \ -H x-unrelated-credential: should-not-pass \ -H Mcp-Param-Future: must-not-cross-era \ -H X-Request-ID: demo-bridge-call \ --data-binary requests/call-tool.json | jq请求体 call-tool.json 携带name: proxy_echo与arguments.value: bridge。预期返回echo:bridge、isError: false、resultType: complete——工具调用结果被正常透传且被套上新版结果合同。Step 4检查精确握手序列证据验证实验最有价值的一步查看 fixture 事件台账确认 Higress 在两次下游请求内部各自执行了一次完整的 legacy 握手kubectl -n mcp-demo exec deployment/legacy-mcp -- python -c \ import urllib.request; print(urllib.request.urlopen(http://127.0.0.1:8080/__state).read().decode()) | jq两次下游请求应产生严格的六个上游事件initialize notifications/initialized tools/list initialize notifications/initialized tools/call也可以用一条命令直接断言该顺序kubectl -n mcp-demo exec deployment/legacy-mcp -- python -c \ import urllib.request; print(urllib.request.urlopen(http://127.0.0.1:8080/__state).read().decode()) | jq -e [.events[].rpcMethod] [initialize,notifications/initialized,tools/list,initialize,notifications/initialized,tools/call]fixture 的事件记录逻辑legacy_server.py 是一个ThreadingHTTPServer实现对每个 RPC 记录以下字段rpcMethod/rpcId/toolNameRPC 本身的信息protocolVersion/mcpMethod/mcpName从请求头读取的协议元数据futureParam读取Mcp-Param-Future头用于验证新纪元参数不得跨代authorizationPresent/cookiePresent/sessionPresent/lastEventIDPresent/unrelatedCredentialPresent分别探测Authorization、Cookie、Mcp-Session-Id、Last-Event-ID、x-unrelated-credential是否到达上游。同时 fixture 对initialize返回protocolVersion: 2025-03-26并在响应头签发Mcp-Session-Id: fixture-upstream-session对tools/list、tools/call返回旧版结果格式——这正是legacy语义的具体载体。关键断言cookiePresent、lastEventIDPresent、authorizationPresent、unrelatedCredentialPresent必须全部为falseCookie、会话 ID、Last-Event-ID、Authorization、无关凭据均未越过协议边界futureParam必须为nullMcp-Param-Future这类新纪元参数被隔离不会泄漏给旧版上游握手自身产生的Mcp-Session-Id只在上游交换中使用下游不可见。这与 mcp-server 扩展文档 中出站 Header 为每个 RPC 重建的实现约束一致Authorization仅通过显式的代理鉴权策略生成或转发Cookie、下游会话、Last-Event-ID、内部路由头与无关凭据默认一律不透传。清理kubectl delete -f resources.yaml kubectl delete -f fixture/deployment.yaml kubectl -n mcp-demo delete configmap legacy-mcp-fixture依次删除 WasmPlugin/Ingress 路由、fixture 部署与其 ConfigMap恢复集群初始状态。机制总结与迁移注意从本实验可以提炼出 Higress 处理现代客户端 → Legacy 上游的完整行为模型请求内隔离握手每次下游交换内部插件先向上游发送initialize随后发送notifications/initialized再转发实际 RPCtools/list/tools/call。握手产生的会话 ID 被限制在上游链路内下游完全无感结果合同适配旧版上游返回的裸结果被包装为新版合同resultType: complete、ttlMs: 0、cacheScope: private、serverInfo服务身份保证新版客户端可正常消费Header 白名单化出站 Header 按 RPC 重建Cookie、下游 Session、Last-Event-ID、Authorization、无关凭据与跨代参数默认不转发从源头杜绝凭据越界。迁移层面需注意现有未配置protocolStrategy的mcp-proxy继续默认使用legacy其下游/上游均为旧版的路径保持不变只有在确认上游支持2026-07-28时才应显式切换为protocolStrategy: modern。该里程碑不会自动探测、回退或重试其他协议版本protocolStrategy: auto、2025-11-25profile 等能力被明确列入后续计划见 README_EN。因此在真实环境中启用此类桥接前务必先确认上游协议版本与自身认证策略避免将运行期会话 ID 写入配置或测试凭据。如需横向对照可继续阅读同一版本目录下的 Demo 01 无状态 HTTP、Demo 02 REST 转 MCP 与 Demo 04 请求校验它们在无状态、翻译与校验维度上与本实验互补共同构成 MCP2026-07-28特性的可运行验证矩阵。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Higress MCP 协议桥接实战：新版无状态客户端如何调用 Legacy MCP Server（2025-03-26）
Higress MCP 协议桥接实战新版无状态客户端如何调用 Legacy MCP Server2025-03-26【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higressMCPModel Context Protocol协议在快速演进当客户端已采用2026-07-28新版无状态交互方式而上游服务仍是2025-03-26旧版时中间层网关必须完成协议代差桥接。本指南基于 Higress 仓库中的可运行实验 03-modern-to-legacy仓库内亦提供中文版演示 Higress 如何在每个下游请求内部执行隔离的 legacy 握手、将新版结果合同适配给旧版上游并阻止敏感下游 Header 穿越协议边界。读完本文你将掌握完整的部署、验证、事件级证据检查与清理流程并理解protocolStrategy: legacy的底层实现原理。场景与核心问题2026-07-28版本的 MCP 协议强调无状态 HTTP 交换客户端无需先initialize每个 RPC 请求独立携带协议版本、方法等元数据即可完成发现与调用对应 Demo 01 Stateless HTTP。而2025-03-26的 Legacy Server 仍遵循先握手、再通信的会话式流程其initialize响应还会签发一个Mcp-Session-Id供后续请求携带。当这两者直接对接时存在三个障碍握手缺失新版请求不会先发initialize旧版 Server 无法识别结果合同不一致新版要求resultType、ttlMs、cacheScope等字段旧版响应没有敏感头越界下游的Cookie、会话 ID、Last-Event-ID、Authorization、无关凭据等一旦被透传给旧版上游可能造成凭据泄露或协议污染。Higress 的mcp-server插件以mcp-proxy类型承担桥接职责对上游声明protocolStrategy: legacy并在单次下游交换内部自动完成握手 → 转发 RPC → 适配结果的完整闭环。前置条件与实验环境准备实验在 Higress 仓库根目录开始首先进入samples/mcp并完成两件事构建插件、启动共享环境。cd samples/mcp ./protocol/2026-07-28/plugin/build.sh ./environment/scripts/up.sh cd protocol/2026-07-28/03-modern-to-legacy export GATEWAY_URLhttp://127.0.0.1:18080/mcp export MCP_HOSTlegacy-bridge.mcp.demo环境说明插件构建build.sh 会优先使用 Docker、其次 Podman 构建镜像然后基于 Dockerfile 从固定 commit 拉取 Higress 源码以GOOSwasip1 GOARCHwasm编译mcp-server扩展并输出到.runtime/plugins/mcp-server/2026-07-28/plugin.wasm同时生成source-commit.txt与SHA256SUMS两份可审计产物源码版本锁定默认构建源与固定 commit 定义在 source.env 中如需更换可参考版本目录 README_EN 通过MCP_DEMO_HIGRESS_REPOSITORY、MCP_DEMO_HIGRESS_REF环境变量覆盖共享环境up.sh 负责把构建出的 wasm 文件暴露给 Kind 节点与 Higress Gateway所有 Demo 统一通过file:///opt/plugins/mcp-server/2026-07-28/plugin.wasm引用两个环境变量GATEWAY_URL指向网关入口路径/mcpMCP_HOST指定本实验的路由 Host后续 curl 均依赖它们。Step 1部署 Legacy MCP fixturefixture 是一个可观测的2025-03-26服务它记录收到的每个 RPC 事件及关键 Header便于实验后核对握手序列与隔离效果。Python 源码通过 ConfigMap 挂载到python:3.12-alpine容器见 deployment.yaml含/healthz就绪探针kubectl -n mcp-demo create configmap legacy-mcp-fixture \ --from-fileserver.pyfixture/legacy_server.py \ --dry-runclient -o yaml | kubectl apply -f - kubectl apply -f fixture/deployment.yaml kubectl -n mcp-demo rollout status deployment/legacy-mcp --timeout180s接着部署 Higress 路由与 MCP Proxy 配置kubectl apply -f resources.yaml清空 fixture 的事件台账确保实验从干净状态开始kubectl -n mcp-demo exec deployment/legacy-mcp -- python -c \ import urllib.request; urllib.request.urlopen(urllib.request.Request(http://127.0.0.1:8080/__reset, datab, methodPOST))resources.yaml 中的桥接配置解读resources.yaml 包含两部分是整个桥接能力的落点IngressingressClassName: higressHost 为legacy-bridge.mcp.demo路径/mcp前缀路由到legacy-mcp服务WasmPlugin挂载本实验的 wasm 插件并通过matchRules[].config声明上游 profileserver: name: legacy-bridge-demo type: mcp-proxy transport: http protocolStrategy: legacy mcpServerURL: http://legacy-mcp.mcp-demo.svc.cluster.local:8080/legacy tools: - name: proxy_echo description: Echo a deterministic value through a legacy MCP server args: - name: value description: Value to echo type: string required: true要点type: mcp-proxy表明插件以代理模式转发到mcpServerURL注意路径末尾的/legacy是 fixture 的 RPC 端点protocolStrategy: legacy是本次桥接的关键开关它声明上游遵循旧版会话式协议插件据此在每次下游交换内插入隔离握手tools中显式声明的proxy_echo描述与参数 schema供新版客户端通过server/discover与tools/list直接发现defaultConfigDisable: true表示本规则配置完全由 matchRules 提供不叠加全局默认配置。Step 2用新版请求列出 Legacy Tool客户端完全以2026-07-28无状态方式发起请求同时故意携带一批敏感的、与旧版协议无关的 Header用于验证隔离效果curl -sS -D /tmp/mcp-bridge-list-headers \ $GATEWAY_URL \ -H Host: $MCP_HOST \ -H Origin: http://$MCP_HOST \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -H MCP-Protocol-Version: 2026-07-28 \ -H Mcp-Method: tools/list \ -H Cookie: downstream-cookiesecret \ -H Mcp-Session-Id: downstream-session \ -H Last-Event-ID: downstream-event \ -H Authorization: Bearer downstream-not-policy \ -H x-unrelated-credential: should-not-pass \ -H Mcp-Param-Future: must-not-cross-era \ -H X-Request-ID: demo-bridge-list \ --data-binary requests/list-tools.json | jq请求体 list-tools.json 是标准新版工具列表请求_meta中声明io.modelcontextprotocol/protocolVersion: 2026-07-28、客户端信息与能力。预期返回工具proxy_echo可见且结果遵循新版合同——resultType: complete、ttlMs: 0、cacheScope: private。这三个字段是该里程碑的线上合同约定详见 mcp-server 扩展文档server/discover与tools/list携带ttlMs: 0与cacheScope: private表示本里程碑不含响应/描述缓存引擎同时每个成功结果都会在_meta.io.modelcontextprotocol/serverInfo中携带服务身份。紧接着验证响应头没有暴露上游会话grep -i ^Mcp-Session-Id: /tmp/mcp-bridge-list-headers || echo upstream session is hiddenlegacy 握手在initialize响应中会签发Mcp-Session-Id但该 ID 只在上游交换内部使用绝不应返回给下游——这条 grep 即用于确认上游会话被隐藏。Step 3调用 Legacy Tool以相同方式发起tools/call调用proxy_echo并传入参数valuebridgecurl -sS -D /tmp/mcp-bridge-call-headers \ $GATEWAY_URL \ -H Host: $MCP_HOST \ -H Origin: http://$MCP_HOST \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -H MCP-Protocol-Version: 2026-07-28 \ -H Mcp-Method: tools/call \ -H Mcp-Name: proxy_echo \ -H Cookie: downstream-cookiesecret \ -H Mcp-Session-Id: downstream-session \ -H Last-Event-ID: downstream-event \ -H Authorization: Bearer downstream-not-policy \ -H x-unrelated-credential: should-not-pass \ -H Mcp-Param-Future: must-not-cross-era \ -H X-Request-ID: demo-bridge-call \ --data-binary requests/call-tool.json | jq请求体 call-tool.json 携带name: proxy_echo与arguments.value: bridge。预期返回echo:bridge、isError: false、resultType: complete——工具调用结果被正常透传且被套上新版结果合同。Step 4检查精确握手序列证据验证实验最有价值的一步查看 fixture 事件台账确认 Higress 在两次下游请求内部各自执行了一次完整的 legacy 握手kubectl -n mcp-demo exec deployment/legacy-mcp -- python -c \ import urllib.request; print(urllib.request.urlopen(http://127.0.0.1:8080/__state).read().decode()) | jq两次下游请求应产生严格的六个上游事件initialize notifications/initialized tools/list initialize notifications/initialized tools/call也可以用一条命令直接断言该顺序kubectl -n mcp-demo exec deployment/legacy-mcp -- python -c \ import urllib.request; print(urllib.request.urlopen(http://127.0.0.1:8080/__state).read().decode()) | jq -e [.events[].rpcMethod] [initialize,notifications/initialized,tools/list,initialize,notifications/initialized,tools/call]fixture 的事件记录逻辑legacy_server.py 是一个ThreadingHTTPServer实现对每个 RPC 记录以下字段rpcMethod/rpcId/toolNameRPC 本身的信息protocolVersion/mcpMethod/mcpName从请求头读取的协议元数据futureParam读取Mcp-Param-Future头用于验证新纪元参数不得跨代authorizationPresent/cookiePresent/sessionPresent/lastEventIDPresent/unrelatedCredentialPresent分别探测Authorization、Cookie、Mcp-Session-Id、Last-Event-ID、x-unrelated-credential是否到达上游。同时 fixture 对initialize返回protocolVersion: 2025-03-26并在响应头签发Mcp-Session-Id: fixture-upstream-session对tools/list、tools/call返回旧版结果格式——这正是legacy语义的具体载体。关键断言cookiePresent、lastEventIDPresent、authorizationPresent、unrelatedCredentialPresent必须全部为falseCookie、会话 ID、Last-Event-ID、Authorization、无关凭据均未越过协议边界futureParam必须为nullMcp-Param-Future这类新纪元参数被隔离不会泄漏给旧版上游握手自身产生的Mcp-Session-Id只在上游交换中使用下游不可见。这与 mcp-server 扩展文档 中出站 Header 为每个 RPC 重建的实现约束一致Authorization仅通过显式的代理鉴权策略生成或转发Cookie、下游会话、Last-Event-ID、内部路由头与无关凭据默认一律不透传。清理kubectl delete -f resources.yaml kubectl delete -f fixture/deployment.yaml kubectl -n mcp-demo delete configmap legacy-mcp-fixture依次删除 WasmPlugin/Ingress 路由、fixture 部署与其 ConfigMap恢复集群初始状态。机制总结与迁移注意从本实验可以提炼出 Higress 处理现代客户端 → Legacy 上游的完整行为模型请求内隔离握手每次下游交换内部插件先向上游发送initialize随后发送notifications/initialized再转发实际 RPCtools/list/tools/call。握手产生的会话 ID 被限制在上游链路内下游完全无感结果合同适配旧版上游返回的裸结果被包装为新版合同resultType: complete、ttlMs: 0、cacheScope: private、serverInfo服务身份保证新版客户端可正常消费Header 白名单化出站 Header 按 RPC 重建Cookie、下游 Session、Last-Event-ID、Authorization、无关凭据与跨代参数默认不转发从源头杜绝凭据越界。迁移层面需注意现有未配置protocolStrategy的mcp-proxy继续默认使用legacy其下游/上游均为旧版的路径保持不变只有在确认上游支持2026-07-28时才应显式切换为protocolStrategy: modern。该里程碑不会自动探测、回退或重试其他协议版本protocolStrategy: auto、2025-11-25profile 等能力被明确列入后续计划见 README_EN。因此在真实环境中启用此类桥接前务必先确认上游协议版本与自身认证策略避免将运行期会话 ID 写入配置或测试凭据。如需横向对照可继续阅读同一版本目录下的 Demo 01 无状态 HTTP、Demo 02 REST 转 MCP 与 Demo 04 请求校验它们在无状态、翻译与校验维度上与本实验互补共同构成 MCP2026-07-28特性的可运行验证矩阵。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考