news 2026/10/19 7:16:17

使用 MCP Inspector 调试 MCP 服务器：mcp-for-beginners 实战指南

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
使用 MCP Inspector 调试 MCP 服务器：mcp-for-beginners 实战指南
  • 教程
  • 文档
  • 人工智能

【免费下载链接】mcp-for-beginners

This open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.

项目地址：https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners
点击查看免费下载

MCP Inspector 是 Model Context Protocol（MCP）官方提供的交互式调试工具，常被形象地称为"MCP 世界的 Postman"。在本课程（mcp-for-beginners）的模块 13-mcp-inspector 中，它被用于在无需启动完整 AI 宿主应用的前提下，对 MCP 服务器进行连接验证、工具调用、资源读取与提示词测试。阅读本文后，你将掌握 Inspector 的三种安装方式、stdio 与 HTTP 两类传输的连接方法、界面各功能区的用法、CLI 模式下的自动化调试技巧，以及四类常见故障的排查流程。

为什么使用 MCP Inspector

在构建 MCP 服务器时，开发者经常会遇到下面四类问题，而 Inspector 恰好逐一给出答案：

  • "我的服务器到底跑起来了吗？"—— Inspector 直接显示连接状态（Connected / Disconnected）；
  • "我的工具注册正确吗？"—— Inspector 自动调用tools/list并列出全部可用工具；
  • "响应格式是什么样的？"—— Inspector 展示完整的 JSON 响应；
  • "为什么这个工具不工作？"—— Inspector 输出包含错误码与消息的详细错误响应。

模块 08-testing 从更高层面总结了 MCP 官方的三种测试途径：MCP Inspector（命令行与可视化双模式）、手工测试（如使用 curl 直接发起 HTTP 请求）、单元测试（基于 pytest 等框架验证服务器与客户端行为）。Inspector 是其中交互体验最好、上手门槛最低的一种，适合开发阶段反复验证服务器能力。

前置条件

在开始之前，请确认环境满足以下要求：

  • 已安装 Node.js 18+；
  • npm（随 Node.js 一并安装）；
  • 一个可供测试的 MCP 服务器——如果还没有，可以先完成 模块 3.1：第一个服务器，那里提供了 Python、TypeScript、.NET、Java、Rust 等语言的完整示例；也可直接使用 03-GettingStarted/samples 中的计算器样例（如 Java 计算器）。

安装 Inspector

Inspector 是一个基于 Node.js 构建的工具（见 08-testing 的说明），提供了三种安装方式：

方式一：使用 npx 直接运行（推荐用于快速测试）

无需安装任何东西，npx 会临时下载并执行 Inspector，任务结束后自动清理：

npx @modelcontextprotocol/inspector

方式二：全局安装

npm install -g @modelcontextprotocol/inspector mcp-inspector

方式三：添加到项目作为开发依赖

cd your-mcp-server-project npm install --save-dev @modelcontextprotocol/inspector

然后在package.json中注册一个 npm script，方便团队复用：

{ "scripts": { "inspector": "mcp-inspector" } }

之后即可通过npm run inspector启动。参考仓库中的示例工程（如 02-client 的 TypeScript 工程、05-stdio-server 的 TypeScript 工程），可以看到将 Inspector 作为开发依赖（devDependencies）引入是仓库推荐的常见做法。

连接你的服务器

Inspector 支持两类 MCP 传输：stdio（本地进程，通过标准输入/输出通信）与HTTP/SSE（网络服务）。此外还需要注意新版协议对传输类型的约束。

[!NOTE] 使用--sse参数、URL 以/sse结尾的命令，测试的是旧版 HTTP+SSE 传输。对于基于 MCP2026-07-28协议的新服务器，请使用支持Streamable HTTP的 Inspector 版本，并在界面中选择该传输类型。

关于新旧协议的区别，可参考仓库中的 01-CoreConcepts/mcp-2026-07-28.md：2026-07-28协议取消了initialize握手，改用自包含的请求元数据与server/discover，这一点在后续"消息日志分析"小节中还会展开。

连接 stdio 服务器（本地进程）

对于通过标准输入/输出通信的服务器，直接把服务器启动命令作为 Inspector 的参数传入：

# Python 服务器 npx @modelcontextprotocol/inspector python -m your_server_module # Node.js 服务器 npx @modelcontextprotocol/inspector node ./build/index.js # 带环境变量启动 OPENAI_API_KEY=xxx npx @modelcontextprotocol/inspector python server.py

