1. 为什么你的 MCP 工具总被 Claude Code 选错先还原一个我踩过的坑。我给 Claude Code 挂了一个内部工单系统的 MCP 服务里面有两个工具search_ticket和get_ticket_detail。前者按关键词搜工单列表后者按工单 ID 拉详情。逻辑上很清晰但实际跑起来Claude Code 经常在用户说“帮我看看上周那个支付超时的工单”时直接调get_ticket_detail然后传一个它自己编的 ID 进去报错再重试来回三四轮才回到search_ticket。问题不在模型笨而在我把“函数思维”直接搬进了“认知工具”的设计里。传统编程里函数签名清楚、调用方是人人知道先搜再取详情。但 Claude Code 面对的是几十个 MCP 工具它靠工具名、描述、参数 schema 来建立“认知地图”。地图画得糊它就走错路。这一篇聚焦的就是这件事怎么让 Claude Code 稳定选中正确的 MCP 工具并且把整条调用链路一次跑通。核心检索词是 Claude Code 工具设计与 MCP 工具 schema适合已经在用 Claude Code、准备接自定义 MCP 服务、或者被工具误调用折磨过的开发者。我会给出可复制的 MCP 工具 schema、Claude Code 的配置片段以及把 endpoint 切到 TaoToken 统一 Key 通道后的连通性验证步骤。目标很明确一次跑通不靠玄学。先说清楚一个前提。Claude Code 调用工具时工具描述和参数 schema 会被塞进上下文和系统提示词一起构成模型对“我能做什么”的认知。描述写得含糊模型就会用它的先验去猜参数命名不自然模型就会填错。这不是提示词工程的花活而是接口设计的基本功。我实测下来把工具描述从“查询工单”改成带使用场景、边界条件、示例参数的完整说明后误调用率下降非常明显。所以这一篇的结构是先讲工具设计的具体法则和 schema 写法再讲怎么把 Claude Code 的请求通道统一到 TaoToken最后验证整条链路。工具设计和通道接入是两件事但只有两件都做对工具调用才会稳。2. MCP 工具 schema 设计让 Claude Code 一眼看懂参数2.1 工具描述要写“什么时候用”而不是“这是什么”很多人写工具描述就一句话“搜索工单”。Claude Code 看到这句话只能靠工具名猜。正确的写法是把使用场景、不适用场景、返回什么、参数怎么填都写进去。下面是我现在用的search_ticket的 schema可以直接复制改{ name: search_ticket, description: 按关键词、状态、时间范围搜索工单列表。当用户想查找某个问题相关的工单、但还没有具体工单ID时使用此工具。返回匹配工单的摘要列表ID、标题、状态、创建时间不返回完整详情。如果需要工单的完整对话记录请先用本工具拿到 ticket_id再调用 get_ticket_detail。不要在没有关键词的情况下调用本工具那会返回过多结果。, inputSchema: { type: object, properties: { keyword: { type: string, description: 搜索关键词匹配工单标题和描述。例如 支付超时、登录失败。必填。 }, status: { type: string, enum: [open, in_progress, resolved, closed], description: 按工单状态过滤。不传则返回所有状态。 }, days: { type: integer, description: 只搜索最近 N 天内创建的工单。默认 30最大 365。 }, limit: { type: integer, description: 返回结果数量上限默认 10最大 50。超过时结果会被截断并提示缩小范围。 } }, required: [keyword] } }注意几个细节。第一描述里明确写了“不返回完整详情”和“先拿 ticket_id 再调 get_ticket_detail”这是在引导模型走正确的调用顺序。第二keyword的 description 给了示例值模型填参数时会参考。第三limit的说明里写了“超过时结果会被截断并提示缩小范围”这是给模型一个预期避免它一次要 500 条。2.2 参数命名要自解释别用缩写我见过有人把参数写成kw、st、d。人看上下文能猜模型不行。参数名本身就是提示词的一部分。用keyword而不是kw用status而不是st用days而不是d。同理user_id比uid好ticket_id比tid好。这不是啰嗦是在降低模型的认知负担。还有一个坑布尔参数。is_resolved: true和status: resolved哪个好我倾向后者因为枚举值比布尔值携带更多语义模型不容易搞反。如果确实需要布尔参数名要写成include_closed这种正向表述别用exclude_open这种双重否定。2.3 返回结果要带上下文别只丢 ID工具返回的内容同样影响模型下一步决策。如果search_ticket只返回一串ticket_id模型还得再调一次详情工具才能知道哪个相关。更好的做法是返回摘要ID、标题、状态、创建时间、一句话描述。这样模型能直接判断该深入看哪个。但也要控制 token。我实测下来单条工单摘要控制在 100 token 以内10 条就是 1000 token完全可接受。如果返回 50 条完整工单上下文直接爆掉。所以分页和截断策略必须做而且截断时要给模型明确提示比如“结果已截断共匹配 230 条当前返回前 10 条建议添加更具体的关键词或缩小 days 范围”。2.4 工具数量要克制功能重叠是大忌Claude Code 同时挂多个 MCP 服务时工具总数可能上百。这时候功能重叠的工具会让模型选择困难。我的做法是同一类操作只保留一个入口把高频串联的操作合并。比如不要同时提供list_users、list_events、create_event而是提供一个schedule_event内部自动查空闲时间并创建。工具越少、职责越清晰模型选对的概率越高。命名空间也要用起来。如果你同时接了 Asana 和 Jira 的 MCP工具名写成asana_search和jira_search而不是两个都叫search。前缀还是后缀不同模型反应不同建议用你的实际评估数据决定。我这边测试下来前缀式在 Claude 系列上表现更稳。3. Claude Code 接入 TaoToken 统一 Key 的配置片段工具 schema 写好了接下来要保证 Claude Code 的请求能稳定发出去。如果你在国内直连官方 endpoint经常会遇到超时或连接失败工具调用链路根本跑不起来。把 endpoint 切到 TaoToken 的统一 Key 通道是我目前用得比较顺的方案。下面给出完整配置。3.1 获取 API Key 与 Base URL先到 TaoToken 控制台创建一个 API Key。地址是https://taotoken.net/console登录后在 API Keys 页面新建一个复制出来。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数。3.2 Claude Code 的 settings 配置Claude Code 读取的是项目根目录或用户目录下的配置文件。我一般放在项目根目录的.claude/settings.json内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Claude Code 的 CLI也可以直接通过环境变量注入export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥 export ANTHROPIC_MODELclaude-sonnet-4-20250514三件套必须齐全Base URL、Key、Model ID。少任何一个都会导致 401 或模型找不到。Model ID 要写你实际要用的模型别照抄我的去 TaoToken 的模型列表页确认当前可用的 ID。3.3 MCP 服务端的配置MCP 服务本身是本地进程不需要走网络通道但 Claude Code 调用模型时走的是上面配置的 Base URL。如果你用的是 Cline 或 CC Switch 这类工具来管理 MCP配置方式类似核心还是那三件套。下面是一个 Cline 的 MCP 配置示例{ mcpServers: { ticket-system: { command: node, args: [/path/to/your/mcp-server/index.js], env: { TICKET_API_BASE: https://internal.example.com/api } } } }注意MCP 服务端自己的环境变量和 Claude Code 的模型通道是两回事。前者是工具内部访问你业务系统的凭证后者是模型请求的通道。别混在一起。3.4 验证配置是否生效配置写完后先跑一个最小请求确认通道通。用 curl 直接打 TaoToken 的 APIcurl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回里有content字段且文本是 OK说明通道没问题。如果返回 401检查 Key 是否复制完整如果返回 model not found检查 Model ID 拼写。这一步过了再进 Claude Code 里跑工具调用。4. 验证工具调用链路从提问到正确选中工具4.1 启动 Claude Code 并加载 MCP在项目目录下启动 Claude Code确认 MCP 服务已加载。你可以用/mcp命令查看当前挂载的工具列表。如果search_ticket和get_ticket_detail都在列表里说明 MCP 服务注册成功。4.2 用真实场景提问不要用“测试一下”这种空话。用真实场景比如帮我查一下最近 7 天关于“支付超时”的工单看看有没有还没解决的。Claude Code 应该先调search_ticket参数是keyword: 支付超时、days: 7、status: open。如果它直接调get_ticket_detail说明工具描述里的引导没起作用回去检查search_ticket的描述是否明确写了“没有具体 ID 时先用本工具”。4.3 观察调用顺序和参数Claude Code 会在终端里打印工具调用日志。重点看三件事调了哪个工具、参数填了什么、返回结果是否被正确理解。如果它先搜到了工单列表然后针对某一条调get_ticket_detail说明链路是通的。如果它在两个工具之间反复横跳或者参数填错回到 schema 层面改描述。4.4 成功结果长什么样一次成功的调用链路是这样的用户提问 → Claude Code 调search_ticket→ 拿到 3 条摘要 → 模型判断其中一条相关 → 调get_ticket_detail拿详情 → 汇总回答。整个过程不需要人工干预工具调用次数在 2 到 3 次之间token 消耗可控。我实测下来工具描述写清楚后这条链路基本一次跑通。5. 常见报错排查401、local proxy failed、reading choices5.1 401 Unauthorized最常见。原因通常是 Key 没配对或者 Base URL 写成了带路径的完整地址。检查ANTHROPIC_API_KEY是否以sk-开头且没有多余空格。如果用的是 settings.json确认 JSON 格式合法别多逗号。还有一种情况是 Key 过期或被禁用去 TaoToken 控制台确认状态。5.2 local proxy failed这个报错通常出现在你本地配了代理但代理没起来或者 Claude Code 尝试走一个不存在的本地端口。检查环境变量里有没有残留的HTTP_PROXY或HTTPS_PROXY指向本地端口。如果有清掉再试。另外确认ANTHROPIC_BASE_URL是https://taotoken.net/api不要写成http://或带端口。5.3 reading choices 相关报错这类报错一般出现在模型返回格式不符合预期时比如你用的 Model ID 和实际通道支持的模型不匹配。检查ANTHROPIC_MODEL是否在 TaoToken 的可用模型列表里。如果模型 ID 写错通道可能返回一个非标准响应Claude Code 解析时就报 reading choices 错误。换成确认可用的 Model ID 即可。5.4 OAuth 相关报错如果你之前用 Claude Code 登录过官方账号本地可能残留 OAuth token导致它优先走旧凭证而不是你配的 API Key。解决办法是清除本地凭证缓存或者显式设置ANTHROPIC_API_KEY并确保它优先级更高。具体路径因系统而异一般在~/.claude/目录下清掉credentials.json之类的文件再重启。5.5 工具调用超时如果模型通道通了但工具调用总是超时检查 MCP 服务端本身是否响应正常。可以单独跑 MCP 服务的启动命令看它有没有报错。另外确认 MCP 服务监听的端口没有被防火墙拦。工具调用超时和模型通道超时是两回事分开排查。6. 把工具设计和通道接入一起做才算真正跑通工具设计和通道接入是两条腿。schema 写得再好通道不通Claude Code 连模型都调不到工具调用无从谈起通道再顺工具描述含糊模型照样选错工具。我踩过的坑基本都在这两头要么是描述里漏了“先搜后取”的引导要么是 Base URL 多写了一个斜杠导致 401。如果你现在正在接自定义 MCP 工具建议按这个顺序来先把工具 schema 按第 2 节的写法改一遍重点补全描述里的使用场景和边界条件然后把 Claude Code 的通道切到 TaoToken用第 3 节的 curl 命令确认通道通最后用真实场景提问观察调用顺序。三步都过了链路就稳了。需要长期跑编码 Agent 的话可以看看 TaoToken 的 Coding Plan地址是https://taotoken.net/coding-plan。如果只是想先验证模型对话是否正常用模型对话页面https://taotoken.net/models快速试一条。接入文档在https://taotoken.net/docAPI Keys 管理在https://taotoken.net/api-keys。这几个入口按需取用别一次全开。最后说一个我自己的习惯每次改完工具 schema我都会用同一个真实问题跑三遍看模型是否稳定选中同一个工具、参数是否一致。三次都一致才算这个工具设计过关。不一致就回去改描述。这个笨办法比任何理论都管用。