1. 本地大模型应用为什么总在 MCP 调用上卡住
本地大模型应用最吸引人的地方，是数据不出内网、推理延迟可控、断网也能跑。但真正把 ollama 和 MCP 工具调用串起来时，很多人会卡在同一个地方：模型能聊天，却调不动工具；或者工具能单独跑，模型却收不到返回。这个问题的本质，是 solon-ai 里 MCP endpoint 的配置和鉴权链路没有对齐。
solon-ai 是 Solon 生态里做大模型接入的模块，它把 ChatModel、FunctionTool、MCP Client 这些概念封装得比较轻。MCP 则是模型和外部工具之间的协议层，负责把「查天气」「查订单」这类业务能力暴露给模型。ollama 负责本地推理，MCP 负责工具调用，solon-ai 负责把两者粘起来。三者缺一，链路就断。
我试过在本地同时起两个 Solon 工程：一个 my-mcp-server 发布工具，一个 my-llm-server 做对话入口。默认配置下，MCP endpoint 指向 localhost:8002/mcp/sse，ollama 指向局域网里的 11434。这套组合在纯内网能跑通，但一旦要把 MCP 通道换成统一 Key/API 通道，比如改到 TaoToken，就会遇到 endpoint 格式、鉴权头、channel 类型三处不一致的问题。
这篇文章面向的是已经在用 solon-ai 做本地大模型应用、但 MCP 调用链路不稳的开发者。你会看到完整的 pom 依赖、app.yml 配置、McpClientProvider 注入方式，以及把 endpoint 改到 TaoToken 后的连通性验证动作。重点不是注册流程，而是配置片段和排障对照。
适合谁看：有 Java 和 Solon 基础、本地已经跑过 ollama、想让模型通过 MCP 调用业务工具的人。如果你还没起过 ollama，建议先把ollama run qwen3跑通再往下看。
2. TaoToken 在 solon-ai MCP 链路里的前置准备
在改 endpoint 之前，先把 TaoToken 这条通道理解清楚。TaoToken 提供的是统一的 Key 和 API 入口，官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api 。它的作用是让你不用在每台机器上分别配不同厂商的 Key，而是用一个 Key 走统一通道。
对 solon-ai 来说，MCP endpoint 改到 TaoToken 意味着两件事：一是 MCP Client 的 url 不再指向本地 8002，而是指向 TaoToken 的 MCP 通道；二是请求头里要带上 Authorization。这两点如果只改一处，就会出现 401 或者 local proxy failed。
前置准备分三步。第一步，拿到 Key。进入控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 页面创建一个新 Key，复制出来。这个 Key 后面要写进 app.yml 的 headers 里。第二步，确认模型 ID。如果你继续用 ollama 本地推理，模型 ID 保持qwen3:latest；如果你想走 TaoToken 的模型通道，可以在模型对话页 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 确认可用模型名。第三步，确认 MCP 通道地址。TaoToken 的 MCP endpoint 和普通 API 基址不同，不要直接把 https://taotoken.net/api 当成 MCP url。
这里有个容易踩的坑：solon-ai 的 MCP Client 配置里，channel必须和 endpoint 协议匹配。本地 SSE 用channel: sse，如果 TaoToken 的 MCP 通道走的是 streamable-http，就要改成对应值。excerpt 里特别提到「app.yml 中的配置项必须加上 solon.xxxxxx.channel: sse」，说明 channel 漏配是高频错误。
另外，TaoToken 的 Key 不要硬编码在 Java 代码里。solon-ai 支持从 app.yml 注入，你可以把 Key 放在solon.ai.mcp.client.demo.headers.Authorization下。这样换 Key 只改配置文件，不用重新编译。
如果你打算长期跑编码类 Agent，可以了解 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ；如果只是验证模型连通性，用模型对话页就够了。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，配置项对不上时优先查这里。
3. solon-ai 工程里 MCP endpoint 与鉴权的可复制配置
这一节是全文的核心。我会把 my-mcp-server 和 my-llm-server 两个工程的配置都列出来，你可以直接复制。先看 my-mcp-server 的 pom.xml：
<dependencies> <dependency> <groupId>org.noear</groupId> <artifactId>solon-web</artifactId> </dependency> <dependency> <groupId>org.noear</groupId> <artifactId>solon-ai</artifactId> </dependency> <dependency> <groupId>org.noear</groupId> <artifactId>solon-ai-mcp</artifactId> </dependency> </dependencies>发布 MCP 工具的类保持 excerpt 里的写法，但建议开启编译参数-parameters，否则@Param的 name 要手动补：
@McpServerEndpoint(channel = McpChannel.SSE, mcpEndpoint = "/mcp/sse") public class McpServerTool { @ToolMapping(description = "查询天气预报") public String getWeather(@Param(description = "城市位置") String location) { System.out.println("获取天气,time: " + System.currentTimeMillis()); return "晴，14度，当前时间是：" + LocalDateTime.now(); } }my-mcp-server 的 app.yml 里端口设为 8002，channel 写 sse。启动后控制台会打印http://localhost:8002，说明工具侧就绪。
接下来是 my-llm-server。pom.xml 依赖和上面一致。重点是 app.yml，这里要把 MCP endpoint 改到 TaoToken：
server.port: 8001 solon: app: name: 'solon-ai-web-demo-app' group: 'demo' ai: mcp: client: demo: url: "https://taotoken.net/api/mcp/sse" channel: sse headers: Authorization: "Bearer 你的TaoTokenKey" chat: demo: apiUrl: "http://172.16.76.135:11434/api/chat" provider: "ollama" model: "qwen3:latest"注意三处：url换成 TaoToken 的 MCP 通道地址，channel保持 sse，headers.Authorization填 Bearer 加 Key。如果你用的是 streamable-http 通道，把channel改成streamable，url 后缀也要对应调整。
McpClientProvider 的注入方式不变：
@Configuration public class MyConfig { @Bean public McpClientProvider mcpClientProvider(@Inject("${solon.ai.mcp.client.demo}") McpClientProvider client) { return client; } @Bean public ChatModel chatModel(@Inject("${solon.ai.chat.demo}") ChatConfig chatConfig, McpClientProvider mcpClientProvider) { ChatModel chatModel = ChatModel.of(chatConfig).build(); System.out.println(chatModel); return chatModel; } }测试接口也保持原样，关键是opts.toolsAdd(tools)这一步，它把 MCP 工具挂到模型推理选项上：
@Controller public class MsgController { @Inject ChatModel chatModel; @Inject McpClientProvider mcpClientProvider; @Get @Mapping("/msg") public String msg(@Param String prompt) throws IOException { System.out.println(prompt); String content = chatModel.prompt(prompt) .options(opts -> { Collection<FunctionTool> tools = mcpClientProvider.getTools(); opts.toolsAdd(tools); }) .call() .getMessage() .getContent(); return content; } }如果你同时用 Claude Code 或 Cline 这类工具，配置三件套要写全：Base URL 用 https://taotoken.net/api ，Key 用控制台创建的 Key，Model ID 用qwen3:latest或 TaoToken 模型页确认的名称。缺任何一个都会导致鉴权失败。
4. 连通性验证：从本地 ollama 到 TaoToken MCP 通道
配置改完后，启动 my-llm-server。控制台会打印 ChatModel 的配置，重点看apiUrl是不是 ollama 地址，provider是不是 ollama。如果这里打印的是 TaoToken 地址，说明 chat 配置被误改了。
第一个验证动作：不走 MCP 的普通提问。浏览器访问：
http://localhost:8001/msg?prompt=你好！帮我写一个排序算法，用java预期结果是模型直接返回排序算法代码，my-mcp-server 控制台没有「获取天气」输出。这一步验证的是 ollama 本地推理链路正常。
第二个验证动作：走 MCP 的天气提问。访问：
http://localhost:8001/msg?prompt=现在上海天气怎么样？预期结果是模型返回类似「上海今天天气晴朗，温度为14摄氏度」的内容，同时 my-mcp-server 控制台打印获取天气,time: ...。这一步验证的是 MCP 工具调用链路正常。
如果第二步没有触发工具调用，先看 my-llm-server 控制台有没有 MCP 连接日志。正常情况会打印 MCP Client 初始化信息。如果没有，说明 endpoint 或鉴权有问题。再看 my-mcp-server 控制台有没有收到请求。如果收到请求但模型没返回工具结果，说明toolsAdd没生效。
改到 TaoToken 后，验证动作多一步：确认请求头里带了 Authorization。你可以在 TaoToken 控制台的调用日志里看到这次 MCP 请求。如果日志里显示 401，说明 Key 没带上或者格式不对。Bearer 后面要有一个空格，Key 不要有多余换行。
实测下来，最容易出问题的是 channel 和 url 后缀不匹配。本地 SSE 是/mcp/sse，TaoToken 的 MCP 通道如果也是 SSE，url 要写成https://taotoken.net/api/mcp/sse；如果是 streamable-http，url 和 channel 都要改。两者不一致时，solon-ai 会报连接超时或者协议错误。
验证通过后，你可以把 prompt 换成更复杂的业务问题，比如「帮我查上海天气，然后根据温度推荐穿什么」。模型会先调 getWeather，再基于返回结果生成建议。这就是 MCP 工具调用的完整闭环。
5. 本篇常见错误排查对照
这一节按真实报错来对照。第一个高频错误是 401 Unauthorized。现象是 my-llm-server 启动时 MCP Client 初始化失败，或者调用 /msg 时返回鉴权错误。原因通常是 app.yml 里 headers 没写、Key 写错、或者 Bearer 格式不对。排查动作：检查solon.ai.mcp.client.demo.headers.Authorization是否存在，值是否为Bearer 你的Key。如果 Key 是从控制台复制的，注意不要带前后空格。
第二个错误是 local proxy failed。这个报错通常出现在 MCP endpoint 指向了不可达地址，或者本机网络策略拦截了出站请求。如果你把 url 改成 TaoToken 后出现这个错，先确认 https://taotoken.net/api 能正常访问。如果本地 ollama 地址写成了172.16.76.135:11434但实际 IP 变了，也会报类似错误。排查动作：把 url 换成http://localhost:11434/api/chat试一次，确认 ollama 本身可达。
第三个错误是 reading choices 相关解析失败。现象是模型返回内容为空，或者控制台报 JSON 解析异常。原因通常是 provider 和 apiUrl 不匹配。比如 apiUrl 指向 ollama，但 provider 写成了 openai，dialect 就会用错。排查动作：确认provider: "ollama"和apiUrl指向 ollama 的/api/chat。如果你走 TaoToken 的模型通道，provider 要改成对应值，apiUrl 改成 https://taotoken.net/api 。
第四个错误是 OAuth 相关报错。如果你在 MCP Client 里配了 OAuth 但 TaoToken 通道用的是 Bearer Key，就会冲突。排查动作：去掉 OAuth 配置，只用 headers.Authorization。TaoToken 的 Key 鉴权不需要额外 OAuth 流程。
第五个错误是工具不触发。现象是模型能回答天气问题，但 my-mcp-server 控制台没有输出。原因通常是opts.toolsAdd(tools)没执行，或者mcpClientProvider.getTools()返回空集合。排查动作：在toolsAdd前打印tools.size()，如果是 0，说明 MCP Client 没拉到工具列表。这时检查 my-mcp-server 是否启动、endpoint 是否可达、channel 是否匹配。
第六个错误是端口冲突。my-mcp-server 用 8002，my-llm-server 用 8001，如果本机有其他服务占用，启动会失败。排查动作：netstat -ano | findstr 8002查占用，换端口后同步改 app.yml 和 MCP url。
对照表如下：
| 报错现象 | 可能原因 | 排查动作 |
|---|---|---|
| 401 Unauthorized | Key 缺失或格式错 | 检查 headers.Authorization |
| local proxy failed | endpoint 不可达 | 确认 url 和网络 |
| reading choices 失败 | provider 与 apiUrl 不匹配 | 对齐 provider 和 apiUrl |
| OAuth 报错 | 鉴权方式冲突 | 去掉 OAuth，用 Bearer |
| 工具不触发 | tools 为空 | 打印 tools.size() |
| 启动失败 | 端口占用 | netstat 查占用 |
6. 把 MCP endpoint 稳定跑在 TaoToken 上的后续动作
配置跑通后，建议把 Key 管理收口。不要在多个工程的 app.yml 里散落同一个 Key，而是用环境变量注入。solon-ai 支持${TAOTOKEN_KEY}这种写法，app.yml 里写Authorization: "Bearer ${TAOTOKEN_KEY}"，启动时通过环境变量传入。这样换 Key 不用改代码，也不怕误提交。
第二个动作是给 MCP 调用加超时和重试。solon-ai 的 ChatConfig 里有 timeout 配置，默认 PT1M。如果 TaoToken 通道偶尔抖动，可以把 timeout 调到 PT2M，并在业务层加重试。注意重试不要无限循环，建议最多两次。
第三个动作是区分本地推理和远程 MCP 的日志。my-llm-server 控制台会同时打印 ollama 请求和 MCP 请求，建议在msg接口里加一个 traceId，方便对照。my-mcp-server 侧也打印同一个 traceId，这样排查链路问题时能快速定位是模型侧还是工具侧。
如果你后续要接 Claude Code 或 Cline，配置三件套再确认一遍：Base URL 用 https://taotoken.net/api ，Key 用控制台创建的 Key，Model ID 用确认过的模型名。Claude Code 的接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有完整的 settings 片段。API Keys 页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，需要新建 Key 时从这里进。
最后一个实用技巧：把 my-mcp-server 的工具描述写清楚。@ToolMapping(description = "查询天气预报")里的 description 会直接影响模型是否选择调用这个工具。描述太模糊，模型可能不调；描述太具体，又可能限制泛化。建议用「查询指定城市的当前天气」这种粒度。参数 description 也要写，否则模型不知道传什么。
跑通之后，你可以把 getWeather 换成真实业务接口，比如查订单、查库存。只要 MCP endpoint 稳定指向 TaoToken，鉴权头正确，solon-ai 就能把本地 ollama 的推理能力和远程工具调用串起来。这套链路的价值在于：模型可以本地跑，工具可以远程管，Key 可以统一控。
