教程文档人工智能【免费下载链接】mcp-for-beginnersThis 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 ProtocolMCP官方提供的交互式调试工具常被形象地称为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 18npm随 Node.js 一并安装一个可供测试的 MCP 服务器——如果还没有可以先完成 模块 3.1第一个服务器那里提供了 Python、TypeScript、.NET、Java、Rust 等语言的完整示例也可直接使用 03-GettingStarted/samples 中的计算器样例如 Java 计算器。安装 InspectorInspector 是一个基于 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结尾的命令测试的是旧版 HTTPSSE 传输。对于基于 MCP2026-07-28协议的新服务器请使用支持Streamable HTTP的 Inspector 版本并在界面中选择该传输类型。关于新旧协议的区别可参考仓库中的 01-CoreConcepts/mcp-2026-07-28.md2026-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_KEYxxx npx modelcontextprotocol/inspector python server.py模块 05-stdio-server 中给出了同样的调用形式npx modelcontextprotocol/inspector python server.py并指出启动后可以在网页界面中查看服务器能力、用不同参数测试工具、监视 JSON-RPC 消息并排查连接问题。连接 SSE/HTTP 服务器网络服务对于以 HTTP 服务形式运行的服务器需要分两步先启动服务器python server.py # 服务器运行在 http://localhost:8080再启动 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列出可用工具点击Tools标签页Inspector 会自动调用tools/list界面会展示所有已注册工具包含三要素工具名称name描述description输入模式input schema即参数定义调用一个工具从列表中选择目标工具在表单中填写所需参数点击Run Tool在结果面板中查看响应。示例测试一个加法计算器工具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列出资源点击Resources标签页Inspector 调用resources/list界面展示资源 URI名称与描述MIME 类型读取一个资源选择一个资源点击Read Resource查看返回的内容。示例输出Resource: file:///config/settings.json Content-Type: application/json { config: { debug: true, maxConnections: 10 } }测试提示词Prompts列出提示词点击Prompts标签页Inspector 调用prompts/list查看服务器提供的提示词模板列表。获取一个提示词选择一个提示词填写需要的参数arguments点击Get Prompt查看渲染后的提示词消息rendered prompt messages。消息日志分析消息日志Message Log记录服务器交互过程中的所有 MCP 协议消息。下面的转录来自一台基于旧版2025-11-25协议的服务器其中包含已被移除的initialize握手而2026-07-28协议的服务器改用自包含的请求元数据与server/discover14: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 a1 --tool-arg b2预期输出{ 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...。检查清单✅ 服务器启动命令是否正确✅ 依赖是否都已安装✅ 服务器路径是绝对路径还是相对于当前目录的相对路径✅ 必需的环境变量是否已设置排查步骤# 先手动验证服务器模块能否导入 python -c import your_server_module; print(OK) # 检查导入错误 python -m your_server_module 21 | head -20 # 确认 MCP SDK 已安装 pip show mcp场景二工具不显示症状Tools 标签页显示空列表。可能原因工具未在服务器初始化阶段注册服务器启动后立即崩溃tools/list处理器返回了空数组。排查步骤检查消息日志中tools/list的响应在工具注册代码处添加日志输出确认 Python 服务器中mcp.tool()装饰器是否齐全。场景三工具调用返回错误症状工具调用返回错误响应。排查思路仔细阅读错误消息检查参数类型是否与输入模式schema匹配在工具逻辑中加入 try/catch 并输出详细错误信息查看服务器日志中的堆栈跟踪。改进后的错误处理示例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(fInvalid parameter: {e}) except Exception as e: raise McpError(fTool failed: {type(e).__name__}: {e})将底层异常包装为携带上下文信息的McpError能让 Inspector 界面上呈现的错误消息对排查更有帮助。场景四资源内容为空症状资源读取成功返回但内容为空或 null。检查清单✅ 文件路径或 URI 是否正确✅ 服务器是否具备读取该资源的权限✅ 资源内容是否正确返回而非被吞掉。高级功能自定义请求头SSE向 SSE 连接注入自定义头例如携带认证凭据npx modelcontextprotocol/inspector \ --sse http://localhost:8080/sse \ --header Authorization: Bearer your-token详细日志输出通过DEBUGmcp*环境变量开启 MCP 相关的调试日志DEBUGmcp* npx modelcontextprotocol/inspector python server.py记录会话Inspector 支持导出消息日志以便事后分析在消息面板中点击Export Log保存为 JSON 文件分享给团队成员协助排查。最佳实践尽早、频繁地测试——在开发过程中持续使用 Inspector而不是等出问题才想起它从简单开始——先验证基本连接再执行复杂工具调用检查 Schema——许多错误源于参数类型与输入模式不匹配读懂错误消息——MCP 的错误信息通常具有描述性先读清楚再动手保持 Inspector 常开——边开发边观察能更早捕获回归问题。继续学习完成本模块后你已经掌握了 MCP 服务器的交互式调试手段可以继续深入学习模块 4实战实现分页等模块 5进阶主题采样、安全、路由、扩展等更完整的测试方法论见 模块 3.8测试与调试如果希望先按部就班搭建第一个服务器可从 模块 3.1第一个服务器 开始赞分享教程文档人工智能【免费下载链接】mcp-for-beginnersThis 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-for-beginners 实战用 TypeScript 构建并调试 MCP 工具服务器Node.js Zod MCP Inspectormcp for beginners 实战用 TypeScript 构建并调试 MCP 工具服务器Node.js Zod MCP Inspector教程文档人工智能MCP协议调试工具mcp-for-beginners Inspector使用指南MCP协议调试工具mcp for beginners Inspector使用指南 概述 MCPModel Context Protocol模型上下文协议教程文档人工智能MCP 服务器测试与调试完全指南Inspector、curl 与单元测试实战mcp-for-beginnersMCP 服务器测试与调试完全指南Inspector、curl 与单元测试实战mcp for beginners 本篇技术指南以 mcp for begin教程文档人工智能上一篇Competitive Analysis Schemas 参考指南MA 交易表、情景分析与幻灯片结构规范financial-services 仓库实战下一篇Apache Airflow Redis Provider 使用指南基于 RedisHook 与 RedisPublishOperator 构建 DAG 的 Redis 集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/10 9:06:26 · 阅读 1.2k 使用 MCP Inspector 调试 MCP 服务器：mcp-for-beginners 实战指南
教程文档人工智能【免费下载链接】mcp-for-beginnersThis 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 ProtocolMCP官方提供的交互式调试工具常被形象地称为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 18npm随 Node.js 一并安装一个可供测试的 MCP 服务器——如果还没有可以先完成 模块 3.1第一个服务器那里提供了 Python、TypeScript、.NET、Java、Rust 等语言的完整示例也可直接使用 03-GettingStarted/samples 中的计算器样例如 Java 计算器。安装 InspectorInspector 是一个基于 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结尾的命令测试的是旧版 HTTPSSE 传输。对于基于 MCP2026-07-28协议的新服务器请使用支持Streamable HTTP的 Inspector 版本并在界面中选择该传输类型。关于新旧协议的区别可参考仓库中的 01-CoreConcepts/mcp-2026-07-28.md2026-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_KEYxxx npx modelcontextprotocol/inspector python server.py模块 05-stdio-server 中给出了同样的调用形式npx modelcontextprotocol/inspector python server.py并指出启动后可以在网页界面中查看服务器能力、用不同参数测试工具、监视 JSON-RPC 消息并排查连接问题。连接 SSE/HTTP 服务器网络服务对于以 HTTP 服务形式运行的服务器需要分两步先启动服务器python server.py # 服务器运行在 http://localhost:8080再启动 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列出可用工具点击Tools标签页Inspector 会自动调用tools/list界面会展示所有已注册工具包含三要素工具名称name描述description输入模式input schema即参数定义调用一个工具从列表中选择目标工具在表单中填写所需参数点击Run Tool在结果面板中查看响应。示例测试一个加法计算器工具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列出资源点击Resources标签页Inspector 调用resources/list界面展示资源 URI名称与描述MIME 类型读取一个资源选择一个资源点击Read Resource查看返回的内容。示例输出Resource: file:///config/settings.json Content-Type: application/json { config: { debug: true, maxConnections: 10 } }测试提示词Prompts列出提示词点击Prompts标签页Inspector 调用prompts/list查看服务器提供的提示词模板列表。获取一个提示词选择一个提示词填写需要的参数arguments点击Get Prompt查看渲染后的提示词消息rendered prompt messages。消息日志分析消息日志Message Log记录服务器交互过程中的所有 MCP 协议消息。下面的转录来自一台基于旧版2025-11-25协议的服务器其中包含已被移除的initialize握手而2026-07-28协议的服务器改用自包含的请求元数据与server/discover14: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 a1 --tool-arg b2预期输出{ 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...。检查清单✅ 服务器启动命令是否正确✅ 依赖是否都已安装✅ 服务器路径是绝对路径还是相对于当前目录的相对路径✅ 必需的环境变量是否已设置排查步骤# 先手动验证服务器模块能否导入 python -c import your_server_module; print(OK) # 检查导入错误 python -m your_server_module 21 | head -20 # 确认 MCP SDK 已安装 pip show mcp场景二工具不显示症状Tools 标签页显示空列表。可能原因工具未在服务器初始化阶段注册服务器启动后立即崩溃tools/list处理器返回了空数组。排查步骤检查消息日志中tools/list的响应在工具注册代码处添加日志输出确认 Python 服务器中mcp.tool()装饰器是否齐全。场景三工具调用返回错误症状工具调用返回错误响应。排查思路仔细阅读错误消息检查参数类型是否与输入模式schema匹配在工具逻辑中加入 try/catch 并输出详细错误信息查看服务器日志中的堆栈跟踪。改进后的错误处理示例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(fInvalid parameter: {e}) except Exception as e: raise McpError(fTool failed: {type(e).__name__}: {e})将底层异常包装为携带上下文信息的McpError能让 Inspector 界面上呈现的错误消息对排查更有帮助。场景四资源内容为空症状资源读取成功返回但内容为空或 null。检查清单✅ 文件路径或 URI 是否正确✅ 服务器是否具备读取该资源的权限✅ 资源内容是否正确返回而非被吞掉。高级功能自定义请求头SSE向 SSE 连接注入自定义头例如携带认证凭据npx modelcontextprotocol/inspector \ --sse http://localhost:8080/sse \ --header Authorization: Bearer your-token详细日志输出通过DEBUGmcp*环境变量开启 MCP 相关的调试日志DEBUGmcp* npx modelcontextprotocol/inspector python server.py记录会话Inspector 支持导出消息日志以便事后分析在消息面板中点击Export Log保存为 JSON 文件分享给团队成员协助排查。最佳实践尽早、频繁地测试——在开发过程中持续使用 Inspector而不是等出问题才想起它从简单开始——先验证基本连接再执行复杂工具调用检查 Schema——许多错误源于参数类型与输入模式不匹配读懂错误消息——MCP 的错误信息通常具有描述性先读清楚再动手保持 Inspector 常开——边开发边观察能更早捕获回归问题。继续学习完成本模块后你已经掌握了 MCP 服务器的交互式调试手段可以继续深入学习模块 4实战实现分页等模块 5进阶主题采样、安全、路由、扩展等更完整的测试方法论见 模块 3.8测试与调试如果希望先按部就班搭建第一个服务器可从 模块 3.1第一个服务器 开始赞分享教程文档人工智能【免费下载链接】mcp-for-beginnersThis 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-for-beginners 实战用 TypeScript 构建并调试 MCP 工具服务器Node.js Zod MCP Inspectormcp for beginners 实战用 TypeScript 构建并调试 MCP 工具服务器Node.js Zod MCP Inspector教程文档人工智能MCP协议调试工具mcp-for-beginners Inspector使用指南MCP协议调试工具mcp for beginners Inspector使用指南 概述 MCPModel Context Protocol模型上下文协议教程文档人工智能MCP 服务器测试与调试完全指南Inspector、curl 与单元测试实战mcp-for-beginnersMCP 服务器测试与调试完全指南Inspector、curl 与单元测试实战mcp for beginners 本篇技术指南以 mcp for begin教程文档人工智能上一篇Competitive Analysis Schemas 参考指南MA 交易表、情景分析与幻灯片结构规范financial-services 仓库实战下一篇Apache Airflow Redis Provider 使用指南基于 RedisHook 与 RedisPublishOperator 构建 DAG 的 Redis 集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考