1. 为什么你的 MCP 工具调用总是卡在握手阶段MCP 协议Model Context Protocol是大模型与外部工具之间的标准化通信层你可以把它理解成 AI 世界的 USB-C 接口模型不需要知道每个工具内部怎么实现只要双方都遵守同一套客户端-服务器约定就能完成工具发现、参数协商和结果回传。它主要解决三件事——统一不同 LLM 的工具描述格式、让工具在本地进程里安全运行、把资源访问权限收拢到服务器侧。适合谁适合正在给本地 AI 工具接入外部能力的人比如让 Claude Desktop 读本地 SQLite、让自建 Agent 调内部 HTTP 接口、让 coding 助手查实时文档。但真正动手时多数人第一次跑 MCP 都会卡在同一个地方客户端启动了服务器也起来了可tools/list返回空或者tools/call直接超时。问题往往不在业务代码而在配置骨架——settings.json里 command 写成了相对路径、config.toml的 transport 和实际启动方式不匹配、环境变量没透传导致服务器拿不到 Key。这篇就按「客户端-服务器握手 → 工具注册 → 实际调用」的顺序把可复制的配置骨架和验证动作拆开讲并用 TaoToken 统一 Key/API 通道让你独立跑通一次完整的 MCP 工具调用。2. TaoToken 前置把 Key 和 API 通道先理顺MCP 的服务器进程通常需要调用某个大模型来完成「分析可用工具 → 决定调哪个 → 生成参数」这一步。如果你每个工具服务器都单独配一套厂商 Key很快就会乱有的读ANTHROPIC_API_KEY有的读OPENAI_API_KEY环境变量名还不统一。我试过把 Key 集中到一处管理后面换模型、加工具都省事很多。TaoToken 在这里的角色是统一入口你拿到一个 Key通过统一的 API 通道访问模型MCP 服务器和客户端都指向同一个 base_url不用为每个工具单独申请凭证。操作路径如下先在控制台创建 Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 创建后复制保存它只显示一次。然后确认你要用的模型通道模型对话入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 这里能看到当前可用的模型标识后面写进配置的model字段要和它一致。API 的基础地址是https://taotoken.net/api注意这个地址不带任何查询参数配置里直接填它即可。如果你后面要做长期编码或 Agent 类任务可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合高频调用的场景。注意Key 不要写进会提交到 Git 的配置文件里。用环境变量或本地.env并在.gitignore里排除。3. 可复制配置settings.json 与 config.toml 骨架MCP 客户端读取服务器配置的方式因工具而异。Claude Desktop 系用claude_desktop_config.json很多自建客户端和编辑器插件用settings.json而部分 Python 生态工具用config.toml。下面给两份骨架字段含义一致只是格式不同。3.1 settings.json 骨架{ mcpServers: { local-tools: { command: python, args: [/absolute/path/to/server.py], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_MODEL: 你的模型标识 } } } }关键点有三个。第一command用python或node不要写python3.11这种带小版本的路径除非你确认客户端能解析。第二args里的脚本路径必须是绝对路径相对路径在客户端切换工作目录后会失效这是tools/list返回空的高频原因。第三env里把 TaoToken 的 Key、base_url、model 一次性透传给服务器进程服务器代码里直接os.environ读取即可不用再维护第二份配置。3.2 config.toml 骨架[mcp_servers.local-tools] command python args [/absolute/path/to/server.py] transport stdio [mcp_servers.local-tools.env] TAOTOKEN_API_KEY sk-你的Key TAOTOKEN_BASE_URL https://taotoken.net/api TAOTOKEN_MODEL 你的模型标识transport stdio表示客户端通过标准输入输出和服务器通信这是本地工具最常用的方式。如果你改成 HTTP 或 SSE服务器启动方式也要跟着改两边不一致就会握手失败。3.3 服务器侧读取配置服务器代码里不要硬编码 Key统一从环境变量取import os from mcp.server.fastmcp import FastMCP mcp FastMCP(local-tools) API_KEY os.environ.get(TAOTOKEN_API_KEY) BASE_URL os.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api) MODEL os.environ.get(TAOTOKEN_MODEL) mcp.tool() async def echo_tool(text: str) - str: 一个最小可验证工具原样返回输入。 return fecho: {text} if __name__ __main__: mcp.run(transportstdio)这个echo_tool没有实际业务价值但它是验证握手和工具注册的最小单元。先用它跑通链路再换成真实工具排障范围会小很多。4. 验证请求握手、工具注册与一次真实调用配置写完后不要急着接业务逻辑按下面三步验证。4.1 验证服务器能独立启动先在终端直接跑服务器脚本TAOTOKEN_API_KEYsk-你的Key python /absolute/path/to/server.py如果进程挂起不报错说明 stdio 模式正常在等客户端输入。如果立刻退出并报ModuleNotFoundError先补依赖pip install mcp。这一步能排除掉「服务器本身起不来」的问题。4.2 验证客户端握手与工具列表启动客户端后观察日志里是否出现类似输出Connected to server with tools: [echo_tool]这行来自客户端调用session.list_tools()的结果。如果列表为空回到第 3 节检查args路径和command。如果客户端根本没打印连接信息检查settings.json的 JSON 是否合法——多一个逗号就会导致整个配置被忽略。4.3 验证一次真实工具调用在客户端输入调用 echo_tool参数 text 为 hello-mcp预期返回echo: hello-mcp。这一步走通说明「客户端 → 服务器 → 工具执行 → 结果回传」整条链路是通的。此时再把echo_tool替换成你的真实工具比如查数据库、调内部 API只需要改工具函数体配置骨架不用动。如果你在验证模型侧行为比如确认模型是否正确选择了工具、参数是否符合 schema可以用模型对话入口手动发一轮请求对照https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。5. 本篇常见错排查5.1 tools/list 返回空最常见的原因是脚本路径不是绝对路径或者command指向了一个不存在的解释器。排查方法把args里的路径复制到终端ls一下确认文件存在把command换成which python的输出。另一个原因是服务器启动时抛了异常但被 stdio 吞掉了临时把mcp.run外面包一层 try/except 打印到 stderr 就能看到。5.2 握手超时或连接立即断开transport配置和实际启动方式不匹配是主因。config.toml写了stdio但服务器代码里mcp.run()没传transportstdio两边对不上。统一成 stdio 后重试。如果用的是 HTTP 模式还要确认端口没有被占用。5.3 工具被调用但报 Key 无效说明环境变量没透传到服务器进程。检查settings.json的env块是否在mcpServers.local-tools下面而不是写到了外层。另外确认 Key 没有多余空格复制时容易带上换行。base_url 必须是https://taotoken.net/api不要自己拼/v1之类的后缀。5.4 模型不调用工具只回文字这通常不是 MCP 的问题而是工具描述写得太模糊。mcp.tool()下面的 docstring 就是给模型看的工具说明写清楚「这个工具做什么、参数是什么、什么时候该用」。比如把查询数据改成根据用户 ID 查询订单状态参数 user_id 为字符串模型选择准确率会明显上升。5.5 调用成功但结果被截断检查客户端的max_tokens设置和工具返回内容长度。MCP 本身不限制返回大小但模型侧有 token 上限。如果工具返回的是大段文本考虑在服务器侧先做摘要再回传。6. 把链路固定下来再谈扩展跑通一次之后建议把配置骨架和echo_tool一起留在一个最小仓库里作为以后加新工具的模板。每次加工具只改服务器代码客户端配置不动这样排障时变量最少。Key 和 base_url 始终走 TaoToken 统一通道换模型时只改TAOTOKEN_MODEL一个值不用翻遍所有工具的配置。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言 SDK 的调用示例配合本篇的配置骨架可以直接对照。如果你要做的是长期运行的编码助手或 AgentCoding Plan 的额度模型比按次调用更适合https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。Claude Code 相关接入参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_anthropicutm_campaignrewrite 。最后留一个实用习惯每次改完配置先单独跑服务器脚本确认能启动再启动客户端看tools/list最后才发调用请求。三步分开验证比一次性全跑再猜哪里错要快得多。
)