模块 05-stdio-server 中给出了同样的调用形式（npx @modelcontextprotocol/inspector python server.py），并指出启动后可以在网页界面中查看服务器能力、用不同参数测试工具、监视 JSON-RPC 消息并排查连接问题。

连接 SSE/HTTP 服务器（网络服务）

对于以 HTTP 服务形式运行的服务器，需要分两步：

  1. 先启动服务器：

    python server.py # 服务器运行在 http://localhost:8080

  2. 再启动 Inspector 并指定 SSE 端点：

    npx @modelcontextprotocol/inspector --sse http://localhost:8080/sse

对于新版 Streamable HTTP 服务器，仓库中的 .NET HTTP Streaming 示例运行说明 演示了更直接的连接方式：服务器运行后，直接运行

npx @modelcontextprotocol/inspector http://localhost:3001

并确保传输类型选择 Streamable HTTP、URL 填写为http://localhost:3001/mcp。连接成功后即可列出工具、调用add（传参 2 和 4，期望结果为 6），再前往 Resources 标签调用名为 greeting 的资源模板。

Inspector 界面概览

Inspector 启动后会打开一个 Web 界面（默认地址为http://localhost:5173），整体布局如下：

┌─────────────────────────────────────────────────────────────┐ │ MCP Inspector [Connected ✅] │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 🔧 Tools │ │ 📄 Resources│ │ 💬 Prompts │ │ │ │ (3) │ │ (2) │ │ (1) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ 📋 Message Log │ │ │ │ ─────────────────────────────────────────────────── │ │ │ │ → initialize │ │ │ │ ← initialized (server info) │ │ │ │ → tools/list │ │ │ │ ← tools (3 tools) │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘

左侧面板用于配置传输类型与目标地址、查看连接状态；顶部的Tools / Resources / Prompts三个标签页分别对应 MCP 的三大能力原语；底部的Message Log（消息日志）实时滚动展示每一次协议交互。下面这张图展示了调试工具时的完整操作链路：从工具列表中选择工具、填写参数、执行到查看结果与调用历史。

测试工具（Tools）

列出可用工具

  1. 点击Tools标签页；
  2. Inspector 会自动调用tools/list；
  3. 界面会展示所有已注册工具，包含三要素：
    • 工具名称（name）
    • 描述（description）
    • 输入模式（input schema，即参数定义）

调用一个工具

  1. 从列表中选择目标工具；
  2. 在表单中填写所需参数；
  3. 点击Run Tool；
  4. 在结果面板中查看响应。

示例：测试一个加法计算器工具

Tool: add Parameters: a: 25 b: 17 Response: { "content": [ { "type": "text", "text": "42" } ] }

调试工具错误

当工具调用失败时，Inspector 会展示标准 JSON-RPC 错误响应：

Error Response: { "error": { "code": -32602, "message": "Invalid params: 'b' is required" } }

常见的错误码含义如下表：

代码含义
-32700解析错误（JSON 无效）
-32600无效请求
-32601方法不存在
-32602参数无效
-32603内部错误

测试资源（Resources）

列出资源

  1. 点击Resources标签页；
  2. Inspector 调用resources/list；
  3. 界面展示：
    • 资源 URI
    • 名称与描述
    • MIME 类型

读取一个资源

  1. 选择一个资源；
  2. 点击Read Resource；
  3. 查看返回的内容。

示例输出：

Resource: file:///config/settings.json Content-Type: application/json { "config": { "debug": true, "maxConnections": 10 } }

测试提示词（Prompts）

列出提示词

  1. 点击Prompts标签页；
  2. Inspector 调用prompts/list；
  3. 查看服务器提供的提示词模板列表。

获取一个提示词

  1. 选择一个提示词；
  2. 填写需要的参数（arguments）；
  3. 点击Get Prompt；
  4. 查看渲染后的提示词消息（rendered prompt messages）。

消息日志分析

消息日志（Message Log）记录服务器交互过程中的所有 MCP 协议消息。下面的转录来自一台基于旧版2025-11-25协议的服务器，其中包含已被移除的initialize握手；而2026-07-28协议的服务器改用自包含的请求元数据与server/discover：

14:32:01 → {"jsonrpc":"2.0","id":1,"method":"initialize",...} 14:32:01 ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25",...}} 14:32:02 → {"jsonrpc":"2.0","id":2,"method":"tools/list"} 14:32:02 ← {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}} 14:32:05 → {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add",...}} 14:32:05 ← {"jsonrpc":"2.0","id":3,"result":{"content":[...]}}

