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/sseollama 指向局域网里的 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个新 Key复制出来。这个 Key 后面要写进 app.yml 的 headers 里。第二步确认模型 ID。如果你继续用 ollama 本地推理模型 ID 保持qwen3:latest如果你想走 TaoToken 的模型通道可以在模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 确认可用模型名。第三步确认 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_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 如果只是验证模型连通性用模型对话页就够了。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置项对不上时优先查这里。3. solon-ai 工程里 MCP endpoint 与鉴权的可复制配置这一节是全文的核心。我会把 my-mcp-server 和 my-llm-server 两个工程的配置都列出来你可以直接复制。先看 my-mcp-server 的 pom.xmldependencies dependency groupIdorg.noear/groupId artifactIdsolon-web/artifactId /dependency dependency groupIdorg.noear/groupId artifactIdsolon-ai/artifactId /dependency dependency groupIdorg.noear/groupId artifactIdsolon-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 里端口设为 8002channel 写 sse。启动后控制台会打印http://localhost:8002说明工具侧就绪。接下来是 my-llm-server。pom.xml 依赖和上面一致。重点是 app.yml这里要把 MCP endpoint 改到 TaoTokenserver.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保持 sseheaders.Authorization填 Bearer 加 Key。如果你用的是 streamable-http 通道把channel改成streamableurl 后缀也要对应调整。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 - { CollectionFunctionTool tools mcpClientProvider.getTools(); opts.toolsAdd(tools); }) .call() .getMessage() .getContent(); return content; } }如果你同时用 Claude Code 或 Cline 这类工具配置三件套要写全Base URL 用 https://taotoken.net/api Key 用控制台创建的 KeyModel 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/sseTaoToken 的 MCP 通道如果也是 SSEurl 要写成https://taotoken.net/api/mcp/sse如果是 streamable-httpurl 和 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 写成了 openaidialect 就会用错。排查动作确认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 用 8002my-llm-server 用 8001如果本机有其他服务占用启动会失败。排查动作netstat -ano | findstr 8002查占用换端口后同步改 app.yml 和 MCP url。对照表如下报错现象可能原因排查动作401 UnauthorizedKey 缺失或格式错检查 headers.Authorizationlocal proxy failedendpoint 不可达确认 url 和网络reading choices 失败provider 与 apiUrl 不匹配对齐 provider 和 apiUrlOAuth 报错鉴权方式冲突去掉 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 用控制台创建的 KeyModel ID 用确认过的模型名。Claude Code 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的 settings 片段。API Keys 页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 需要新建 Key 时从这里进。最后一个实用技巧把 my-mcp-server 的工具描述写清楚。ToolMapping(description 查询天气预报)里的 description 会直接影响模型是否选择调用这个工具。描述太模糊模型可能不调描述太具体又可能限制泛化。建议用「查询指定城市的当前天气」这种粒度。参数 description 也要写否则模型不知道传什么。跑通之后你可以把 getWeather 换成真实业务接口比如查订单、查库存。只要 MCP endpoint 稳定指向 TaoToken鉴权头正确solon-ai 就能把本地 ollama 的推理能力和远程工具调用串起来。这套链路的价值在于模型可以本地跑工具可以远程管Key 可以统一控。