企业官网建设流程全解析

1. 为什么我最后还是回到 MCP Inspector 来调 MCP 服务

如果你正在写 MCP（Model Context Protocol）服务，尤其是用 Python 或 Node 起一个本地 server，然后想接到 Claude 里用，那你大概率会遇到一个很尴尬的阶段：代码写完了，Claude 那边也配好了，但就是没反应。你不知道是 server 没起来、协议握手失败、还是 tools 没注册成功。这个时候，mcp inspector就是那个能让你少走弯路的工具。

MCP Inspector 是 modelcontextprotocol 官方提供的一个可视化调试工具，它能直接连上你的 MCP server，把 server 暴露出来的 tools、resources、prompts 全部列出来，还能手动调用某个 tool 看返回。简单说，它把「Claude 到底能不能看到我的服务」这件事，从黑盒变成了白盒。适合谁用？适合所有在本地开发 MCP server、准备接入 Claude Desktop 或 Claude Code 的开发者，尤其是用uv管理 Python 环境、或者用npx跑 Node 服务的人。

我这边的场景很典型：一开始想用别的编辑器接 MCP，后来发现 Claude 只支持 stdio 模式，于是整个调试链路就得重新捋一遍。踩过的坑是，Inspector 并不能帮你测「异常连接」这种边界情况，它更像是一个正常路径下的能力检查器。所以正确的顺序是：先用命令行确认 server 本身不报错，再用 Inspector 看能力列表，最后才去配 Claude 的settings.json。下面我把这套流程拆开讲。

2. 前置准备：TaoToken 与 MCP 调试环境的关系

在讲 Inspector 之前，先说一个容易被忽略的点：MCP server 本身不负责模型调用，它只负责把能力暴露给客户端。但如果你在调试过程中想顺便验证「模型能不能正确调用这个 tool」，那就需要一个能稳定访问 Claude 的通道。我这边用的是 TaoToken 来做模型侧的联调，它的 API 地址是https://taotoken.net/api，官网在https://taotoken.net/?utm_source=taotoken_aicg_blog_end。

为什么要在 MCP 调试里提这个？因为很多人调 MCP 的时候，server 明明没问题，Inspector 里 tools 也列出来了，但一接到 Claude 就失败，最后发现是模型侧请求根本没发出去。所以我的建议是：MCP server 用 Inspector 调，模型调用用 TaoToken 的 key 单独验证一遍，两条链路分开排查，效率高很多。

你需要准备的东西不多：一个能跑 Python 或 Node 的本地环境，uv或npx至少有一个能用，然后去 TaoToken 控制台拿一个 API Key 备用。控制台入口在https://taotoken.net/console，API Keys 管理在https://taotoken.net/api-keys。这些不是 MCP Inspector 的必需项，但后面验证模型调用时会用到。

3. 可复制配置：uv 与 npx 两种启动方式

3.1 先用 uv 确认 server 本身能跑

不管你后面用不用 Inspector，第一步永远是让 server 自己在命令行里跑起来不报错。假设你的 MCP 项目在C:\Users\Administrator\PycharmProjects\xrun，入口文件是sqlserver-mcp.py，那你可以这样：

uv --directory C:\Users\Administrator\PycharmProjects\xrun run sqlserver-mcp.py

如果这条命令报错，那就先修代码，别急着上 Inspector。我实测下来，uv --directory在 Windows 路径下有时候会被转义影响，比如反斜杠和空格处理不好就会失败。偷懒但有效的做法是直接进到项目目录再跑：

cd C:\Users\Administrator\PycharmProjects\xrun uv run sqlserver-mcp.py

这样能跑通，说明 server 的 stdio 模式是正常的。注意，MCP server 在 stdio 模式下启动后不会主动输出什么，它会等着客户端发 JSON-RPC 消息，所以命令行看起来「卡住」是正常的，按 Ctrl+C 退出即可。

3.2 用 npx 启动 MCP Inspector

确认 server 能跑之后，就可以用 Inspector 来连它了。官方包是@modelcontextprotocol/inspector，两种用法：

第一种，直接把启动命令交给 Inspector，它会自动拉起 server 并连接：

npx @modelcontextprotocol/inspector uv run sqlserver-mcp.py

注意这里我没有加--directory，因为前面说过转义容易出问题，所以先cd到项目目录再执行这条命令最稳。

第二种，先单独启动 Inspector，然后在网页里手动填参数：

npx @modelcontextprotocol/inspector

执行后它会输出一个本地地址，通常是http://localhost:6274，用浏览器打开，在界面里填 command 为uv，args 为run sqlserver-mcp.py，然后点 Connect。这种方式适合你反复改参数、反复重连的场景。

3.3 Inspector 界面里看什么

连上之后，重点看几个地方。左侧一般会有 Tools、Resources、Prompts 几个标签。点 Tools，如果 server 注册了工具，这里会全部列出来，包括每个 tool 的名字、描述、输入参数 schema。你可以直接选一个 tool，填上参数，点 Run，看返回结果。这一步比在 Claude 里试错快太多了，因为 Claude 那边你只能看到最终对话，看不到协议层的报错。