观察要点

  • 请求/响应配对：每一个→（请求）都应有一个对应的←（响应）；
  • 错误消息：在响应中留意"error"字段；
  • 时间间隔：请求与响应之间出现明显空档，可能暗示性能问题；
  • 协议版本：确认服务器与客户端协商的protocolVersion一致。

在 CLI 模式下使用 Inspector

除了网页界面，Inspector 还支持--cli模式，适合脚本化与 CI/CD 场景，运行速度通常比浏览器模式更快。仓库中的 .NET HTTP Streaming 示例运行说明 给出了完整的 CLI 用法。

列出服务器上的全部工具：

npx @modelcontextprotocol/inspector --cli http://localhost:3001 --method tools/list

预期输出（以示例服务器的 AddNumbers 工具为例）：

{ "tools": [ { "name": "AddNumbers", "description": "Add two numbers together.", "inputSchema": { "type": "object", "properties": { "a": { "description": "The first number", "type": "integer" }, "b": { "description": "The second number", "type": "integer" } }, "title": "AddNumbers", "description": "Add two numbers together.", "required": [ "a", "b" ] } } ] }

调用一个工具并传参：

npx @modelcontextprotocol/inspector --cli http://localhost:3001 --method tools/call --tool-name AddNumbers --tool-arg a=1 --tool-arg b=2

预期输出：

{ "content": [ { "type": "text", "text": "3" } ], "isError": false }

CLI 模式的关键参数为：--cli（启用命令行模式）、--method（要调用的协议方法，如tools/list、tools/call）、--tool-name（工具名）与--tool-arg（键值对形式的参数，可重复传入）。对应 stdio 服务器，CLI 模式同样适用，例如 08-testing 中演示的npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list。

与 VS Code 集成

Inspector 可以直接嵌入 VS Code 的调试与任务体系。

使用 launch.json

在.vscode/launch.json中添加如下配置：

{ "version": "0.2.0", "configurations": [ { "name": "Debug with MCP Inspector", "type": "node", "request": "launch", "runtimeExecutable": "npx", "runtimeArgs": [ "@modelcontextprotocol/inspector", "python", "${workspaceFolder}/server.py" ], "console": "integratedTerminal" }, { "name": "Debug SSE Server with Inspector", "type": "chrome", "request": "launch", "url": "http://localhost:5173", "preLaunchTask": "Start MCP Inspector" } ] }

其中第一个配置通过runtimeExecutable: npx直接拉起 Inspector 并连接 Python 服务器；第二个配置面向 SSE/HTTP 服务器，先用preLaunchTask启动 Inspector，再用 Chrome 调试器打开其 Web 界面（http://localhost:5173）。

使用 tasks.json

在.vscode/tasks.json中添加后台任务：

{ "version": "2.0.0", "tasks": [ { "label": "Start MCP Inspector", "type": "shell", "command": "npx @modelcontextprotocol/inspector node ${workspaceFolder}/build/index.js", "isBackground": true, "problemMatcher": { "pattern": { "regexp": "^$" }, "background": { "activeOnStart": true, "beginsPattern": "Inspector", "endsPattern": "listening" } } } ] }

isBackground: true配合problemMatcher.background中的beginsPattern/endsPattern，让 VS Code 能识别"Inspector 已启动并在监听"这一状态，从而与上面的 Chrome 调试配置联动。

常见调试场景与排查流程

场景一：服务器无法连接

症状：Inspector 显示"Disconnected"或一直卡在"Connecting..."。

检查清单：

  1. ✅ 服务器启动命令是否正确？
  2. ✅ 依赖是否都已安装？
  3. ✅ 服务器路径是绝对路径，还是相对于当前目录的相对路径？
  4. ✅ 必需的环境变量是否已设置？

排查步骤：

# 先手动验证服务器模块能否导入 python -c "import your_server_module; print('OK')" # 检查导入错误 python -m your_server_module 2>&1 | head -20 # 确认 MCP SDK 已安装 pip show mcp

场景二：工具不显示

症状：Tools 标签页显示空列表。

可能原因：

  1. 工具未在服务器初始化阶段注册；
  2. 服务器启动后立即崩溃；
  3. tools/list处理器返回了空数组。

排查步骤：

  1. 检查消息日志中tools/list的响应；
  2. 在工具注册代码处添加日志输出；
  3. 确认 Python 服务器中@mcp.tool()装饰器是否齐全。

场景三：工具调用返回错误

症状：工具调用返回错误响应。

