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_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，创建后复制保存，它只显示一次。

然后确认你要用的模型通道，模型对话入口在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，这里能看到当前可用的模型标识，后面写进配置的model字段要和它一致。

API 的基础地址是https://taotoken.net/api，注意这个地址不带任何查询参数，配置里直接填它即可。如果你后面要做长期编码或 Agent 类任务，可以看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，它更适合高频调用的场景。

注意：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 f"echo: {text}" if __name__ == "__main__": mcp.run(transport="stdio")

这个echo_tool没有实际业务价值，但它是验证握手和工具注册的最小单元。先用它跑通链路，再换成真实工具，排障范围会小很多。

4. 验证请求：握手、工具注册与一次真实调用

配置写完后，不要急着接业务逻辑，按下面三步验证。

4.1 验证服务器能独立启动

先在终端直接跑服务器脚本：

TAOTOKEN_API_KEY=sk-你的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_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。

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()没传transport="stdio"，两边对不上。统一成 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_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言 SDK 的调用示例，配合本篇的配置骨架可以直接对照。如果你要做的是长期运行的编码助手或 Agent，Coding Plan 的额度模型比按次调用更适合：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。Claude Code 相关接入参考：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code_anthropic&utm_campaign=rewrite 。

最后留一个实用习惯：每次改完配置，先单独跑服务器脚本确认能启动，再启动客户端看tools/list，最后才发调用请求。三步分开验证，比一次性全跑再猜哪里错要快得多。