企业官网建设流程全解析

1. 存量 REST API 接入 MCP Service 的真实痛点

手里有一套跑了很久的 REST API，接口稳定、文档齐全，但每次想让 AI 工具调用它，就得重新写一遍适配层。这个场景在团队里太常见了：后端接口是给前端和内部服务用的，返回结构、鉴权方式、错误码都是按 HTTP 语义设计的，而 MCP Service 需要的是工具描述、参数 schema、调用入口。两者之间隔着一层协议转换。

Nacos3 加 Higress 的组合正好能填上这层。Nacos3 负责服务注册与配置管理，Higress 作为网关做协议转换和路由转发，把已有的 REST 接口包装成 MCP Service 暴露出去。你不需要改后端一行代码，只需要在 Nacos 里注册服务、在 Higress 里配路由和 MCP 转换规则，AI 工具就能通过标准 MCP 协议调用你的存量接口。

这套方案适合谁？适合已经有 REST API 资产、想让 Claude Code、Cline、Cursor 这类支持 MCP 的 AI 工具直接调用内部接口的团队。也适合想把多个微服务接口统一收口到一个 MCP 入口、集中管理调用凭证的场景。我试过用这套组合把一个订单查询接口转成 MCP Service，整个过程从注册到验证大概二十分钟，比写适配层快得多。

调用凭证这块单独说。存量 API 通常有自己的鉴权体系，可能是 API Key、可能是 JWT、也可能是内部签名。MCP Service 暴露出去之后，AI 工具侧需要一套统一的 Key 来调用。TaoToken 在这里的角色是统一 Key 通道：你可以在 TaoToken 控制台创建 API Key，把上游鉴权信息配置在通道里，AI 工具侧只认 TaoToken 的 Key，后端鉴权由通道透传。这样换后端、换鉴权方式的时候，AI 工具侧的配置不用动。

下面按实际落地顺序走一遍：先起 Nacos3 和 Higress，再注册服务、配 MCP 转换，最后用 MCP Inspector 验证调用。每一步都给可复制的配置片段。

2. Nacos3 与 Higress 环境搭建：Docker Compose 起服务与 Redis 依赖

Nacos3 和 Higress 都需要持久化和缓存支撑。Nacos3 用 MySQL 存配置和服务数据，Higress 用 Redis 做限流和会话缓存。先把 Docker network 建好，三个服务放同一个网络里，互相用容器名通信。

创建共享网络：

docker network create mcp

Nacos3 的 compose 文件，用 MySQL 作为数据源。注意NACOS_AUTH_TOKEN需要是 Base64 编码的字符串，长度有要求，测试环境可以直接用下面这个：

version: '3' services: nacos3: image: nacos/nacos-server:v3.1.1 container_name: nacos-standalone-mysql restart: always ports: - "8848:8848" - "9848:9848" - "8080:8080" environment: - MODE=standalone - NACOS_AUTH_TOKEN=ZTAzYWVjMWItMjU2Yy00YjNhLWI2NmEtYWJjZjI1NDk3OGZj - NACOS_AUTH_IDENTITY_KEY=nacos - NACOS_AUTH_IDENTITY_VALUE=nacos - SPRING_DATASOURCE_PLATFORM=mysql - MYSQL_SERVICE_HOST=192.168.42.129 - MYSQL_SERVICE_DB_NAME=nacos_config - MYSQL_SERVICE_PORT=3306 - MYSQL_SERVICE_USER=root - MYSQL_SERVICE_PASSWORD=123456 - MYSQL_SERVICE_DB_PARAM=characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true volumes: - ./logs/:/home/nacos/logs - ./data/:/home/nacos/data - ./conf/:/home/nacos/conf networks: - mcp networks: mcp: external: true

MySQL 里需要先建nacos_config库，然后执行 Nacos3 的初始化 SQL。核心表包括config_info、config_info_gray、config_tags_relation、group_capacity、his_config_info、tenant_capacity、tenant_info、users、roles、permissions。这些表结构在 Nacos 官方仓库的mysql-schema.sql里都有，直接导入即可。注意config_info_gray是 2.5.0 之后新增的灰度配置表，Nacos3 需要它。