排查思路：

  1. 仔细阅读错误消息；
  2. 检查参数类型是否与输入模式（schema）匹配；
  3. 在工具逻辑中加入 try/catch 并输出详细错误信息；
  4. 查看服务器日志中的堆栈跟踪。

改进后的错误处理示例：

@mcp.tool() async def my_tool(param1: str, param2: int) -> str: try: # 工具逻辑 result = process(param1, param2) return str(result) except ValueError as e: raise McpError(f"Invalid parameter: {e}") except Exception as e: raise McpError(f"Tool failed: {type(e).__name__}: {e}")

将底层异常包装为携带上下文信息的McpError，能让 Inspector 界面上呈现的错误消息对排查更有帮助。

场景四：资源内容为空

症状：资源读取成功返回，但内容为空或 null。

检查清单：

  1. ✅ 文件路径或 URI 是否正确；
  2. ✅ 服务器是否具备读取该资源的权限；
  3. ✅ 资源内容是否正确返回（而非被吞掉）。

高级功能

自定义请求头（SSE）

向 SSE 连接注入自定义头（例如携带认证凭据）：

npx @modelcontextprotocol/inspector \ --sse http://localhost:8080/sse \ --header "Authorization: Bearer your-token"

详细日志输出

通过DEBUG=mcp*环境变量开启 MCP 相关的调试日志：

DEBUG=mcp* npx @modelcontextprotocol/inspector python server.py

记录会话

Inspector 支持导出消息日志以便事后分析：

  1. 在消息面板中点击Export Log；
  2. 保存为 JSON 文件；
  3. 分享给团队成员协助排查。

最佳实践

  1. 尽早、频繁地测试——在开发过程中持续使用 Inspector，而不是等出问题才想起它；
  2. 从简单开始——先验证基本连接，再执行复杂工具调用；
  3. 检查 Schema——许多错误源于参数类型与输入模式不匹配；
  4. 读懂错误消息——MCP 的错误信息通常具有描述性，先读清楚再动手；
  5. 保持 Inspector 常开——边开发边观察，能更早捕获回归问题。

继续学习

完成本模块后，你已经掌握了 MCP 服务器的交互式调试手段，可以继续深入学习：

  • 模块 4：实战实现（分页等）
  • 模块 5：进阶主题（采样、安全、路由、扩展等）
  • 更完整的测试方法论见 模块 3.8：测试与调试
  • 如果希望先按部就班搭建第一个服务器，可从 模块 3.1：第一个服务器 开始
  • 教程
  • 文档
  • 人工智能

【免费下载链接】mcp-for-beginners

This open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.

项目地址：https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners
点击查看免费下载
上一篇：Competitive Analysis Schemas 参考指南：M&A 交易表、情景分析与幻灯片结构规范（financial-services 仓库实战）
下一篇：Apache Airflow Redis Provider 使用指南：基于 RedisHook 与 RedisPublishOperator 构建 DAG 的 Redis 集成

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/10/19 7:15:29

基于Spring Boot+Vue的毕业论文选题管理系统设计与实现

每年一到毕业季，导师群和教务群就会被选题表、改题申请、重复课题的交锋反复轰炸。学生不知道哪些题目还能选，导师不清楚哪个学生已经占坑，教务管理员更是要对着Excel表格手动核对上限人数——这种情况我曾经完整经历过一遍，所以当…

作者头像 李华
网站建设 2026/10/16 12:45:26

tailwind-patterns - SKILL

name: tailwind-patterns description: “Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.” risk: none source: community date_added: “2026-02-27” Tailwind CSS 模式（v4 - 2025&…

作者头像 李华
网站建设 2026/10/17 11:29:34

teach - GLOSSARY-FORMAT

GLOSSARY.md 格式 GLOSSARY.md 是此教学工作区的规范语言。所有讲解、练习和学习记录都应遵循其术语。构建它本身就是学习的一部分：把一个概念压缩成精确定义，正是用户理解它的证据。 结构 # {主题} 术语表{一两句话描述此术语表涵盖的主题。}## 术语**肥…

作者头像 李华
网站建设 2026/10/16 8:17:22

swiftui-expert-skill - localization

SwiftUI 本地化参考 面向用户的文本指导：Text、Button、Label、导航/工具栏标题、alert 以及携带可本地化字符串的类型。关于单个 Text 上更窄的"verbatim 与本地化"决策，请参阅 references/text-patterns.md。 目录 SwiftUI 自动本地化字符…

作者头像 李华