Higress MCP 2026-07-28 协议实战验证指南：无状态 HTTP、REST 转换、Legacy 桥接与前置校验

Higress MCP 2026-07-28 协议实战验证指南：无状态 HTTP、REST 转换、Legacy 桥接与前置校验

【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress

本篇技术指南以 samples/mcp/protocol/2026-07-28 目录下的 MCP 版本 Demo 手册为核心，系统讲解 Higress 对 MCP2026-07-28（modern）协议基线的实现与验证方法。你将掌握如何在本地 Kind 环境构建固定 commit 的mcp-server插件，并通过四个可独立执行的 Demo 逐一验证「无状态 HTTP Tools」「REST-to-MCP 转换」「新版客户端访问 Legacy Server」以及「请求前置校验与阻断」四类核心能力，同时结合 mcp-server 插件源码 与 conformance 测试理解其底层实现契约。

一、MCP 2026-07-28 基线：modern profile 与结果合同

Higress 内置的mcp-server插件同时维护两套协议 profile，版本目录2026-07-28专门归档 modern 基线：

modern profile 本期只实现server/discover、tools/list和tools/call三个 RPC。从 mcp-server 插件 README 可以看到，它还会校验 Content-Type、Accept、同源 Origin、JSON-RPC 单消息边界、身份镜像头与资源上限，批量、response envelope 和 trailing JSON 会被拒绝。

modern 成功结果统一遵守如下结果合同（见 能力与结果合同）：

• server/discover只声明当前真正可用的tools: {}，不声明tools.listChanged、MRTR、subscriptions、resources、prompts 等未实现能力；
• 所有 modern 成功结果使用resultType: complete，并在_meta.io.modelcontextprotocol/serverInfo携带服务端身份；
• server/discover与tools/list额外返回ttlMs: 0与cacheScope: private（仅是 wire contract，本期没有 response/descriptor cache 引擎）。

modern 请求必须同时携带传输头与 body 中的_meta，例如：

MCP-Protocol-Version: 2026-07-28 Mcp-Method: tools/call Mcp-Name: get_weather Content-Type: application/json Accept: application/json, text/event-stream

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": {"name": "example", "version": "1.0.0"}, "io.modelcontextprotocol/clientCapabilities": {} }, "name": "get_weather", "arguments": {"location": "Hangzhou"} } }

二、准备环境与构建固定 commit 插件

2.1 前置条件

依据 公共环境说明，需要：

• Docker 或 Podman；
• Kind；
• kubectl；
• Helm；
• curl；
• jq（用于执行各 Demo 的响应断言）；
• 至少约 4 GiB 可用内存；
• 能访问 Higress Helm 仓库和所需镜像仓库。

2.2 构建插件并启动环境

从 Higress 仓库根目录执行：

cd samples/mcp ./protocol/2026-07-28/plugin/build.sh ./environment/scripts/up.sh

build.sh的构建逻辑（见 plugin/build.sh）：

1. 自动探测可用的容器引擎（优先 Docker，其次 Podman），无可用引擎时报错退出；
2. 若.runtime/container-engine已存在（即环境已启动），会拒绝重建插件，避免挂载中的 WASM 被覆盖；
3. 使用 plugin/Dockerfile 构建镜像：基于golang:1.24.4-alpine，在构建阶段git init后fetch --depth=1拉取固定源码，并以GOOS=wasip1 GOARCH=wasm交叉编译 mcp-server 扩展 为 WASM；
4. 运行产物镜像把plugin.wasm拷入挂载目录.runtime/plugins/mcp-server/2026-07-28/，同时写入source-commit.txt与SHA256SUMS供溯源核对。

插件默认从以下固定源码构建（定义于 plugin/source.env）：

https://github.com/higress-group/higress.git 14c36d9bd70b3dc38237cda6175b3f9dede0dccd

构建结果写入：

.runtime/plugins/mcp-server/2026-07-28/plugin.wasm

Kind 节点和 Higress Gateway 通过公共环境提供的 hostPath 看到该文件，因此所有 Demo 的WasmPlugin都引用：

file:///opt/plugins/mcp-server/2026-07-28/plugin.wasm

up.sh会依次完成（见 公共环境说明）：创建名为higress-mcp-demo的 Kind 集群、将.runtime/plugins挂载到节点/opt/plugins、使用固定 Helm Chart2.2.3安装 Higress、部署协议无关的observable-weatherHTTP 服务、建立端口转发。环境地址：