Higress 的 compose 文件，用 all-in-one 镜像，映射 8080 到宿主机 8081，控制台在 8001：

version: '3' services: higress-gateway: image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest container_name: higress-gateway restart: always ports: - "8081:8080" - "8001:8001" - "8443:8443" volumes: - ./data:/data environment: - O11Y=on networks: - mcp networks: mcp: external: true

Redis 用 4.0.11 版本，Higress 的限流插件依赖它：

version: "3" services: redis: image: redis:4.0.11 ports: - 6379:6379 volumes: - "./redis.conf:/usr/local/etc/redis/redis.conf" - "./data:/data" command: redis-server /usr/local/etc/redis/redis.conf

三个服务起来之后，Nacos 控制台在http://你的IP:8080/，首次访问要设 admin 密码，测试环境用nacos/nacos就行。Higress 控制台在http://你的IP:8001/，同样设 admin 密码，测试用admin/admin。

这里有个容易踩的坑：Nacos3 的 9848 端口是 gRPC 端口，客户端连接时需要同时能访问 8848 和 9848。如果你在容器里跑客户端，网络要通；如果从宿主机连，两个端口都要映射出来。另外 MySQL 连接参数里的allowPublicKeyRetrieval=true在 MySQL 8 上必须加，否则会报公钥检索失败。

环境就绪后，先别急着配 MCP，去 Nacos 控制台确认服务列表是空的、配置列表是空的，说明初始化干净。然后开始注册存量 API 对应的服务。

3. 存量 API 注册与 Higress MCP 转换配置：路由、协议转换与鉴权透传

这一步是核心。假设你有一个存量 REST API，比如订单查询接口GET /api/order/{orderId}，返回 JSON。目标是把它包装成 MCP Service，让 AI 工具能通过 MCP 协议调用。

先在 Nacos 里创建 MCP Server。进入 Nacos 控制台，找到 MCP 管理入口，新建一个 MCP Server，名称比如order-mcp，类型选 SSE。然后在里面创建服务，服务指向你的存量 API 地址。再创建 Tool，Tool 是对外暴露的工具描述，包括名称、描述、参数 schema。

Tool 的参数 schema 用 JSON Schema 描述。比如订单查询工具：

{ "name": "query_order", "description": "根据订单ID查询订单详情", "inputSchema": { "type": "object", "properties": { "orderId": { "type": "string", "description": "订单唯一标识" } }, "required": ["orderId"] } }

Nacos 里配好之后，去 Higress 控制台配路由和 MCP 转换。Higress 的 MCP 转换能力通过插件实现，需要在路由上挂载mcp-server插件。路由匹配路径设为/mcp/order-mcp/sse，上游指向 Nacos 里注册的服务。

Higress 的路由配置可以用控制台可视化配，也可以直接写 YAML。可复制的路由片段：

apiVersion: networking.higress.io/v1 kind: McpBridge metadata: name: order-mcp-bridge namespace: higress-system spec: registries: - name: nacos-order type: nacos3 domain: nacos-standalone-mysql port: 8848 nacosGroups: - DEFAULT_GROUP

然后在 Higress 里创建路由，匹配/mcp/order-mcp/sse，上游服务选 Nacos 注册的服务，插件配置里开启 MCP 转换：

apiVersion: networking.higress.io/v1 kind: HttpRoute metadata: name: order-mcp-route namespace: higress-system spec: hostnames: - "*" rules: - matches: - path: type: PathPrefix value: /mcp/order-mcp/sse backendRefs: - name: order-service port: 8080 filters: - type: extension extension: name: mcp-server config: serverName: order-mcp protocol: sse

鉴权透传这块要单独处理。存量 API 可能有自己的鉴权头，比如Authorization: Bearer xxx或者X-API-Key: xxx。AI 工具侧调用 MCP Service 时带的是 TaoToken 的 Key。你需要在 Higress 里配一个请求头转换插件，把 TaoToken 的 Key 映射成后端认识的鉴权头。

TaoToken 的统一 Key 通道在这里的作用是：AI 工具侧只配置 TaoToken 的 Base URL 和 API Key，Higress 收到请求后，通过 TaoToken 通道把请求转发到后端，鉴权信息由通道配置透传。这样后端换鉴权方式时，只需要改 TaoToken 通道配置，AI 工具侧不动。

