1. 查 Bug 的真实痛点五个工具来回切线索全断在切换里线上报错进来你大概率是这么干的先开 Sentry 看堆栈复制 traceId切到日志平台搜这条链路发现是某个接口返回异常再打开 Postman 或 curl 复现怀疑数据不对又连上数据库查那几条记录最后回到 IDE 里翻代码定位。五个工具五次上下文切换每切一次脑子里那条推理链就断一截。等你好不容易把线索拼起来半小时过去了Bug 还没开始改。这个场景的本质问题不是工具不好用而是工具之间没有共享上下文。Sentry 知道报错但不知道日志里那条慢查询数据库知道数据状态但不知道是哪次请求写坏的。你充当了人肉消息总线把信息从一个工具搬到另一个工具。Claude Code 的 MCPModel Context Protocol就是来解决这件事的。MCP 是 Claude Code 连接外部世界的协议层你可以把它理解成「给 Claude Code 装 USB 接口」——日志、接口、数据库、错误追踪、代码仓库每个工具做成一个 MCP ServerClaude Code 就能用自然语言一次性调度它们。你不再手动搬运信息而是说一句「查一下昨天下午支付接口的 500 报错把相关日志和数据库记录一起拉出来」它自己去调。这篇不铺开讲 MCP 的全部能力只聚焦一件事把分散的 Bug 排查工具收敛成一句话调用需要怎样的配置骨架以及怎么逐项验证每个工具真的被调起来了。适合本地已经有一堆排查脚本或工具、想统一入口的后端和全栈开发者。下面所有配置都可以直接复制改。2. 前置准备TaoToken 接入与 Claude Code 环境确认在配 MCP 之前得先保证 Claude Code 本身能正常跑起来。如果你还没接模型服务可以用 TaoToken 作为统一入口它兼容 Anthropic 的接口格式Claude Code 直接指向它就行。先拿 API Key打开 https://taotoken.net/api-keys 创建密钥复制出来。然后配置环境变量让 Claude Code 走这个端点export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥Windows 下用set或写进系统环境变量PowerShell 里是$env:ANTHROPIC_API_KEYsk-...。配完执行claude --version确认 CLI 可用再随便问一句验证模型通了claude -p 回复 ok 两个字母即可能返回内容说明模型链路没问题。这一步别跳过因为后面 MCP 调不通时你得先排除「模型本身没连上」这个变量。如果你更想先在网页里验证模型对话是否正常可以到 https://taotoken.net/models 试几句确认账号和额度都正常。环境确认后检查 MCP 相关命令是否可用claude mcp list这条命令会列出当前已配置的 MCP Server。如果是空列表也正常说明还没配。接下来我们开始搭骨架。3. 可复制的 MCP 配置骨架五个排查工具一次配齐Bug 排查通常涉及五类工具错误追踪Sentry、日志查询、接口调试、数据库、代码仓库。下面给出一个.mcp.json骨架放在项目根目录团队可以提交到 Git 共享。注意把命令和参数换成你自己工具的实际情况。{ mcpServers: { sentry: { type: http, url: https://mcp.sentry.dev/mcp, headers: { Authorization: Bearer ${SENTRY_TOKEN} } }, logs: { type: stdio, command: npx, args: [-y, your-org/log-mcp-server], env: { LOG_API_BASE: ${LOG_API_BASE}, LOG_API_KEY: ${LOG_API_KEY} } }, api-debug: { type: stdio, command: npx, args: [-y, your-org/http-probe-mcp], env: { ALLOWED_HOSTS: api.yourdomain.com,staging.yourdomain.com } }, postgres: { type: stdio, command: npx, args: [ -y, modelcontextprotocol/server-postgres, postgresql://readonly:${DB_PASSWORD}localhost:5432/appdb ] }, repo: { type: stdio, command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./src] } } }几个关键点解释一下。type只有http和stdio两种主流方式远程云服务用http本地进程或脚本用stdio。${VAR}是环境变量占位符Claude Code 启动时会从当前 shell 读取这样敏感凭据不用明文写进配置文件。数据库那条我特意用了readonly账号排查 Bug 只读就够了别给写权限。如果你更习惯用 CLI 逐条添加等价命令是这样claude mcp add --transport http sentry https://mcp.sentry.dev/mcp \ --header Authorization: Bearer $SENTRY_TOKEN claude mcp add --transport stdio logs \ --env LOG_API_BASE$LOG_API_BASE --env LOG_API_KEY$LOG_API_KEY \ -- npx -y your-org/log-mcp-server claude mcp add --transport stdio postgres \ -- npx -y modelcontextprotocol/server-postgres \ postgresql://readonly:$DB_PASSWORDlocalhost:5432/appdb注意--env、--header这些选项必须写在服务器名称之前--用来分隔 Claude 参数和实际执行的命令漏了会报错。Windows 下 stdio 命令要用cmd /c包一层claude mcp add --transport stdio logs -- cmd /c npx -y your-org/log-mcp-server配完.mcp.json后还要在settings.json里确认 MCP 被允许加载。项目级.claude/settings.json片段{ enableAllProjectMcpServers: true, permissions: { allow: [ mcp__sentry__*, mcp__logs__*, mcp__postgres__* ] } }enableAllProjectMcpServers让项目里的.mcp.json自动生效permissions.allow用通配符放行这几个 Server 的工具调用避免每次弹确认。生产环境建议把通配符收窄到具体工具名比如只允许mcp__postgres__query而不放行全部。4. 逐项验证确认每个工具真的被 Claude Code 调起来配置写完不代表能用必须逐个验证。核心命令是会话内的/mcp它会列出所有 Server 的连接状态和可用工具。claude /mcp正常输出会显示每个 Server 名称、传输方式、状态connected / failed以及暴露的工具列表。如果某个显示 failed先看下一节的排查。验证 Sentry在会话里直接问。 列出最近 24 小时错误数量最多的三个 issue如果它返回了真实的 issue 列表说明 Sentry MCP 通了。返回「没有可用工具」则说明没连上。验证日志工具 搜索包含 traceIdabc123 的日志返回最近 20 条验证接口调试工具 对 https://api.yourdomain.com/health 发一个 GET 请求返回状态码和响应体验证数据库 查询 orders 表里 statusfailed 且 created_at 在今天的记录最多 10 条验证代码仓库 读取 src/payment/handler.ts 的内容五个都单独通了之后做一次串联验证这才是 MCP 的价值所在 查一下昨天下午支付接口的 500 报错把 Sentry 的堆栈、相关日志、 涉及的数据库记录和对应代码文件一起整理出来观察它是否依次调用了多个 MCP 工具。如果它只调了一个就停下说明工具描述不够清晰或者权限没放全。实测下来串联调用能否成功很大程度取决于每个 MCP Server 的工具描述是否写清楚了「什么时候该用我」。5. 本篇常见错排查连接失败Server 显示 failed。先跑claude mcp get server-name看详细配置确认命令路径、环境变量是否解析成功。stdio 类型最常见的问题是npx找不到包手动在终端执行一遍npx -y your-org/log-mcp-server看是否报错。如果手动能跑但 Claude Code 里失败多半是环境变量没传进去。认证失败HTTP 类型返回 401。检查Authorization头的 token 是否过期。会话内执行/mcp查看认证状态需要重新授权时用/mcp clear-auth sentry清掉旧凭据再重连。注意 token 里的${SENTRY_TOKEN}必须在启动 Claude Code 的同一个 shell 里 export 过换个终端窗口就没了。工具调用了但返回空。这通常不是连接问题而是查询参数或权限范围问题。比如数据库用了 readonly 账号但查的表不在授权范围或者日志工具的LOG_API_BASE指向了错误环境。先用工具自己的 CLI 或 curl 验证一次原始查询确认数据源本身有数据。输出被截断。MCP 单次输出超过约 10000 token 会触发警告并截断。排查时经常要拉大量日志可以临时扩容export MAX_MCP_OUTPUT_TOKENS50000或者在查询里加限制条件比如「最多返回 20 条」从源头控制输出量。Windows 下路径或编码问题。stdio 命令必须用cmd /c包装路径用正斜杠或双反斜杠。中文路径容易因 GBK 编码解析失败建议把工作目录建成英文符号链接mklink /D C:\mcp-workspace C:\工作空间\项目然后配置里统一用C:/mcp-workspace。项目级 Server 不生效。执行claude mcp reset-project-choices重置项目范围的授权选择然后重新在会话里确认信任该项目。6. 把入口收敛之后下一步怎么走配置骨架搭好、五个工具逐项验证通过之后你查 Bug 的入口就从「五个窗口」变成了「一句话」。日常最实用的做法是把这个项目级的.mcp.json提交到仓库团队成员拉下来配好自己的环境变量就能用同一套排查入口不用每个人重新配一遍。如果你还在调模型接入这一层先把 API Key 和端点理顺到 https://taotoken.net/api-keys 拿密钥接入文档在 https://taotoken.net/doc 有完整的参数说明。想先验证模型对话质量再决定怎么配 MCP可以直接在 https://taotoken.net/models 试。长期用 Claude Code 做编码和 Agent 工作流的可以看 Coding Plan 的额度方案 https://taotoken.net/coding-plan 比按次调用更适合高频排查场景。最后提醒一句数据库 MCP 一定用只读账号接口调试工具的ALLOWED_HOSTS要收窄到自己的域名。排查工具能读生产数据权限给大了就是风险。骨架先跑通再按最小权限原则一项项收紧这个顺序别反。
Claude Code MCP 查 Bug 实战：一句话串联 5 个工具的配置骨架
1. 查 Bug 的真实痛点五个工具来回切线索全断在切换里线上报错进来你大概率是这么干的先开 Sentry 看堆栈复制 traceId切到日志平台搜这条链路发现是某个接口返回异常再打开 Postman 或 curl 复现怀疑数据不对又连上数据库查那几条记录最后回到 IDE 里翻代码定位。五个工具五次上下文切换每切一次脑子里那条推理链就断一截。等你好不容易把线索拼起来半小时过去了Bug 还没开始改。这个场景的本质问题不是工具不好用而是工具之间没有共享上下文。Sentry 知道报错但不知道日志里那条慢查询数据库知道数据状态但不知道是哪次请求写坏的。你充当了人肉消息总线把信息从一个工具搬到另一个工具。Claude Code 的 MCPModel Context Protocol就是来解决这件事的。MCP 是 Claude Code 连接外部世界的协议层你可以把它理解成「给 Claude Code 装 USB 接口」——日志、接口、数据库、错误追踪、代码仓库每个工具做成一个 MCP ServerClaude Code 就能用自然语言一次性调度它们。你不再手动搬运信息而是说一句「查一下昨天下午支付接口的 500 报错把相关日志和数据库记录一起拉出来」它自己去调。这篇不铺开讲 MCP 的全部能力只聚焦一件事把分散的 Bug 排查工具收敛成一句话调用需要怎样的配置骨架以及怎么逐项验证每个工具真的被调起来了。适合本地已经有一堆排查脚本或工具、想统一入口的后端和全栈开发者。下面所有配置都可以直接复制改。2. 前置准备TaoToken 接入与 Claude Code 环境确认在配 MCP 之前得先保证 Claude Code 本身能正常跑起来。如果你还没接模型服务可以用 TaoToken 作为统一入口它兼容 Anthropic 的接口格式Claude Code 直接指向它就行。先拿 API Key打开 https://taotoken.net/api-keys 创建密钥复制出来。然后配置环境变量让 Claude Code 走这个端点export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥Windows 下用set或写进系统环境变量PowerShell 里是$env:ANTHROPIC_API_KEYsk-...。配完执行claude --version确认 CLI 可用再随便问一句验证模型通了claude -p 回复 ok 两个字母即可能返回内容说明模型链路没问题。这一步别跳过因为后面 MCP 调不通时你得先排除「模型本身没连上」这个变量。如果你更想先在网页里验证模型对话是否正常可以到 https://taotoken.net/models 试几句确认账号和额度都正常。环境确认后检查 MCP 相关命令是否可用claude mcp list这条命令会列出当前已配置的 MCP Server。如果是空列表也正常说明还没配。接下来我们开始搭骨架。3. 可复制的 MCP 配置骨架五个排查工具一次配齐Bug 排查通常涉及五类工具错误追踪Sentry、日志查询、接口调试、数据库、代码仓库。下面给出一个.mcp.json骨架放在项目根目录团队可以提交到 Git 共享。注意把命令和参数换成你自己工具的实际情况。{ mcpServers: { sentry: { type: http, url: https://mcp.sentry.dev/mcp, headers: { Authorization: Bearer ${SENTRY_TOKEN} } }, logs: { type: stdio, command: npx, args: [-y, your-org/log-mcp-server], env: { LOG_API_BASE: ${LOG_API_BASE}, LOG_API_KEY: ${LOG_API_KEY} } }, api-debug: { type: stdio, command: npx, args: [-y, your-org/http-probe-mcp], env: { ALLOWED_HOSTS: api.yourdomain.com,staging.yourdomain.com } }, postgres: { type: stdio, command: npx, args: [ -y, modelcontextprotocol/server-postgres, postgresql://readonly:${DB_PASSWORD}localhost:5432/appdb ] }, repo: { type: stdio, command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./src] } } }几个关键点解释一下。type只有http和stdio两种主流方式远程云服务用http本地进程或脚本用stdio。${VAR}是环境变量占位符Claude Code 启动时会从当前 shell 读取这样敏感凭据不用明文写进配置文件。数据库那条我特意用了readonly账号排查 Bug 只读就够了别给写权限。如果你更习惯用 CLI 逐条添加等价命令是这样claude mcp add --transport http sentry https://mcp.sentry.dev/mcp \ --header Authorization: Bearer $SENTRY_TOKEN claude mcp add --transport stdio logs \ --env LOG_API_BASE$LOG_API_BASE --env LOG_API_KEY$LOG_API_KEY \ -- npx -y your-org/log-mcp-server claude mcp add --transport stdio postgres \ -- npx -y modelcontextprotocol/server-postgres \ postgresql://readonly:$DB_PASSWORDlocalhost:5432/appdb注意--env、--header这些选项必须写在服务器名称之前--用来分隔 Claude 参数和实际执行的命令漏了会报错。Windows 下 stdio 命令要用cmd /c包一层claude mcp add --transport stdio logs -- cmd /c npx -y your-org/log-mcp-server配完.mcp.json后还要在settings.json里确认 MCP 被允许加载。项目级.claude/settings.json片段{ enableAllProjectMcpServers: true, permissions: { allow: [ mcp__sentry__*, mcp__logs__*, mcp__postgres__* ] } }enableAllProjectMcpServers让项目里的.mcp.json自动生效permissions.allow用通配符放行这几个 Server 的工具调用避免每次弹确认。生产环境建议把通配符收窄到具体工具名比如只允许mcp__postgres__query而不放行全部。4. 逐项验证确认每个工具真的被 Claude Code 调起来配置写完不代表能用必须逐个验证。核心命令是会话内的/mcp它会列出所有 Server 的连接状态和可用工具。claude /mcp正常输出会显示每个 Server 名称、传输方式、状态connected / failed以及暴露的工具列表。如果某个显示 failed先看下一节的排查。验证 Sentry在会话里直接问。 列出最近 24 小时错误数量最多的三个 issue如果它返回了真实的 issue 列表说明 Sentry MCP 通了。返回「没有可用工具」则说明没连上。验证日志工具 搜索包含 traceIdabc123 的日志返回最近 20 条验证接口调试工具 对 https://api.yourdomain.com/health 发一个 GET 请求返回状态码和响应体验证数据库 查询 orders 表里 statusfailed 且 created_at 在今天的记录最多 10 条验证代码仓库 读取 src/payment/handler.ts 的内容五个都单独通了之后做一次串联验证这才是 MCP 的价值所在 查一下昨天下午支付接口的 500 报错把 Sentry 的堆栈、相关日志、 涉及的数据库记录和对应代码文件一起整理出来观察它是否依次调用了多个 MCP 工具。如果它只调了一个就停下说明工具描述不够清晰或者权限没放全。实测下来串联调用能否成功很大程度取决于每个 MCP Server 的工具描述是否写清楚了「什么时候该用我」。5. 本篇常见错排查连接失败Server 显示 failed。先跑claude mcp get server-name看详细配置确认命令路径、环境变量是否解析成功。stdio 类型最常见的问题是npx找不到包手动在终端执行一遍npx -y your-org/log-mcp-server看是否报错。如果手动能跑但 Claude Code 里失败多半是环境变量没传进去。认证失败HTTP 类型返回 401。检查Authorization头的 token 是否过期。会话内执行/mcp查看认证状态需要重新授权时用/mcp clear-auth sentry清掉旧凭据再重连。注意 token 里的${SENTRY_TOKEN}必须在启动 Claude Code 的同一个 shell 里 export 过换个终端窗口就没了。工具调用了但返回空。这通常不是连接问题而是查询参数或权限范围问题。比如数据库用了 readonly 账号但查的表不在授权范围或者日志工具的LOG_API_BASE指向了错误环境。先用工具自己的 CLI 或 curl 验证一次原始查询确认数据源本身有数据。输出被截断。MCP 单次输出超过约 10000 token 会触发警告并截断。排查时经常要拉大量日志可以临时扩容export MAX_MCP_OUTPUT_TOKENS50000或者在查询里加限制条件比如「最多返回 20 条」从源头控制输出量。Windows 下路径或编码问题。stdio 命令必须用cmd /c包装路径用正斜杠或双反斜杠。中文路径容易因 GBK 编码解析失败建议把工作目录建成英文符号链接mklink /D C:\mcp-workspace C:\工作空间\项目然后配置里统一用C:/mcp-workspace。项目级 Server 不生效。执行claude mcp reset-project-choices重置项目范围的授权选择然后重新在会话里确认信任该项目。6. 把入口收敛之后下一步怎么走配置骨架搭好、五个工具逐项验证通过之后你查 Bug 的入口就从「五个窗口」变成了「一句话」。日常最实用的做法是把这个项目级的.mcp.json提交到仓库团队成员拉下来配好自己的环境变量就能用同一套排查入口不用每个人重新配一遍。如果你还在调模型接入这一层先把 API Key 和端点理顺到 https://taotoken.net/api-keys 拿密钥接入文档在 https://taotoken.net/doc 有完整的参数说明。想先验证模型对话质量再决定怎么配 MCP可以直接在 https://taotoken.net/models 试。长期用 Claude Code 做编码和 Agent 工作流的可以看 Coding Plan 的额度方案 https://taotoken.net/coding-plan 比按次调用更适合高频排查场景。最后提醒一句数据库 MCP 一定用只读账号接口调试工具的ALLOWED_HOSTS要收窄到自己的域名。排查工具能读生产数据权限给大了就是风险。骨架先跑通再按最小权限原则一项项收紧这个顺序别反。
