调试 MCP 集成

原文：调试 MCP 集成

一句话

MCP 提供多种调试工具和方法，包括 MCP Inspector、服务器日志和客户端开发者工具，帮助开发者有效调试 MCP 服务器集成。

什么时候翻这页

• 开发 MCP 服务器时遇到问题
• 集成 MCP 服务器到应用程序时出现故障
• 需要检查工具、提示或资源调用情况
• 遇到连接问题或初始化错误
• 需要监控服务器性能和错误处理

核心概念

• MCP Inspector：交互式、传输无关的测试 UI，可连接到 stdio 或 Streamable HTTP 服务器，调用 tools、prompts 和 resources，并查看通知流
• 服务器日志：结构化日志输出到 stderr（stdio 传输）或通过 notifications/message（所有传输）
• 客户端开发者工具：大多数 MCP 客户端暴露日志和连接状态
• 日志消息通知：服务器可通过发送日志消息通知向客户端提供日志
• RFC 5424 严重级别：MCP 定义了八个日志级别（从 debug 到 emergency）
• 工作目录：MCP 客户端启动 stdio 服务器时的当前目录
• 环境变量：stdio 服务器继承的环境变量子集

怎么做

使用调试工具

1. MCP Inspector：

   • 连接到 stdio 或 Streamable HTTP 服务器
   • 调用 tools、prompts 和 resources
   • 观察通知流

2. 服务器日志：

   • stdio 传输：日志自动输出到 stderr
   • Streamable HTTP 传输：使用日志消息通知或 HTTP 工具检查

3. 客户端开发者工具：

   • 检查客户端日志和连接状态
   • 在 Claude Desktop 中查看可用工具和连接状态

实现日志记录

1. 服务器端日志：

   • stdio 传输：日志输出到 stderr
   • 避免输出到 stdout，会干扰协议操作
   • Streamable HTTP 传输：使用日志消息通知

2. 发送日志消息通知：

   @server.tool()
   async def my_tool(ctx: Context) -> str:
       await ctx.session.send_log_message(
           level="info",
           data="Server started successfully",
       )
       return "done"
   

   await server.sendLoggingMessage({
       level: "info",
       data: "Server started successfully",
   });
   

调试 Claude Desktop

1. 检查服务器状态：

   • 点击聊天输入框的"+"图标
   • 悬停在"Connectors"菜单上查看连接的服务器和可用工具

2. 查看日志：

   • macOS: ~/Library/Logs/Claude
   • Windows: %APPDATA%\Claude\logs

   tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
   

   type "$env:AppData\Claude\logs\mcp*.log"
   

3. 使用 Chrome DevTools：

   • 创建 developer_settings.json 文件：

     echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
     

     '{"allowDevTools": true}' | Set-Content "$env:AppData\Claude\developer_settings.json"
     

   • 打开 DevTools：Command-Option-I (macOS) 或 Ctrl+Alt+I (Windows)

解决常见问题

1. 工作目录问题：

   • 使用绝对路径而非相对路径
   • 在配置文件中指定完整路径

2. 环境变量问题：

   • 在配置中指定 env 键：

     {
       "mcpServers": {
         "myserver": {
           "command": "mcp-server-myapp",
           "env": {
             "MYAPP_API_KEY": "some_key"
           }
         }
       }
     }
     

3. 服务器初始化问题：

   • 检查路径问题
   • 验证配置错误
   • 解决环境问题

4. 连接问题：

   • 检查客户端日志
   • 验证服务器进程运行状态
   • 使用 Inspector 测试
   • 验证协议兼容性和能力协商

命令 / 配置速查

配置文件示例

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/data"
      ]
    },
    "myserver": {
      "command": "mcp-server-myapp",
      "env": {
        "MYAPP_API_KEY": "some_key"
      }
    }
  }
}

日志级别

• debug
• info
• notice
• warning
• error
• critical
• alert
• emergency

日志位置

• macOS: ~/Library/Logs/Claude
• Windows: %APPDATA%\Claude\logs

与 Claude Code / Hello-Agents 的联系

• 在 Claude Code 手册的 MCP 章节中介绍了 MCP 的基本概念，本章深入探讨了调试 MCP 集成的具体方法
• Hello-Agents 第 10 章讨论了 MCP 在代理系统中的应用，本章提供了调试这些集成所需的具体工具和技术

初学者易错点

1. 工作目录误解：假设服务器在预期的工作目录中启动，实际可能是未定义的目录（如 macOS 上的 /）
2. 环境变量缺失：stdio 服务器只继承有限的环境变量，需要显式指定
3. 日志输出错误：将日志输出到 stdout 而非 stderr，会干扰协议操作
4. 配置语法错误：JSON 配置文件中的语法错误或类型不匹配
5. 连接问题：忽略协议兼容性和能力协商检查，导致连接失败

相关词条

• MCP Inspector
• 构建 MCP 服务器
• 连接本地服务器
• 安全最佳实践