TaoToken 的接入信息：

• 官网：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API 地址：https://taotoken.net/api
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

在 TaoToken 控制台创建 API Key 后，把上游鉴权信息配在通道里。Higress 侧的路由配置里，请求头转换规则写成：

- type: requestHeaderModifier requestHeaderModifier: set: - name: X-Upstream-Auth value: "Bearer ${TAOTOKEN_UPSTREAM_KEY}"

这样 AI 工具调用时只需要带 TaoToken 的 Key，Higress 自动替换成后端鉴权头。注意${TAOTOKEN_UPSTREAM_KEY}是占位符，实际值从 TaoToken 通道配置里取，不要硬编码在 YAML 里。

配置完成后，Higress 会把 Nacos 里注册的 MCP Server 暴露成 SSE 端点。访问路径规则是：

http://{Higress的IP}:{8080映射到宿主机的端口}/{Higress创建服务时配置的路径}/{Nacos中创建的MCP Server名称}/sse

按上面的配置，完整地址是http://192.168.42.131:8081/mcp/order-mcp/sse。

4. 用 MCP Inspector 验证调用：从 REST API 到 MCP Service 的完整链路

配置配好了，得验证链路通不通。MCP Inspector 是官方提供的调试工具，能直观看到 MCP Service 暴露了哪些工具、参数 schema 对不对、调用返回什么。

先装 Node.js，建议用 nvm 管理版本，我用的 v24.9.0。然后直接跑：

npx @modelcontextprotocol/inspector

启动后会输出一个 URL，复制到浏览器打开。在 Inspector 界面里，Transport 选 SSE，URL 填http://192.168.42.131:8081/mcp/order-mcp/sse，点 Connect。

连接成功后，左侧会列出所有可用的 Tool。你应该能看到query_order这个工具，点进去能看到它的参数 schema。在参数框里填orderId，比如ORD-2024-001，点 Run。

如果链路正常，右侧会返回后端 REST API 的响应。这时候你看到的是 MCP 协议包装后的结果，但底层调用的还是你原来的 REST 接口。

验证的时候注意几个点。第一，SSE 连接是长连接，Inspector 里如果显示连接成功但工具列表为空，检查 Higress 的 MCP 插件是否真的挂载到了路由上。第二，调用返回 401 的话，说明鉴权透传没生效，去 Higress 的请求头转换配置里检查 TaoToken 通道的 Key 是否正确。第三，如果返回reading choices之类的错误，通常是后端返回结构不符合 MCP 转换插件的预期，需要在 Higress 里配响应转换规则。

一次成功的调用验证动作是这样的：Inspector 里 Connect 成功，工具列表出现query_order，填入orderId后 Run，右侧返回订单 JSON 数据，状态码 200。这时候整条链路就通了：AI 工具 → TaoToken 统一 Key → Higress MCP 转换 → Nacos 服务发现 → 存量 REST API。

如果你用的是 Claude Code 或者 Cline，配置方式类似。Claude Code 的 MCP 配置在~/.claude/settings.json或者项目级的.mcp.json里，Cline 在 VS Code 设置里配 MCP Servers。核心三件套是 Base URL、Key、Model ID。以 Claude Code 为例：

{ "mcpServers": { "order-mcp": { "type": "sse", "url": "http://192.168.42.131:8081/mcp/order-mcp/sse", "headers": { "Authorization": "Bearer ${TAOTOKEN_API_KEY}" } } } }

这里的${TAOTOKEN_API_KEY}是 TaoToken 控制台创建的 Key。Claude Code 启动时会读取这个配置，连接 MCP Service。连接成功后，你在 Claude Code 里就能直接让 AI 调用query_order工具了。

5. 常见报错排查：401、local proxy failed、reading choices 与 OAuth 问题

这套链路涉及 Nacos、Higress、TaoToken、MCP Inspector 多个组件，出错的地方比较多。按实际踩过的坑整理几个高频报错。