我当时的做法就是通过 Tools 列表确认所有支持的能力都注册上了，然后再去配 Claude。如果这里列表是空的，那说明 server 的 tool 注册代码有问题，跟 Claude 没关系。

4. 验证请求：从 Inspector 到 Claude settings.json

4.1 先用 TaoToken 验证模型侧能通

在配 Claude 之前，我建议先用 TaoToken 的 API 单独发一个请求，确认模型通道是好的。比如用 curl 测一下：

curl https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: 你的_TAOTOKEN_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 128, "messages": [{"role": "user", "content": "ping"}] }'

如果返回正常，说明模型侧没问题。这一步能帮你排除「MCP 配好了但模型请求发不出去」的情况。想直接在网页里试模型对话的话，可以用https://taotoken.net/model-chat。

4.2 Claude 的 settings.json 配置骨架

Claude Desktop 的 MCP 配置一般在claude_desktop_config.json，Claude Code 则在项目或全局的settings.json里。核心结构是一样的，都是mcpServers下面挂一个个 server。给你一个可以直接改的骨架：

{ "mcpServers": { "sqlserver-mcp": { "command": "uv", "args": [ "--directory", "C:\\Users\\Administrator\\PycharmProjects\\xrun", "run", "sqlserver-mcp.py" ], "env": { "PYTHONUNBUFFERED": "1" } } } }

几个关键点。第一，Windows 路径在 JSON 里反斜杠要写成双反斜杠\\，这是最常见的配置错误。第二，如果你前面发现--directory有转义问题，那就把command改成cmd，args用/c cd /d 路径 && uv run sqlserver-mcp.py这种形式绕过去。第三，env里加PYTHONUNBUFFERED=1能让 Python 的输出不被缓冲，调试时更容易看到日志。

如果你用的是 Claude Code，配置位置和字段名略有不同，但command/args/env这套逻辑是一致的。配完之后重启 Claude，让它重新加载 MCP server。

4.3 验证 Claude 是否真的连上了

重启后，在 Claude 里问一句跟你的 tool 相关的话，比如「列出数据库里有哪些表」。如果 Claude 调用了你的 tool，你会看到它发起工具调用的提示。如果没反应，回到 Inspector 确认 server 还能连上，再检查 Claude 的日志。Claude Desktop 的日志一般在%APPDATA%\Claude\logs下面，能看到 MCP 连接的具体报错。

5. 本篇常见错排查

5.1 Inspector 连不上 server

最常见的原因是 command 或 args 写错。比如uv不在 PATH 里，或者路径里有空格没处理。解决办法是先在终端里把完整命令跑通，再原样填进 Inspector。另外，Inspector 启动的 server 是子进程，如果 server 启动后立刻退出，Inspector 会显示连接失败，这时候去看 server 自己的 stderr 输出。

5.2 Tools 列表为空

Server 连上了但 Tools 是空的，说明 tool 注册代码没执行到。检查你的@mcp.tool()装饰器或者等价的注册逻辑，确认 server 启动时确实注册了。有些框架要求你在if __name__ == "__main__":里调用mcp.run()，漏了这行就不会注册。

5.3 Claude 里看不到 tool

如果 Inspector 里正常但 Claude 里没有，先确认配置文件路径对不对，JSON 有没有语法错误（比如多了逗号）。然后重启 Claude，MCP 配置是启动时加载的。还不行就看日志，日志里会写「failed to start server」或者「connection closed」这类信息。

5.4 uv --directory 转义问题

这个前面提过，Windows 下路径转义很容易出问题。最稳的方案是不要用--directory，直接在配置里用cmd /c cd /d 路径 && uv run ...。虽然丑一点，但能跑通比什么都重要。

5.5 stdio 模式下 server 输出干扰协议

MCP 的 stdio 模式是用标准输入输出传 JSON-RPC 的，如果你在代码里print()了调试信息，会污染协议导致连接失败。调试信息一律走 stderr，或者用日志库写到文件。这个问题很隐蔽，Inspector 可能表现为连上又断开。

6. 接入与验证的下一步

把 Inspector 调通、Claude 配置写对之后，你的 MCP 服务基本就能用了。如果你后面要做更复杂的编码任务或者 Agent 流程，可以考虑用 TaoToken 的 Coding Plan 来跑长期任务，入口在https://taotoken.net/coding-plan。接入文档在https://taotoken.net/doc，API Keys 还是在https://taotoken.net/api-keys管理。

回到 MCP 本身，我的经验是：Inspector 负责「能力对不对」，命令行负责「server 活不活」，Claude 负责「最终能不能用」。这三步分开做，出问题的时候你才知道该修哪一层。另外，如果你偏爱 SSE 或 HTTP 模式的 MCP，那断点调试会更舒服，Python 里直接下断点就行，不用像 stdio 那样隔着一层进程。但 Claude 目前对 stdio 支持最稳，所以这套流程还是值得先跑一遍。