2.3 使用其他源码版本

编辑plugin/source.env，或在执行前覆盖其中的变量（三个均可覆盖：仓库、commit、构建镜像）：

MCP_DEMO_HIGRESS_REPOSITORY=https://github.com//higress.git \ MCP_DEMO_HIGRESS_REF= \ ./protocol/2026-07-28/plugin/build.sh

环境侧同样支持覆盖MCP_DEMO_CLUSTER、MCP_DEMO_GATEWAY_PORT、MCP_DEMO_CONSOLE_PORT、MCP_DEMO_BACKEND_PORT、MCP_DEMO_KIND_NODE_IMAGE与MCP_DEMO_HIGRESS_CHART_VERSION，避免端口冲突或多环境并存。

2.4 状态检查与清理

./environment/scripts/status.sh # 显示 higress-system、mcp-demo Pod 与三个端口转发状态 ./environment/scripts/down.sh # 停止端口转发并删除由本 Demo 创建的 Kind 集群

清理时构建产物保留在.runtime/plugins便于复用，该目录不提交到 Git。

三、Demo 一览

各 Demo 可独立执行：进入任一目录，部署资源、发送请求、观察证据并清理即可。下面逐一展开。

四、Demo 01：无状态 HTTP Tools

本 Demo 验证 modern 客户端可以通过独立 HTTP 请求完成server/discover、tools/list和tools/call，不需要initialize，也不会获得协议 Session。完整指引见 01-stateless-http README。

4.1 前置与部署

cd protocol/2026-07-28/01-stateless-http export GATEWAY_URL=http://127.0.0.1:18080/mcp export MCP_HOST=stateless.mcp.demo kubectl apply -f resources.yaml kubectl get ingress -n mcp-demo mcp-2026-stateless-http kubectl get wasmplugin -n higress-system mcp-2026-stateless-http

等待几秒让 Higress Controller 将配置下发到 Gateway。

resources.yaml中的 WasmPlugin 通过server.type: rest声明一个纯静态 REST Server，用responseTemplate.body定义返回文本（见 01 resources.yaml）：

spec: defaultConfigDisable: true matchRules: - config: server: name: stateless-demo type: rest version: 1.0.0 tools: - name: say_hello description: Return a deterministic greeting args: - name: name description: Name to greet type: string required: true responseTemplate: body: "hello {{.args.name}}" configDisable: false ingress: - mcp-demo/mcp-2026-stateless-http url: file:///opt/plugins/mcp-server/2026-07-28/plugin.wasm

responseTemplate.body支持{{.args.name}}这样的模板变量，把 Tool 参数渲染进响应文本——这正是「无后端、纯网关托管工具」的配置方式。

4.2 Step 1：发现 Server

curl -sS "$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: server/discover' \ -H 'X-Request-ID: demo-stateless-discover' \ --data-binary @requests/discover.json | jq

requests/discover.json是一个标准 JSON-RPC 2.0 请求，params._meta声明协议版本、clientInfo 与 clientCapabilities（见 discover.json）：

