调试 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 服务器继承的环境变量子集

怎么做

使用调试工具

MCP Inspector：
- 连接到 stdio 或 Streamable HTTP 服务器
- 调用 tools、prompts 和 resources
- 观察通知流
服务器日志：
- stdio 传输：日志自动输出到 stderr
- Streamable HTTP 传输：使用日志消息通知或 HTTP 工具检查
客户端开发者工具：
- 检查客户端日志和连接状态
- 在 Claude Desktop 中查看可用工具和连接状态

实现日志记录

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

发送日志消息通知：

@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

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

查看日志：

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

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

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

使用 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)

解决常见问题

工作目录问题：
- 使用绝对路径而非相对路径
- 在配置文件中指定完整路径

环境变量问题：

在配置中指定 env 键：

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

服务器初始化问题：
- 检查路径问题
- 验证配置错误
- 解决环境问题
连接问题：
- 检查客户端日志
- 验证服务器进程运行状态
- 使用 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 在代理系统中的应用，本章提供了调试这些集成所需的具体工具和技术

初学者易错点

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

语义检索

调试 MCP 集成

一句话

什么时候翻这页

核心概念

怎么做

使用调试工具

实现日志记录

调试 Claude Desktop

解决常见问题

命令 / 配置速查

配置文件示例

日志级别

日志位置

与 Claude Code / Hello-Agents 的联系

初学者易错点

相关词条