Higress+Nacos 实现 API-to-MCP 全记录（附故障注意事项）

Nacos和Hiress官方文档主要是通过代码配置服务且其他网站虽然相关操作的教程文章不少但几乎没有把概念和操作结合起来讲的文章官方文档还存在缺少web配置过程/没有条例/不够详细等问题。本文记录将 REST API 转换为 MCP 服务的完整详细流程回答了配置过程中可能遇到的问题和疑惑以及踩过的 5 个坑。原创不易感谢点赞分享。一、整体架构客户端 (AI助手) ↓ MCP (SSE) Higress (MCP网关) ↓ 服务发现 Nacos (MCP Server) ↓ Tool定义 FastAPI (后端服务)核心转换链路REST API → OpenAPI → MCP Tools → MCP 网关为什么需要这个架构AI 助手原生支持 MCP 协议但不直接理解 REST API因此需要一个翻译层将 REST API 转换为 MCP Tools同时需要一个网关统一管理 MCP 服务入口为 AI 助手提供标准化的调用方式。二、Higress 和 Nacos 的分工组件职责Higress暴露 MCP 端点、路由转发、负载均衡、认证NacosOpenAPI 转 MCP Tools、服务注册发现注意Higress 通过 Nacos 获取后端服务地址Nacos 负责 MCP Tools 的定义与服务发现两者协作完成 REST API 到 MCP 的转换缺一不可。Higress: fba_mcp_server 在哪 ↓ Nacos: 后端实例在 fba_server:8001 ↓ Higress 连接 fba_server:8001 转发请求三、环境准备前置条件组件版本要求检查命令Docker20.10docker --versionDocker Compose2.0docker compose version项目结构如果有时间把他们都整合在同一个docker项目中也是可以C:/Users/XXXX/Desktop/ ├── higress-allinone/ # Higress all-in-one 镜像配置 └── nacos-docker/ # Nacos standalone derby 模式配置OpenAPI 准备OpenAPI 是描述 REST API 的标准规范包含接口路径、请求参数、响应格式等信息。 FastAPI 自动生成 /docsSwagger UI和 /openapi.jsonJSON 格式规范文件。访问 http://localhost:8000/openapi.json 路径获取openapi文档保存为json格式备用。详细的 OpenAPI 准备指南将在后续文章专门讲解第一步创建 Docker 网络注意因为所有软件均运行在容器中在这里创建一个mcp网络在不同的容器之间共享容器之间相互访问可以使用容器名比如fba可以使用容器名 http://fba_server。实际上容器运行在wsl虚拟机中也可以使用宿主机虚拟网络但这样增加工作复杂性。dockernetwork create mcpdockernetworkls|grepmcp第二步启动 Nacos 3.2⚠️ 注意使用独立部署的 Nacos 3.2 (standalone derby 模式)Higress all-in-one 内置的 Nacos 版本太老为什么不用内置Nacos内置的Nacos版本较老只有3.0.1新版的Nacos功能比较丰富。# nacos-docker/docker-compose.yamlversion:3.8services:nacos:image:nacos/nacos-server:v3.2.0container_name:nacosenvironment:-MODEstandalone-NACOS_AUTH_TOKENVGhpc0lzQVRlc3RTZWNyZXRLZXlGb3JOYWNvczEyMzQ1Njc4OTA-NACOS_AUTH_IDENTITY_KEYyour_key-NACOS_AUTH_IDENTITY_VALUEyour_valueports:-8081:8080-8848:8848-9848:9848networks:-mcpvolumes:-./standalone-logs:/home/nacos/logsnetworks:mcp:external:truecdC:/Users/XXXXX/Desktop/nacos-dockerdockercompose up-d# 访问 http://localhost:8081/nacos (nacos/nacos)第三步启动 Higress说明使用 Higress all-in-one 镜像内置网关、控制台、Redis 等组件。为什么用all-in-one这个版本配置比较简单如果是standalone版本配置十分复杂higress初始化配置需要在wsl命令行中运行其中有个大麻烦是windows和linux的换行符不一样在windws中编辑的*.sh文件在linux中运行需要替换换行符定位换行符位置就花了很多时间。另外在Higress配置时不支持新版本的Nacos所以有趣的时Higress的standalone版本不支持3.x版本的Nacos-standalone只能使用内置的Nacos。all-in-one版本直接在容器端启动跳过初始化配置的步骤。事实证明其实higress版本支持3.2版本的Nacos这里仍然不理解的是在配置standalone版本higress时为什么不能使用外置的Nacos日志显示是nacos协议问题。# higress-allinone/docker-compose.yamlversion:3.8services:higress-ai:image:higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latestcontainer_name:higress-aivolumes:-.:/dataports:-8002:8001# 网关端口-8080:8080# 控制台 MCP 端口-8443:8443# HTTPSnetworks:-mcpdepends_on:-higress-redishigress-redis:image:higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/redis-stack-server:7.4.0-v3container_name:higress-redisports:-6380:6379networks:-mcpnetworks:mcp:external:truecdC:/Users/XXXX/Desktop/higress-allinonedockercompose up-d# 访问 http://localhost:8080 (admin/admin)第四步启动后端服务后端服务使用fastapi-best-architecture 构建拉取源码然后docker启动就可以gitclone https://github.com/fastapi-practices/fastapi-best-architecture.gitdocker-composeup-d详细配置fba请参见。fba快速开始首页地址http://localhost:8000四、配置 MCP Server第五步Nacos 创建 MCP Server打开Nacos 控制台 http://localhost:8081进入AI注册中心菜单点击创建 MCP Server开始配置MCP输入MCP服务名fba_mcp_server输入版本号0.0.1选择SSE协议配置远程服务就是要被MCP服务器访问的API服务选择直连新服务服务地址fba_server端口8001,这里的fba_server是使用容器名相互访问IP的方法。配置安全方案。先新建2个安全方案HTTPBearer和APIkey按照图片中要素填写。为什么是HttpBeareropenapi请求模板中定义好的如果openapi中定义的名称是其他的要跟着改如下面的请求模板中定义的security的id项{ url: /api/v1/sys/configs, method: PUT, headers: [ { key: Content-Type, value: application/json } ], security: { id: HTTPBearer } }默认凭证这是fba发送登陆请求后收到的access_token在 http://localhost:8000/docs#/ 中使用测试登陆/api/v1/auth/login/swagger 请求可以获取。配置这个参数mcp才能通过fba后台认证。构建好安全方案后填写下游安全认证和上游安全认证核心概念下游 (Downstream): 客户端 → 网关 上游 (Upstream): 网关 → 后端服务导入openAPI工具。将之前下载的openapi.json 导入即可。点击发布按钮。第六步配置 Higress MCP 服务源。按照如下内容配置 C:\Users\XXXXX\Desktop\higress-allinone\mcpbridges\default.yaml 文件# mcpbridges/default.yamlapiVersion:networking.higress.io/v1kind:McpBridgemetadata:creationTimestamp:nullmanagedFields:-apiVersion:networking.higress.io/v1fieldsType:FieldsV1fieldsV1:f:spec:f:registries:{}manager:Kubernetes Java Clientoperation:Updatetime:2026-03-31T03:54:26Zname:defaultnamespace:higress-systemresourceVersion:8spec:registries:-domain:127.0.0.1:8001name:higress-consoleport:80type:static-authSecretName:mcp-registry-auth-ljxakdomain:nacosenableMCPServer:truemcpServerBaseUrl:/mcpnacosGroups:-mcp-endpoints-DEFAULT_GROUPnacosNamespaceId:publicname:mcp-registryport:8848type:nacos3status:{}dockerrestart higress-ai也可以在Higrees 创建服务来源按照如图所示配置nacos用户名密码是必填项动手填好即可第七步验证测试importrequestsimportre# 建立 SSE 连接sse_urlhttp://localhost:8080/mcp/fba_mcp_server/sserrequests.get(sse_url,streamTrue,timeout5)session_idNoneforlineinr.iter_lines():iflineandsessionIdinline.decode():matchre.search(rsessionId([a-f0-9-]),line.decode())ifmatch:session_idmatch.group(1)break# 调用工具tool_urlfhttp://localhost:8080/mcp/fba_mcp_server?sessionId{session_id}rrequests.post(tool_url,json{jsonrpc:2.0,id:1,method:tools/call,params:{name:postapiV1AuthLoginSwagger,arguments:{username:admin,password:123456}}},timeout10)print(r.json())也可以在支持MCP功能的Client中使用我这里使用了TraeCN作为测试。手动添加MCP工具json如下:{mcpServers:{fba_mcp_server_all:{url:http://localhost:8080/mcp/fba_mcp_server_all/sse,headers:{X-API-Key:fba-mcp-api-key-2024}}}}五、故障排查坑一Docker 网络不通现象503 Service Unavailable - no healthy upstream解决dockernetwork connect mcp fba_serverdockernetwork inspect mcp# 验证坑二Nacos和Higress 分组不一致 ⭐现象503 或服务发现找不到实例原因Nacos 服务有分组概念默认DEFAULT_GROUP在创建MCP服务时自动加入了mcp_endpoints的组解决确保Higress创建的服务源也要加入mcp_endpoints组坑三服务实例 IP 带协议前缀 ⭐⭐现象网络通了还是 503原因Nacos 实例 IP 不能带http://❌ IP http://fba_server ✅ IP fba_server解决Nacos 控制台 → 服务详情 → 编辑实例去掉http://坑四端口未暴露现象本地能访问外部无法连接解决docker-compose.yaml 暴露 8080 端口坑五客户端认证问题 ⭐⭐⭐现象配置了 API Key但无法连接客户端兼容性客户端SSE headers 支持解决方案Trae / Cursor✅ 支持API Key in headersCherry Studio❌ 不支持IP 白名单或无认证LM Studio⚠️ 有限支持减少工具数量常见错误❌ X-API-Key: Bearer your-key ✅ X-API-Key: your-key ❌ 混淆上下游认证 ✅ 下游验证客户端上游验证后端六、排查流程503 错误 ├─→ Docker 网络 ──→ 不通? ──→ docker network connect ├─→ Nacos Group ──→ 不一致? ──→ 修改配置 ├─→ 实例 IP ──→ 带 http://? ──→ 去掉协议 ├─→ 端口映射 ──→ 未暴露? ──→ 修改 compose └─→ 认证配置 ──→ 客户端不支持? ──→ 换客户端或配白名单七、总结坑位错误示例正确做法网络容器在不同网络docker network connect分组Group 不匹配确保配置一致IP 格式http://host纯主机名host端口未映射 8080暴露端口认证客户端不支持检查兼容性参考Nacos MCP Server 官方文档Higress MCP 网关