1. 为什么你的第一个 MCP Server 总是“看起来没反应”如果你刚开始接触 MCPModel Context Protocol大概率会遇到一个很反直觉的场景代码写完了node build/index.js也能跑起来终端没报错但你就是不知道它到底暴露了哪些工具、参数长什么样、调用之后返回什么。更麻烦的是一旦直接接到 Claude、Cursor 这类客户端里报错信息往往只有一句“连接失败”根本定位不到是 Server 没启动、协议握手失败还是工具注册写错了。MCP Inspector 就是解决这个问题的。它是 MCP 官方提供的调试工具你可以把它理解成 MCP 世界的“接口调试器”——类似 Postman 之于 HTTP 接口。它不接大模型直接作为客户端去连接你的 MCP Server自动完成initialize、tools/list、resources/list、prompts/list这些协议方法然后把工具列表、参数表单、原始 JSON-RPC 报文全部展示出来。这篇文章聚焦 Node.js 环境用npx启动 MCP Inspector把自建 MCP Server 从零调通。适合谁刚写完第一个 MCP Server 但不知道怎么验证的开发者被客户端“连接失败”卡住、想先隔离 Server 问题的人以及想搞清楚 stdio 传输下 stdout/stderr 到底怎么分工的 Node.js 用户。读完你能拿到可复制的 Inspector 启动命令、一个最小 MCP Server 配置骨架以及一次端到端调通的完整验证动作。2. 前置准备Node.js 版本、npx 与 TaoToken 接入位MCP Inspector 本身是 Node 程序官方 v2 对 Node 版本有硬性要求node 22.19.0。先确认版本node -v # 期望输出 v22.19.0 或更高如果版本不够用 nvm 升级最省事nvm install 22 nvm use 22 node -vInspector 不需要全局安装npx直接拉起来就行这也是新手最推荐的方式npx modelcontextprotocol/inspector它会启动一个本地 Web 界面默认端口通常是6274但不同版本可能不同以终端实际打印的地址为准。如果你经常用也可以全局装npm install -g modelcontextprotocol/inspector mcp-inspector这里插一句和模型接入相关的准备。Inspector 只负责调通 Server不负责接大模型。等你把 Server 调稳之后真正要接 Claude Code、Codex 或自建 Agent 时会需要一个稳定的模型 API 入口。我自己的做法是先在 TaoToken 控制台把 API Key 建好后面接客户端时直接填省得来回切换配置。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API 基址用 https://taotoken.net/api 。这一步现在不做也行但建议先把 Key 备着因为后面接真实客户端时一定会用到。3. 可复制配置最小 MCP Server 骨架 Inspector 三种启动模式先写一个最小可运行的 MCP Server。Node.js 环境下用官方 TypeScript SDK目录结构如下mcp-demo/ ├── package.json ├── tsconfig.json └── src/ └── index.tspackage.json关键部分{ name: mcp-demo, version: 1.0.0, type: module, bin: { mcp-demo: build/index.js }, scripts: { build: tsc chmod x build/index.js }, dependencies: { modelcontextprotocol/sdk: ^1.0.0 }, devDependencies: { typescript: ^5.6.0 } }src/index.ts骨架暴露两个工具add和greet#!/usr/bin/env node import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; const server new McpServer({ name: demo-server, version: 1.0.0, }); server.tool( add, 两个数相加返回结果, { a: z.number(), b: z.number() }, async ({ a, b }) ({ content: [{ type: text, text: String(a b) }], }) ); server.tool( greet, 向指定名字的人打招呼, { name: z.string() }, async ({ name }) ({ content: [{ type: text, text: 你好${name}欢迎使用 MCP Demo Server。 }], }) ); const transport new StdioServerTransport(); await server.connect(transport); // 注意日志一律走 stderr绝不能 console.log console.error(demo-server started on stdio);编译npm install npm run build先单独确认 Server 能启动node build/index.js如果它“看起来卡住”不动这是正常的——stdio 模式下它在等 stdin 上的 JSON-RPC 消息。直接CtrlC退出即可。接下来是 Inspector 的三种模式按场景选模式命令适合场景Webnpx modelcontextprotocol/inspector node build/index.js图形化调试最直观CLInpx modelcontextprotocol/inspector --cli node build/index.js --method tools/list脚本、CI、一次性连通性检查TUInpx modelcontextprotocol/inspector --tui node build/index.js无浏览器环境命令里node build/index.js的角色很关键它不是 Inspector 的参数而是告诉 Inspector“用这条命令把 MCP Server 作为子进程拉起来”。Inspector 作为父进程 spawn 这个子进程通过子进程的 stdin/stdout 收发 MCP 协议消息。换成别的启动方式同理# 用 uvx 启动 Python 包 npx modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/repo.git # 启动编译好的二进制 npx modelcontextprotocol/inspector ./my-server --flag x4. 验证请求从 tools/list 到一次真实工具调用Web 模式最推荐。在项目目录执行npx modelcontextprotocol/inspector node build/index.js终端会打印一个本地地址浏览器打开后你会看到几个区域Tools 列出add、greetResources 和 Prompts 当前为空Notifications / Console 看服务端日志Protocol / Messages 看原始 JSON-RPC 报文。先看 Tools 面板确认add和greet都出现了。如果这里为空说明工具没注册成功先别往下走。点开add参数表单里a填3b填5点击运行。返回应该是{ content: [ { type: text, text: 8 } ] }再调greetname填小明返回{ content: [ { type: text, text: 你好小明欢迎使用 MCP Demo Server。 } ] }如果你想在 CI 里做连通性检查用 CLI 模式更干净npx modelcontextprotocol/inspector --cli node build/index.js --method tools/list它会列出工具后退出返回非零退出码就说明握手或注册有问题。TUI 模式则适合服务器上没有浏览器的场景npx modelcontextprotocol/inspector --tui node build/index.js调通之后如果你要接远程 HTTP 类型的 ServerInspector 也支持npx modelcontextprotocol/inspector --server-url https://example.com/mcp --transport http带认证时用环境变量传 token别在命令里明文写export API_TOKENxxxx npx modelcontextprotocol/inspector --server-url https://example.com/mcp --transport http -e AUTHORIZATIONBearer $API_TOKEN5. 本篇常见错排查握手失败、工具为空、参数变字符串工具列表为空。先检查server.tool()是否真的在server.connect()之前调用再确认 Inspector 连接的命令对不对比如是node build/index.js而不是只写build/index.js最后确认 Server 用的是 stdio 传输而不是 HTTP。一连接就断开或报解析错误。这是 stdio 模式最经典的坑stdout 被协议占用任何console.log都会破坏 JSON-RPC 流。错误写法console.log(start server); // 会污染协议流正确做法是日志走 stderrconsole.error(debug info); // 或者用 logging 库输出到 stderr参数框不对全变成字符串或没有描述。这是 schema 没写清楚。用 zod 定义类型z.number()会渲染成数字框z.string()是文本框z.boolean()是开关工具描述写在server.tool()的第二个参数里会显示在界面上。改了代码没生效。stdio Server 是被 Inspector 作为子进程启动的改完代码要重新 build然后在 Web 界面点重新连接或者退出 Inspector 再跑一次命令。Node 版本报错。升级到 22.19.0 再试nvm install 22 nvm use 22。Inspector 里行但客户端不行。这说明 Server 本身没问题问题在客户端配置。这时候去检查客户端的 MCP 配置路径、命令参数、环境变量。如果你用的是 Claude Code 这类工具接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的配置示例。6. 调通之后从 Inspector 到真实客户端的接入路径Inspector 调通只完成了一半接下来要把它接到真实客户端。推荐顺序是先 Inspector Web 模式确认工具列表和调用都正常再用 CLI 模式做一次自动化检查最后才接客户端。这样排错边界很清楚——Inspector 里不行就是 Server 问题Inspector 里行但客户端不行就是客户端配置问题。接客户端时你需要一个模型 API 入口。我自己的流程是先在 TaoToken 把 API Key 建好地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 然后根据用途分流如果只是验证模型对话和工具调用用模型对话页 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 快速试如果是长期跑编码 Agent、需要稳定的额度用 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 更合适如果你用 Claude Code 这类 Anthropic 协议客户端接入说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 。最后给一个我踩过的坑stdio 模式下 Server 的启动命令里不要带交互式参数比如需要手动输入密码的命令Inspector spawn 子进程时没法交互会直接卡住。所有配置走环境变量或命令行参数传进去。