401 Unauthorized。最常见。分两种情况：一种是 MCP Inspector 连接时就 401，说明 Higress 的 MCP 端点鉴权没配对，检查 TaoToken 通道的 Key 是否有效、请求头转换规则是否把 Key 带上了。另一种是调用工具时 401，说明后端 REST API 鉴权失败，检查 Higress 请求头转换里X-Upstream-Auth的值是否正确映射到了后端认识的鉴权头。TaoToken 通道配置里，上游鉴权信息要和后端 API 的要求一致，比如后端要Bearer前缀，通道里就得带上。

local proxy failed。这个报错通常出现在 MCP Inspector 连接 SSE 端点时。原因是 Inspector 本地代理无法访问你填的 URL。检查两点：一是 Higress 的 8081 端口是否真的映射出来了，docker ps看端口映射；二是 URL 里的 IP 是不是宿主机可达的 IP，别填localhost，因为 Inspector 跑在宿主机上，localhost指向的是宿主机自己，如果 Higress 在容器里，要用宿主机 IP。另外防火墙要放行 8081 端口。

reading choices 报错。这个报错来自 MCP 转换插件解析后端响应时。MCP 协议期望的响应结构是特定的 JSON 格式，如果你的存量 API 返回的是裸数组或者非标准结构，插件解析会失败。解决办法是在 Higress 里配响应转换，把后端响应包装成 MCP 期望的格式。比如后端返回{"data": {...}}，MCP 插件可能期望{"content": [{"type": "text", "text": "..."}]}，中间需要一层转换。

OAuth 相关报错。如果你的存量 API 用的是 OAuth2 鉴权，Higress 侧需要配 OAuth 插件做 token 校验和透传。常见报错是invalid_token或者token expired。检查 TaoToken 通道里配置的 OAuth 凭证是否过期，以及 Higress 的 OAuth 插件是否把 token 正确传递到了后端。如果后端要求 token 放在特定 header 里，请求头转换规则要对应调整。

Nacos 服务注册不上。检查 Nacos3 的 9848 gRPC 端口是否可达。Nacos3 客户端注册服务时走 gRPC，如果 9848 不通，服务注册会失败但控制台可能不报明显错误。另外检查 MySQL 连接参数，allowPublicKeyRetrieval=true在 MySQL 8 上必须加。

Higress 控制台看不到 Nacos 服务。检查 McpBridge 配置里的domain是不是 Nacos 容器名，port是不是 8848，nacosGroups是不是DEFAULT_GROUP。如果 Nacos 和 Higress 不在同一个 Docker network 里，domain要改成 Nacos 的宿主机 IP。

排查的时候按链路顺序来：先确认 Nacos 里服务注册成功，再确认 Higress 能发现 Nacos 服务，再确认 MCP 端点能连上，最后确认工具调用能返回。每一步都有对应的日志可以看，Higress 的日志在容器里/var/log/higress/下，Nacos 的日志在./logs/下。

6. 统一 Key 通道下的长期调用与 Coding Plan 接入

链路通了之后，日常使用就是 AI 工具侧配置 MCP Service 地址和 TaoToken Key。但如果你有多个存量 API、多个 MCP Service，每个都配一遍 Key 会很乱。TaoToken 的统一 Key 通道在这里的价值就体现出来了：所有 MCP Service 共用一套 TaoToken Key，后端鉴权差异在通道里消化。

对于长期编码和 Agent 场景，TaoToken 的 Coding Plan 提供了更稳定的调用配额和通道管理。你可以在控制台里把多个 MCP Service 挂到同一个通道下，AI 工具侧只认一个 Base URL 和一个 Key。换后端、加服务、改鉴权，都在通道侧完成，AI 工具配置不动。

Coding Plan 的接入地址：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite

模型对话调试入口：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite

控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite

实际用下来，这套组合的维护成本比写适配层低。存量 API 不用改，Nacos 里加个服务注册，Higress 里配个路由和 MCP 转换，TaoToken 里配个通道，AI 工具侧配个 MCP Server 地址。四步走完，一个新的 MCP Service 就上线了。后面接口有变动，改 Nacos 里的 Tool schema 就行，Higress 和 AI 工具侧都不用动。

如果你团队里已经有 Nacos 和 Higress 在用，这套方案几乎是零额外成本。如果没有，Docker Compose 起三个容器也就几分钟的事。关键是先把一个接口跑通，验证链路没问题，再批量接其他接口。