治理与排错
2026/6/27大约 4 分钟
治理与排错
MCP 治理 vs Skill 治理
| 维度 | Skill（Skills 13 章） | MCP（本章） |
|---|---|---|
| 载入内容 | name + description listing | 各 server 的 tool name + JSON schema |
| 典型预算 | skillListingBudgetFraction ≈ 1% context | 无单一官方比例；tool 越多、schema 越大，越占 context |
| 禁用手段 | /skills、skillOverrides | 删配置、/mcp 看状态、缩小 toolset |
| 同步 | cc-switch skills sync | cc-switch mcp sync |
两套同时开时：Skill 定流程，MCP 连 API——不要让 Skill description 和 MCP tool 描述抢同一触发词。
装多少 MCP 合适
| 规模 | 建议 |
|---|---|
| 个人全栈 | 常开 3–5 个 server；文档 / 浏览器走 CLI（ctx7、Playwright），不占 MCP tool 槽 |
| 平台 API 多 | 每个平台 一个 Remote；不要 Remote + stdio 双份 |
| 总 tool 数 | /mcp 汇总过高时，关低频 server 或缩 GitHub toolsets / Gitee 子集（05 章） |
本书主栈常开建议：
- ✅ Gitee Remote（主用 Gitee）
- ✅ ctx7 CLI + Skill（不要再常开 Context7 MCP）
- ✅ Playwright CLI + Skill（不要再常开 Playwright MCP）
- ⚪ Postgres MCP（真要做 EXPLAIN / 索引建议）
- ❌ Filesystem / Sequential Thinking / archived npm server
勿双装
| 组合 | 问题 | 处理 |
|---|---|---|
| ctx7 CLI + Context7 MCP | 同一文档源 | 只留 CLI → 03 |
| Playwright CLI + Playwright MCP | 双倍浏览器 | 只留 CLI → 04 |
Gitee Remote + 本地 mcp-gitee stdio | 同名重复 | 只留 Remote → 05 |
| GitHub MCP + Gitee MCP 全开 | tool 过多 | 主平台常开，另一个按需 + 缩小 toolset |
| 内置 Read/Grep + Filesystem MCP | 完全重复 | 不装 Filesystem |
完整表见 01 · 勿双装。
诊断命令
| 目的 | 命令 / 操作 |
|---|---|
| 会话内状态 | /mcp — Connected / Disconnected、每 server tool 数量；0 tools 会标出 |
| CLI 列表 | claude mcp list |
| 单 server 详情 | claude mcp get <name> |
| Skill 侧（非 MCP） | /skills、/doctor |
| CC Switch 同步 MCP | cc-switch mcp sync |
| CC Switch 同步 Skill | cc-switch skills sync（与 MCP 无关但常一起改配置） |
Claude Code 重连 MCP 时，工具列表按 server 前缀汇总，不再整屏刷 schema（v2.1+，见 Agent 第 15 章）。
连接与零工具
| 现象 | 常见原因 | 处理 |
|---|---|---|
| Disconnected | 命令路径错、Docker 未起、Node 版本不够 | claude mcp get <name> 看 command/args；终端手跑同一命令看 stderr |
| Connected，0 tools | server 启动即 exit；OAuth 未完成；toolset 过滤成空 | 用 MCP Inspector 单独测；Remote 走 claude mcp login <name> |
| OAuth 循环失败 | 浏览器被拦、SSH 无 GUI | claude mcp login <name> --no-browser，手动打开 URL |
| stdio 立刻断 | stdout 被 console.log 污染 | 日志只写 stderr（08 章） |
| Remote 401 | PAT 过期、header 名错 | Gitee/GitHub 核对 Bearer；OAuth 类 Remote 重新 login |
Remote OAuth 标准流程：
claude mcp add-json gitee '{"type":"http","url":"https://gitee.com/api/v5/mcp"}'
claude mcp login gitee
# SSH：
claude mcp login gitee --no-browserGitHub Remote 同理（05）。
缩小 tool 面
tool 太多时优先 减 server，再 减单 server 的 tool：
| Server | 手段 |
|---|---|
| GitHub MCP | Remote 安装时加 --toolsets=repos,issues 等（上游 github-mcp-server）；read-only 模式 |
| Gitee MCP | CC Switch / 配置里只开需要的 tool 子集（05 章 · Gitee 工具列表） |
| Postgres MCP | --access-mode=restricted（06 章） |
关掉一周未用的 server：claude mcp remove <name> 或 CC Switch 里禁用后再 mcp sync。
废弃包迁移
不要继续装 archived npm；/mcp 里若还挂着旧名，删掉并重配。
| 旧 / 误用 | 替换 | 章节 |
|---|---|---|
@modelcontextprotocol/server-github | github/github-mcp-server Remote 或 Docker | 05 |
@modelcontextprotocol/server-postgres | crystaldba/postgres-mcp | 06 |
@modelcontextprotocol/server-puppeteer | Playwright CLI 或 @playwright/mcp | 04 |
servers README 里的 github/postgres npx 一行 | 仅作历史；跟产品仓库 README | 07 |
源码归档位置：modelcontextprotocol/servers-archived。
令牌与配置安全
| 规则 | 说明 |
|---|---|
| PAT 最小权限 | Gitee/GitHub token 只开 Issue/PR 所需 scope（05 章） |
| 勿提交密钥 | .mcp.json 可进 Git，真实 token 用 env 或本机 ~/.claude.json |
| Postgres | DATABASE_URI 用 restricted 模式 + 只读 DB 用户（06 章） |
| 多 server 共用一个 auth 脚本 | Claude Code headersHelper + CLAUDE_CODE_MCP_SERVER_NAME（Agent 第 15 章） |
CC Switch 与多 Agent
| 情况 | 做法 |
|---|---|
| 在 CC Switch 里改了 MCP | cc-switch mcp sync 推到 ~/.claude.json |
| 从 Claude 导入到 CC Switch | cc-switch mcp import --app claude（若 CC Switch 列表空） |
| 多工作区 / 多 Provider | MCP 配置随 sync；换 Provider 不自动删 server，习惯上 sync 后对 /mcp |
项目级 .mcp.json | 进仓库，团队共享；个人密钥仍放 env |
Skill 目录（~/.cc-switch/skills/）与 MCP 配置分开管理——只 sync skills 不会更新 MCP。