{ "jsonrpc": "2.0", "id": "stateless-discover", "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "higress-mcp-demo", "version": "1.0.0" }, "io.modelcontextprotocol/clientCapabilities": {} } } }

预期结果包含：

result.resultType = complete result.capabilities = {"tools": {}} result.ttlMs = 0 result.cacheScope = private result._meta.io.modelcontextprotocol/serverInfo.name = stateless-demo

注意 capabilities 只声明tools: {}，与插件 README 的「只声明当前真正可用的能力」一致。

4.3 Step 2：列出工具

curl -sS "$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 'X-Request-ID: demo-stateless-list' \ --data-binary @requests/list-tools.json | jq '.result'

工具列表中应只有say_hello，并继续携带resultType: complete、ttlMs: 0和cacheScope: private。

4.4 Step 3：调用工具并检查 Session

curl -sS -D /tmp/mcp-stateless-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: say_hello' \ -H 'X-Request-ID: demo-stateless-call' \ --data-binary @requests/call-tool.json | jq

调用say_hello（参数name: Higress）的预期文本为hello Higress。响应头中不应包含协议 Session：

if grep -qi '^Mcp-Session-Id:' /tmp/mcp-stateless-headers; then echo 'unexpected MCP session' else echo 'no MCP session returned' fi

三次请求之间没有 initialize 或 Session 依赖，每一个请求都可以独立执行——这就是「无状态 HTTP Tools」的核心特征。

4.5 Step 4：查看网关证据

kubectl logs -n higress-system deployment/higress-gateway --tail=200 | grep 'demo-stateless' || true

清理：

kubectl delete -f resources.yaml

五、Demo 02：REST-to-MCP

本 Demo 验证 Higress 将一个 MCPtools/call转换为一次普通 REST 请求，并通过协议无关后端的事件账本证明没有重复调用。完整指引见 02-rest-to-mcp README。

5.1 前置与部署

cd protocol/2026-07-28/02-rest-to-mcp export GATEWAY_URL=http://127.0.0.1:18080/mcp export BACKEND_URL=http://127.0.0.1:18082 export MCP_HOST=rest-to-mcp.mcp.demo kubectl apply -f resources.yaml curl -sS -X POST "$BACKEND_URL/__reset" | jq

该 Demo 的 WasmPlugin 与 Demo 01 的关键差异是增加了requestTemplate（见 02 resources.yaml）：

server: name: weather-demo type: rest version: 1.0.0 tools: - name: get_weather description: Query deterministic weather args: - name: location description: City name type: string required: true requestTemplate: url: http://observable-weather.mcp-demo.svc.cluster.local:8080/weather method: GET argsToUrlParam: true

requestTemplate声明工具调用要转换成的 REST 请求：url指向集群内observable-weather服务，method: GET，argsToUrlParam: true表示把 Tool 参数合并进 URL query。从 main_test.go 测试 可以看到requestTemplate的合法组合还包括argsToJsonBody: true（参数作为 JSON body），以及无参数工具的纯 URL 模板。

后端observable-weather是一个协议无关的可观察 HTTP 服务（见 server.py），只实现GET /weather?location=、GET /healthz、GET /__state、POST /__reset，它不理解 MCP 版本、JSON-RPC 方法或 Session——正好用于证明转换后的流量是「普通 REST」。

5.2 Step 1：查看发布的 REST Tool

curl -sS "$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 'X-Request-ID: demo-rest-list' \ --data-binary @requests/list-tools.json | jq '.result.tools'

应看到必填参数为location的get_weather（这是从args声明生成的 tool schema）。

5.3 Step 2：调用 Tool

curl -sS "$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: get_weather' \ -H 'X-Request-ID: demo-rest-call' \ --data-binary @requests/call-weather.json | jq

call-weather.json传入arguments: {"location": "Hangzhou"}（见 call-weather.json）。响应应包含weather for Hangzhou和resultType: complete。

5.4 Step 3：证明只有一次 REST 调用

curl -sS "$BACKEND_URL/__state" | jq

事件账本应只有一条：

{ "httpMethod": "GET", "path": "/weather", "query": {"location": "Hangzhou"} }

可以直接检查事件数量：

curl -sS "$BACKEND_URL/__state" | jq -e '.events | length == 1'

server.py的record_event会为每个到达/weather的请求写入httpMethod、path、query与递增的seq，因此「恰好一条事件」直接证明一个 MCPtools/call只产生一次 REST 上游调用，不存在重试或重复转发。清理：kubectl delete -f resources.yaml。

六、Demo 03：新版客户端访问 Legacy MCP Server

本 Demo 验证新版无状态客户端通过 Higress 访问 MCP2025-03-26Server：Higress 在每个下游请求内部执行隔离的 legacy handshake，同时适配新版结果合同并阻止敏感下游 Header 穿越协议边界。完整指引见 03-modern-to-legacy README。

6.1 部署 Legacy MCP fixture

fixture 使用python:3.12-alpine，Python 源码通过 ConfigMap 挂载：

kubectl -n mcp-demo create configmap legacy-mcp-fixture \ --from-file=server.py=fixture/legacy_server.py \ --dry-run=client -o yaml | kubectl apply -f - kubectl apply -f fixture/deployment.yaml kubectl -n mcp-demo rollout status deployment/legacy-mcp --timeout=180s

部署 Higress 路由和 MCP Proxy，并清空 fixture 事件：

kubectl apply -f resources.yaml 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", data=b"", method="POST"))'

这个 WasmPlugin 演示了mcp-proxy 模式（见 03 resources.yaml）：

server: 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

关键字段说明（对照 插件 README 的 Proxy 配置示例）：

• type: mcp-proxy：网关作为 MCP 代理转发上游；
• transport: http：上游传输为 HTTP（JSON-RPC over POST）；
• protocolStrategy: legacy：上游是 legacy profile，需要在单次下游交换内执行隔离的 legacy handshake；
• mcpServerURL：上游 MCP Server 端点。

6.2 Step 1：用新版请求列出 Legacy Tool

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-cookie=secret' \ -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

这个请求故意携带了一批敏感/伪造 Header（Cookie、下游Mcp-Session-Id、Last-Event-ID、Authorization、无关凭据、未来的Mcp-Param-Future），用于验证 Header 隔离。客户端应看到新版合同：proxy_echo、resultType: complete、ttlMs: 0和cacheScope: private。响应头不应暴露上游 Session：

grep -i '^Mcp-Session-Id:' /tmp/mcp-bridge-list-headers || echo 'upstream session is hidden'

6.3 Step 2：调用 Legacy Tool

curl -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-cookie=secret' \ -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

预期结果为echo:bridge、isError: false和resultType: complete。

6.4 Step 3：检查精确握手序列

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"]'

事件中的cookiePresent、lastEventIDPresent、authorizationPresent、unrelatedCredentialPresent应全部为false，futureParam应为null——证明下游敏感 Header 没有穿越协议边界。Legacy handshake 自己产生的Mcp-Session-Id只在上游交换中使用，客户端不可见。

从 legacy_server.py 可以看到，这个 fixture 每次请求都会记录rpcMethod、protocolVersion、mcpMethod、futureParam以及五个布尔位（authorizationPresent、cookiePresent、sessionPresent、lastEventIDPresent、unrelatedCredentialPresent），并对initialize返回Mcp-Session-Id: fixture-upstream-session响应头——这正是用于核对握手序列与 Header 隔离的「可观察上游」。同时注意：protocolStrategy只描述上游 profile，是显式配置；现有未配置protocolStrategy的mcp-proxy继续默认使用legacy，只有确认上游支持2026-07-28时才应显式切换为modern（见 迁移与默认行为）。

清理：

kubectl delete -f resources.yaml kubectl delete -f fixture/deployment.yaml kubectl -n mcp-demo delete configmap legacy-mcp-fixture

七、Demo 04：请求校验与前置阻断

本 Demo 验证三类错误在触达 REST 后端前被 Higress 拒绝：Tool 参数缺失、恶意跨域 Origin、Mcp-Method与 JSON-RPC Body 不一致。完整指引见 04-request-validation README。

7.1 前置

cd protocol/2026-07-28/04-request-validation export GATEWAY_URL=http://127.0.0.1:18080/mcp export BACKEND_URL=http://127.0.0.1:18082 export MCP_HOST=validation.mcp.demo kubectl apply -f resources.yaml curl -sS -X POST "$BACKEND_URL/__reset" | jq

该 Demo 的 WasmPlugin 配置与 Demo 02 相同（REST 天气工具，argsToUrlParam: true），见 04 resources.yaml。

7.2 Step 1：缺少必填 Tool 参数

curl -sS -w '\nHTTP %{http_code}\n' "$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: get_weather' \ -H 'X-Request-ID: demo-validation-arguments' \ --data-binary @requests/invalid-arguments.json

invalid-arguments.json的arguments为空对象（见 invalid-arguments.json）。预期 HTTP 为200，因为这是一个合法 Tool 调用的执行结果；JSON-RPC Result 中应有isError: true和缺少location的说明。这区分了「Tool 执行错误」（仍返回合法 RPC 结果）与「传输边界错误」（直接以 HTTP 状态码拒绝）。

7.3 Step 2：恶意 Origin

curl -sS -w '\nHTTP %{http_code}\n' "$GATEWAY_URL" \ -H "Host: $MCP_HOST" \ -H 'Origin: https://hostile.invalid' \ -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 'X-Request-ID: demo-validation-origin' \ --data-binary @requests/list-tools.json

预期 HTTP403，错误消息为untrusted Origin。modern profile 要求同源 Origin（请求中的Origin必须与Host匹配），跨域来源在传输边界被直接拒绝。

7.4 Step 3：Header 与 Body 不一致

下面的 Body 是tools/list，但 Header 声明tools/call：

curl -sS -w '\nHTTP %{http_code}\n' "$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 'X-Request-ID: demo-validation-mismatch' \ --data-binary @requests/list-tools.json

预期 HTTP400、JSON-RPC error code-32020，错误消息包含header does not match request body。

这两类传输边界错误在 conformance_test.go 中有明确的契约断言：第 265 行headerMismatchAtHeaders期望HTTPStatus: 400, Code: -32020, Message: "MCP header does not match request body"；第 302 行hostileOrigin期望403, "untrusted Origin"。运行go test -count=1 ./...即可复现这些断言（见 可复现验证）。

7.5 Step 4：证明后端调用数为零

curl -sS "$BACKEND_URL/__state" | jq curl -sS "$BACKEND_URL/__state" | jq -e '.events | length == 0'

这一步确认三种错误都在后端调用前结束——校验发生在网关侧，流量从未到达observable-weather。清理：kubectl delete -f resources.yaml。

八、源码级契约：插件实现与边界

上述四个 Demo 不是孤立的脚本，而是 mcp-server 插件 行为的端到端投影。理解以下几点有助于把 Demo 证据与实现契约对应起来：

8.1 Proxy profile 矩阵

protocolStrategy只描述上游 profile，本期是显式配置：

Demo 01/02/04 对应「modern → registered / REST」，Demo 03 对应「modern → legacy」。

8.2 Outbound Header 隔离

Outbound headers 按每个 RPC 重建。Authorization只会根据显式 proxy auth policy 生成或转发；Cookie、下游 session、Last-Event-ID、内部路由头和无关凭据默认不转发。未识别但格式合法的Mcp-Param-*仅在 modern→modern 的当前 Tool RPC 中透传，不得进入 discover、initialize 或 legacy RPC（见 插件 README 的 Header 规则）——这正是 Demo 03 中futureParam: null的依据。

8.3 明确暂缓范围

了解这些边界可以避免在验证 Demo 时对未实现能力产生错误预期。

九、版本目录的组织约定与扩展方式

samples/mcp目录的设计目标是「可运行、可复现」（见 MCP Demo 首页）：

• 环境完整：用 Kind、Helm 拉起 Higress Controller、Gateway、CRD 和 Console；
• 公共依赖复用：协议无关的集群、Higress 配置和模拟业务后端统一放在environment/；
• 版本边界明确：协议相关的插件源码 commit、构建方式和 Demo 归档在protocol//；
• 逐步可验证：每个 Demo 都是一份独立 README，说明验证目标、操作步骤、预期响应和网关/后端证据；
• 独立执行：读者可选择关心的能力按 README 完成实验。

新增协议版本时，在protocol//plugin/记录实现该版本的 Higress commit 与构建方法；新增 Demo 时，一个目录只验证一个主要能力，提供中英文 README、确定性请求与预期证据，不依赖真实凭据或私有服务，也不提交生成的 WASM、运行日志与临时证据。

十、快速上手总览

# 从 Higress 仓库根目录执行 cd samples/mcp # 1. 构建目标协议版本对应的 MCP Server 插件（固定 commit 14c36d9） ./protocol/2026-07-28/plugin/build.sh # 2. 拉起公共 Higress 环境（Kind + Helm + observable-weather 后端） ./environment/scripts/up.sh # 3. 选择一个 Demo，按其 README 逐步验证 less ./protocol/2026-07-28/01-stateless-http/README.md # 4. 全部实验完成后清理环境 ./environment/scripts/down.sh

对照四个 Demo 与源码可以形成完整闭环：Demo 01验证 modern 无状态 RPC 与结果合同（resultType: complete、ttlMs: 0、cacheScope: private、serverInfo）；Demo 02验证requestTemplate的 REST 转换与「一次调用、一次上游」；Demo 03验证mcp-proxy+protocolStrategy: legacy的隔离 handshake 与 Header 隔离；Demo 04验证参数、Origin、Header/Body 三类前置校验。每个 Demo 的断言命令都直接依赖jq与后端的__state事件账本，证据可复核、结果可复现，适合作为 MCP 协议实现验收与回归测试的基准手册。

【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress