1. 存量 REST API 轉(zhuǎn) MCP 的真實(shí)痛點(diǎn)與場(chǎng)景拆解手里有一套跑了很久的 Spring Boot 圖書服務(wù)接口穩(wěn)定、日志清晰、監(jiān)控齊全但每次想讓 AI Agent 調(diào)用它就得寫一堆膠水代碼要么在 Agent 側(cè)硬編碼 HTTP 請(qǐng)求要么單獨(dú)寫一個(gè) Function Calling 的適配層。接口一多參數(shù)映射、鑒權(quán)、錯(cuò)誤處理全散落在各個(gè)地方改一個(gè)字段要?jiǎng)尤膫€(gè)文件。MCPModel Context Protocol出現(xiàn)之后思路變了把存量 RESTful API 直接聲明成 MCP Server讓 AI Agent 通過(guò)標(biāo)準(zhǔn)協(xié)議發(fā)現(xiàn)工具、調(diào)用工具。問題在于存量服務(wù)不會(huì)為了 MCP 重寫一遍我們需要一個(gè)中間層來(lái)完成「HTTP 接口 → MCP Tool」的協(xié)議轉(zhuǎn)換。這就是 Nacos3 Higress 組合的用武之地。Nacos3 負(fù)責(zé)服務(wù)注冊(cè)與發(fā)現(xiàn)把已有的 book-service 注冊(cè)進(jìn)去Higress 作為 AI 網(wǎng)關(guān)從 Nacos 拉取服務(wù)列表把具體的 REST 接口映射成 MCP Tools對(duì)外暴露 SSE 或 streamableHTTP 端點(diǎn)。整個(gè)鏈路里存量代碼幾乎不用改只需要在 Nacos 控制臺(tái)聲明 MCP 服務(wù)、在 Higress 里配置協(xié)議轉(zhuǎn)換模板。適合誰(shuí)看手上有一批 RESTful 接口、想讓 AI Agent 直接調(diào)用的后端同學(xué)正在做企業(yè)內(nèi)部工具鏈 AI 化、又不想大改存量系統(tǒng)的架構(gòu)同學(xué)以及想搞清楚 MCP 協(xié)議轉(zhuǎn)換到底怎么落地、不想只看概念的同學(xué)。這篇會(huì)從 Nacos3 安裝配置開始到 Higress 部署、Redis 掛載、MCP 服務(wù)聲明、Tool 映射、協(xié)議轉(zhuǎn)換 JSON 配置最后用 curl 驗(yàn)證工具列表和調(diào)用鏈路。每一步都給可復(fù)制的配置片段踩過(guò)的坑也會(huì)標(biāo)出來(lái)。核心檢索詞先明確Nacos3 服務(wù)發(fā)現(xiàn)、Higress MCP 網(wǎng)關(guān)、存量 API 轉(zhuǎn) MCP Server、TaoToken 統(tǒng)一 Key 通道。這四個(gè)詞貫穿全文后面每個(gè)環(huán)節(jié)都會(huì)對(duì)應(yīng)到具體操作。2. TaoToken 統(tǒng)一 Key 通道的前置準(zhǔn)備與接入定位在講 Nacos 和 Higress 的具體配置之前先把 TaoToken 的角色說(shuō)清楚。很多同學(xué)會(huì)問MCP Server 都搭好了為什么還要接 TaoToken原因在于鑒權(quán)和調(diào)用入口的統(tǒng)一。存量 API 轉(zhuǎn)成 MCP 之后調(diào)用方可能是 Cursor、Cherry Studio、Cline也可能是你自己寫的 Agent。每個(gè)客戶端的 Key 管理方式不一樣有的走 Header有的走 Query有的走 OAuth。如果每個(gè) MCP Server 都單獨(dú)配一套鑒權(quán)維護(hù)成本會(huì)迅速膨脹。TaoToken 在這里承擔(dān)的是統(tǒng)一 Key 通道的角色所有 MCP 調(diào)用走同一個(gè) Base URL用同一套 API Key模型側(cè)和工具側(cè)共用一套憑證體系。你不需要在每個(gè) MCP Server 里重復(fù)配置鑒權(quán)邏輯只需要在 TaoToken 側(cè)管理 Key在 Higress 側(cè)做轉(zhuǎn)發(fā)。前置準(zhǔn)備分三塊第一塊是 TaoToken 側(cè)的 Key。訪問 https://taotoken.net/api-keys 創(chuàng)建 API Key這個(gè) Key 后面會(huì)用在 MCP 客戶端的配置里。注意 Key 只在創(chuàng)建時(shí)顯示一次復(fù)制后妥善保存。第二塊是模型側(cè)的準(zhǔn)備。如果你打算讓 Agent 在調(diào)用 MCP 工具的同時(shí)還能做推理需要確認(rèn)模型通道可用?？梢缘?https://taotoken.net/models 看一下當(dāng)前支持的模型列表選一個(gè)適合工具調(diào)用的模型。工具調(diào)用對(duì)模型的 Function Calling 能力有要求不是所有模型都支持。第三塊是文檔側(cè)的準(zhǔn)備。MCP 接入的完整參數(shù)說(shuō)明在 https://taotoken.net/doc建議先過(guò)一遍特別是 Base URL 的格式和 Header 的寫法。很多 401 報(bào)錯(cuò)都是因?yàn)?Base URL 多寫了斜杠或者少寫了版本路徑。這里給一個(gè)最小可用的 MCP 客戶端配置片段后面驗(yàn)證階段會(huì)用到{ mcpServers: { book-service-mcp: { url: http://127.0.0.1:8001/mcp/book-mcp/sse, headers: { Authorization: Bearer sk-你的TaoTokenKey } } } }注意 url 里的路徑結(jié)構(gòu)/mcp/{MCP服務(wù)名}/sseMCP 服務(wù)名是你在 Nacos 里聲明時(shí)填的那個(gè)。headers 里的 Authorization 是 TaoToken 的 Key格式是Bearer加 Key 本身。如果你用的是 Cline 或者 Claude Code 這類支持 MCP 的編碼工具配置方式類似但字段名可能不同。Cline 的 MCP 配置在 settings 里Claude Code 的配置在~/.claude/settings.json或者項(xiàng)目級(jí)的.mcp.json。不管哪個(gè)客戶端三件套不能少Base URL、Key、Model ID。Base URL 指向 TaoToken 的 API 地址Key 用剛才創(chuàng)建的Model ID 選一個(gè)支持工具調(diào)用的。TaoToken 的 Coding Plan 適合長(zhǎng)期編碼場(chǎng)景如果你打算把 MCP 工具鏈用在日常開發(fā)里可以到 https://taotoken.net/coding-plan 看一下套餐說(shuō)明。模型對(duì)話調(diào)試入口在 https://taotoken.net/chat驗(yàn)證模型連通性的時(shí)候可以用。前置準(zhǔn)備做完接下來(lái)進(jìn)入 Nacos3 的安裝和配置。3. Nacos3 安裝配置與 Higress 網(wǎng)關(guān)部署的可復(fù)制片段3.1 Nacos3 安裝與 application.properties 配置Nacos3 的安裝比 Nacos2 多了一個(gè) AI MCP Registry 的端口配置這是它原生支持 MCP 服務(wù)注冊(cè)的關(guān)鍵。下載解壓后修改conf/application.properties下面是我實(shí)測(cè)可用的配置片段nacos.server.main.port8848 spring.datasource.platformmysql db.num1 db.url.0jdbc:mysql://127.0.0.1:3306/nacos?useUnicodetruecharacterEncodingUTF-8autoReconnecttrue db.user.0root db.password.0123456 nacos.config.push.maxRetryTime50 nacos.naming.empty-service.auto-cleantrue nacos.naming.empty-service.clean.initial-delay-ms50000 nacos.naming.empty-service.clean.period-time-ms30000 nacos.ai.mcp.registry.port9080 nacos.server.contextPath/nacos nacos.console.port8090 nacos.console.contextPath nacos.console.remote.server.context-path/nacos nacos.core.auth.system.typenacos nacos.core.auth.enabledfalse nacos.core.auth.admin.enabledfalse nacos.core.auth.plugin.nacos.token.enabledfalse nacos.core.auth.console.enabledfalse nacos.core.auth.caching.enabledfalse nacos.core.auth.server.identity.key123 nacos.core.auth.server.identity.value123 nacos.core.auth.plugin.nacos.token.cache.enablefalse nacos.core.auth.plugin.nacos.token.expire.seconds18000 nacos.core.auth.plugin.nacos.token.secret.keyVGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg nacos.core.api.compatibility.console.enabledtrue nacos.istio.mcp.server.enabledtrue nacos.k8s.sync.enabledfalse nacos.deployment.typemerged幾個(gè)關(guān)鍵點(diǎn)說(shuō)明。nacos.ai.mcp.registry.port9080是 MCP 注冊(cè)端口Higress 會(huì)通過(guò)這個(gè)端口拉取 MCP 服務(wù)列表。nacos.console.port8090是控制臺(tái)端口默認(rèn)是 8848這里改成 8090 是為了避免和主端口沖突。nacos.core.auth.enabledfalse在本地開發(fā)環(huán)境可以關(guān)掉鑒權(quán)生產(chǎn)環(huán)境記得打開并配置好 token secret key。MySQL 地址要改成你自己的。如果本地沒有 MySQL可以用 Docker 快速起一個(gè)docker run -d --name nacos-mysql -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD123456 \ -e MYSQL_DATABASEnacos \ mysql:8.0啟動(dòng) Nacos 后訪問http://127.0.0.1:8090/確認(rèn)控制臺(tái)正常。如果頁(yè)面打不開先看日志里有沒有數(shù)據(jù)庫(kù)連接失敗的報(bào)錯(cuò)。3.2 Higress 與 Redis 的 Docker 部署Higress 我用的是 all-in-one 鏡像在 WSL2 的 Docker Desktop 里跑。先創(chuàng)建一個(gè)數(shù)據(jù)目錄然后執(zhí)行docker run -d --name higress-ai \ -v C:\software\higress\higressData:/data \ -p 8001:8001 -p 8081:8080 -p 8443:8443 \ higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest端口映射說(shuō)明8001 是 Higress 控制臺(tái)端口8081 映射到容器內(nèi)的 8080 是網(wǎng)關(guān)數(shù)據(jù)面端口8443 是 HTTPS 端口。訪問http://127.0.0.1:8001/進(jìn)入控制臺(tái)第一次登錄會(huì)初始化賬號(hào)密碼。Redis 是 Higress 做 MCP 會(huì)話管理必需的不裝的話 MCP 的 SSE 連接會(huì)斷。執(zhí)行docker run -d --name higress-redis \ -p 6379:6379 \ higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/redis-stack-server:7.4.0-v3裝完之后在 Higress 控制臺(tái)里配置 Redis 連接信息地址填host.docker.internal:6379或者你宿主機(jī)的 IP。配置完記得重啟 Higress 容器否則不生效。3.3 Higress 接入 Nacos 與 MCP 開關(guān)在 Higress 控制臺(tái)的「服務(wù)來(lái)源」里添加 Nacos地址填host.docker.internal:8848命名空間用 public。然后在「AI 網(wǎng)關(guān)」里開啟 MCP Server 功能選擇 Redis 作為會(huì)話存儲(chǔ)。這一步的配置會(huì)生成一段 JSON類似{ mcpServerEnabled: true, redisConfig: { host: host.docker.internal, port: 6379, db: 0 }, nacosConfig: { serverAddr: host.docker.internal:8848, namespace: public } }配置保存后重啟容器Higress 就能從 Nacos 拉取服務(wù)列表了。4. 存量 API 聲明為 MCP Tool 的協(xié)議轉(zhuǎn)換配置與驗(yàn)證4.1 服務(wù)注冊(cè)到 Nacos3先準(zhǔn)備一個(gè)簡(jiǎn)單的 Spring Boot 圖書服務(wù)注冊(cè)到 Nacos。pom.xml 關(guān)鍵依賴dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependencyapplication.ymlserver: port: 8090 spring: application: name: book-service cloud: nacos: discovery: server-addr: localhost:8848 username: nacos password: nacosController 里定義三個(gè)接口按作者查、按分類查、查全部。啟動(dòng)后到 Nacos 控制臺(tái)的服務(wù)列表里確認(rèn)book-service已經(jīng)注冊(cè)上來(lái)。4.2 在 Nacos 聲明 MCP 服務(wù)在 Nacos 控制臺(tái)的「MCP 管理」里新建 MCP 服務(wù)。關(guān)鍵字段MCP 服務(wù)名填book-mcp協(xié)議類型選sse轉(zhuǎn) MCP 服務(wù)選http后端服務(wù)選「使用已有服務(wù)」服務(wù)引用選book-service描述填「圖書查詢服務(wù)」版本填1.0.0。填完點(diǎn)發(fā)布。4.3 將 REST API 映射為 MCP Tools在 MCP 列表里找到book-mcp點(diǎn)編輯添加 Tool。以「根據(jù)作者查詢圖書」為例Tool 名稱填getBooksByAuthor描述填「根據(jù)作者姓名查詢圖書列表」輸入?yún)?shù)添加authorName類型 string。協(xié)議轉(zhuǎn)換配置填{ requestTemplate: { url: /books/author, argsToUrlParam: true, method: GET }, responseTemplate: { body: {{ .body | raw }} }, argsPosition: { authorName: query } }這段配置的含義requestTemplate.url指定后端路徑argsToUrlParam為 true 時(shí)把 query 參數(shù)拼到 URL 上method是 GET。responseTemplate.body用{{ .body | raw }}保留原始 JSON 格式。argsPosition聲明authorName放在 query 里。按同樣方式配置另外兩個(gè) ToolgetBooksByCategory對(duì)應(yīng)/books/category參數(shù)categorygetAllBooks對(duì)應(yīng)/books/all無(wú)參數(shù)。配置完點(diǎn)發(fā)布。4.4 用 curl 驗(yàn)證 MCP 工具列表與調(diào)用鏈路MCP 服務(wù)發(fā)布后先驗(yàn)證工具列表。SSE 端點(diǎn)需要先建立連接拿 session再用 session 發(fā)請(qǐng)求。簡(jiǎn)化驗(yàn)證可以用 streamableHTTP 端點(diǎn)curl -X POST http://127.0.0.1:8001/mcp/book-mcp/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoTokenKey \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }正常返回會(huì)列出三個(gè) Tool 的定義包含 name、description、inputSchema。如果返回 401檢查 Authorization 頭如果返回 404檢查 MCP 服務(wù)名和路徑。調(diào)用工具curl -X POST http://127.0.0.1:8001/mcp/book-mcp/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoTokenKey \ -d { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: getBooksByAuthor, arguments: { authorName: Tolkien } } }預(yù)期返回包含兩本書的 JSON 數(shù)組。如果返回空數(shù)組檢查后端服務(wù)的參數(shù)名是否匹配authorName要和 Controller 里的RequestParam(authorName)一致。在 Cherry Studio 或 Cursor 里配置 MCP Serverurl 填http://127.0.0.1:8001/mcp/book-mcp/sseheaders 加 TaoToken 的 Key。連接成功后在對(duì)話里問「幫我查一下 Tolkien 寫的書」Agent 會(huì)自動(dòng)調(diào)用getBooksByAuthor工具并返回結(jié)果。5. 本篇常見報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized最常見的報(bào)錯(cuò)。原因通常是三個(gè)Key 沒傳、Key 格式不對(duì)、Key 過(guò)期。檢查 Header 里是不是Authorization: Bearer sk-xxx注意 Bearer 后面有一個(gè)空格。如果用的是 TaoToken 的 Key確認(rèn) Key 沒有多余的空格或換行。到 https://taotoken.net/api-keys 重新生成一個(gè) Key 試試。還有一種情況是 Higress 側(cè)的鑒權(quán)插件和 TaoToken 的 Key 沖突。如果 Higress 開了 JWT 鑒權(quán)需要把 MCP 路徑加到白名單里讓 TaoToken 的 Key 透?jìng)鞯胶蠖恕?.2 local proxy failed這個(gè)報(bào)錯(cuò)通常出現(xiàn)在 Higress 轉(zhuǎn)發(fā)到 Nacos 服務(wù)的時(shí)候。原因可能是 Nacos 服務(wù)實(shí)例的 IP 是容器內(nèi) IPHigress 容器訪問不到。解決辦法在 Nacos 服務(wù)注冊(cè)時(shí)指定宿主機(jī) IP或者在 Higress 的 Nacos 配置里把serverAddr改成宿主機(jī)可達(dá)的地址。WSL2 環(huán)境下host.docker.internal通常能解析到宿主機(jī)但 Nacos 注冊(cè)的服務(wù) IP 如果是172.x.x.x的容器 IPHigress 就訪問不到。檢查方式在 Higress 容器里curl http://book-service-ip:8090/books/all看能不能通。不通的話在 Spring Boot 配置里加spring.cloud.nacos.discovery.ip宿主機(jī)IP。5.3 reading choices 報(bào)錯(cuò)這個(gè)報(bào)錯(cuò)一般出現(xiàn)在模型側(cè)不是 MCP 側(cè)。原因是模型返回的 tool_calls 格式不完整或者 MCP 返回的結(jié)果格式不符合模型預(yù)期。檢查 MCP Tool 的responseTemplate.body是不是{{ .body | raw }}如果寫成{{ .body }}可能會(huì)被轉(zhuǎn)義導(dǎo)致 JSON 解析失敗。另外確認(rèn)模型支持 Function Calling不支持的話換一個(gè)模型。5.4 OAuth 相關(guān)報(bào)錯(cuò)如果 MCP 客戶端配置里帶了 OAuth 相關(guān)字段但 TaoToken 的 Key 是 Bearer 模式會(huì)報(bào) OAuth 校驗(yàn)失敗。把 OAuth 配置去掉只用 Authorization Header。Claude Code 的配置里如果出現(xiàn)oauth字段刪掉改成{ mcpServers: { book-mcp: { url: http://127.0.0.1:8001/mcp/book-mcp/sse, headers: { Authorization: Bearer sk-你的TaoTokenKey } } } }Codex 的auth.json里如果配了 OAuth也要改成 API Key 模式。三件套確認(rèn)Base URL 指向 TaoToken 的 API 地址Key 用 Bearer 格式Model ID 選支持工具調(diào)用的。5.5 MCP 服務(wù)列表為空Higress 控制臺(tái)里看不到 Nacos 注冊(cè)的 MCP 服務(wù)。檢查 Nacos 的nacos.ai.mcp.registry.port9080是否配置Higress 的 Nacos 地址是否指向正確的端口。另外確認(rèn) Nacos 的 MCP 服務(wù)已經(jīng)發(fā)布草稿狀態(tài)不會(huì)同步到 Higress。6. 從驗(yàn)證到長(zhǎng)期使用TaoToken 通道下的 MCP 調(diào)用建議MCP 工具鏈跑通之后日常使用有幾個(gè)點(diǎn)值得注意。第一Key 的輪換。TaoToken 的 Key 支持多創(chuàng)建幾個(gè)不同客戶端用不同的 Key方便排查問題。如果某個(gè) Key 泄露單獨(dú)吊銷不影響其他客戶端。第二MCP 服務(wù)的版本管理。Nacos 里聲明 MCP 服務(wù)時(shí)填的版本號(hào)建議和存量 API 的版本對(duì)齊。接口有變更時(shí)新建一個(gè) MCP 服務(wù)版本而不是直接改舊的避免正在使用的 Agent 突然調(diào)不到工具。第三調(diào)用日志。Higress 的訪問日志里能看到每次 MCP 調(diào)用的請(qǐng)求和響應(yīng)排查問題時(shí)很有用。日志默認(rèn)在容器內(nèi)的/var/log/higress/下可以掛載出來(lái)。第四模型選擇。工具調(diào)用對(duì)模型的 Function Calling 能力有要求實(shí)測(cè)下來(lái)支持工具調(diào)用的模型在參數(shù)提取和結(jié)果整合上差異明顯?？梢缘?https://taotoken.net/models 對(duì)比一下選一個(gè)適合自己場(chǎng)景的。第五長(zhǎng)期編碼場(chǎng)景。如果你打算把 MCP 工具鏈用在日常編碼里比如讓 Agent 查內(nèi)部文檔、查數(shù)據(jù)庫(kù)、調(diào)內(nèi)部 APITaoToken 的 Coding Plan 在成本和穩(wěn)定性上更適合長(zhǎng)期使用。入口在 https://taotoken.net/coding-plan。最后給一個(gè)完整的 MCP 客戶端配置模板把 Base URL、Key、Model ID 三件套都帶上{ mcpServers: { book-mcp: { url: http://127.0.0.1:8001/mcp/book-mcp/sse, headers: { Authorization: Bearer sk-你的TaoTokenKey } } }, model: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, modelId: claude-sonnet-4-20250514 } }這套配置在 Cursor、Cline、Cherry Studio 里都能用字段名可能略有差異但核心三件套不變。MCP 接入文檔在 https://taotoken.net/doc遇到配置問題可以先查文檔。整個(gè)鏈路跑通之后存量 API 不用改一行代碼就能被 AI Agent 通過(guò)標(biāo)準(zhǔn) MCP 協(xié)議調(diào)用。Nacos3 負(fù)責(zé)服務(wù)發(fā)現(xiàn)Higress 負(fù)責(zé)協(xié)議轉(zhuǎn)換TaoToken 負(fù)責(zé)統(tǒng)一鑒權(quán)和調(diào)用入口。這套組合在內(nèi)部工具鏈 AI 化的場(chǎng)景里落地成本比想象中低很多。