调试

​

调试工具概览

1. MCP Inspector：交互式、与传输无关的 测试界面。可连接到 stdio 或 Streamable HTTP 服务器，调用 工具、 提示 和 资源，并观察 通知流。这应该是你的首选入口。
2. 服务器日志：通过 stderr（stdio 传输）输出结构化日志，或通过 OpenTelemetry（所有传输）输出。 协议内的 日志记录 （notifications/message）自协议版本 2026-07-28 起已弃用。
3. 客户端开发者工具：大多数 MCP 客户端都会暴露日志和连接 状态。例如下面的 在 Claude Desktop 中调试 是一个示例，或者查阅你所使用客户端的文档。

​

实现日志记录

​

服务端日志记录

import logging

from mcp.server import MCPServer

logger = logging.getLogger(__name__)

mcp = MCPServer("reports")


@mcp.tool()
async def fetch_report(report_id: str) -> str:
    """按 id 获取报告。"""
    logger.info("正在获取报告 %s", report_id)
    return f"报告 {report_id} 已准备好。"

await server.sendLoggingMessage({
  level: "info",
  data: "服务器启动成功",
});

• 启动步骤
• 资源访问
• 工具执行
• 错误情况
• 性能指标

​

常见问题

​

工作目录

• 通过客户端配置启动的服务器的工作目录可能是 未定义的（在 macOS 上可能是 /），因为客户端可能从 任意位置启动
• 在配置和 .env 文件中始终使用绝对路径，以确保 稳定运行
• 如果通过命令行直接测试服务器，工作目录将是 你运行命令时所在的目录

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/data"
      ]
    }
  }
}

​

环境变量

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

​

服务器启动

1. 路径问题
   • 服务器可执行文件路径不正确
   • 缺少所需文件
   • 权限问题
   • 尝试为 command 使用绝对路径
2. 配置错误
   • 无效的 JSON 语法
   • 缺少必需字段
   • 类型不匹配
3. 环境问题
   • 缺少环境变量
   • 变量值不正确
   • 权限限制

​

连接问题

1. 检查客户端日志
2. 验证服务器进程是否正在运行
3. 使用 Inspector 独立测试
4. 验证 协议兼容性：调用 server/discover 来查看 服务器支持哪些协议版本。 UnsupportedProtocolVersionError（-32022）会在其 data 字段中列出服务器支持的 版本
5. 检查 每个请求的 _meta 字段： 每个请求都必须携带 io.modelcontextprotocol/protocolVersion 和 io.modelcontextprotocol/clientCapabilities，客户端还应当包含 io.modelcontextprotocol/clientInfo。缺少任一 必需字段的请求都会以错误 -32602（Invalid params）被拒绝，这与许多其他格式错误输入返回的 错误码相同。如果服务器需要请求的 clientCapabilities 未声明的某项能力，例如 elicitation，它会返回一个 MissingRequiredClientCapabilityError（-32021），并指出缺失的 能力。检查请求的 _meta 和 server/discover 响应，以 验证双方都声明了你所期望的内容

​

在 Claude Desktop 中进行调试

​

检查服务器状态

​

查看日志

• 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

1. 创建一个 developer_settings.json 文件，并将 allowDevTools 设置为 true：

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

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

2. 打开 DevTools：Command-Option-I（macOS）或 Ctrl+Alt+I（Windows）

• 主内容窗口
• 应用标题栏窗口

• 消息负载
• 连接时序

​

调试工作流

​

开发周期

1. 初始开发
   • 使用 Inspector 进行基本测试
   • 实现核心功能
   • 添加日志点
2. 集成测试
   • 在目标 MCP 客户端中进行测试
   • 监控日志
   • 检查错误处理

​

测试更改

• 配置更改：重启 MCP 客户端
• 服务器代码更改：重启客户端（对于 Claude Desktop，需要完全退出 并重新打开；仅关闭窗口是不够的）
• 快速迭代：在开发期间使用 Inspector

​

最佳实践

​

日志策略

1. 结构化日志
   • 使用一致的格式
   • 包含上下文
   • 添加时间戳
   • 跟踪请求 ID
2. 错误处理
   • 记录堆栈跟踪
   • 包含错误上下文
   • 跟踪错误模式
   • 监控恢复情况
3. 性能跟踪
   • 记录操作耗时
   • 监控资源使用情况
   • 跟踪消息大小
   • 测量延迟

​

安全注意事项

1. 敏感数据
   • 清理日志
   • 保护凭证
   • 屏蔽个人信息
2. 访问控制
   • 验证权限
   • 检查身份验证
   • 监控访问模式

​

获取帮助

1. 第一步
   • 检查服务器日志
   • 使用 Inspector 进行测试
   • 检查配置
   • 验证环境
2. 支持渠道
   • GitHub issues
   • GitHub discussions
3. 提供信息
   • 日志摘录
   • 配置文件
   • 复现步骤
   • 环境详情

​

后续步骤