MCP 的 local、project、user：`.mcp.json` 为什么不能自己批准自己

MCP 负责接到外部系统。选型见 MCP、Skills、Hooks 怎么选。这篇只讲作用域、审批和按需加载。网上仍有人把服务器写进 .claude/settings.json 的 mcpServers，那是错的；用 claude mcp add。

三个作用域

作用域	存哪	谁能用
local（默认）	`~/.claude.json` 里当前项目路径下	只有你，这个项目
project	仓库根 `.mcp.json`	团队，可提交
user	`~/.claude.json` 顶层 `mcpServers`	只有你，所有项目

同名冲突时整份配置取最高优先级，字段不合并：local > project > user。插件和 claude.ai 连接器按端点去重，不按名字。

「MCP 的 local」不是 .claude/settings.local.json。Claude Code 也不读 ~/.claude/.mcp.json 这类路径。

bash

claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http notion --scope project https://mcp.notion.com/mcp
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest
claude mcp list
claude mcp remove notion

stdio 的服务器参数写在 -- 后面，否则会被当成 Claude 自己的旗标。JSON 里有 url 必须写 "type": "http"（或 sse / ws）；没有 type 会被当成 stdio 并跳过。streamable-http 是 http 的别名。SSE 已弃用，能上 HTTP 就上 HTTP。WebSocket 用 JSON 的 "type": "ws"，--transport 不接受 ws，且不会出现在 claude mcp list 里。

.mcp.json 支持 ${VAR} 和 ${VAR:-default}，可用在 command、args、env、url、headers。变量没设又没有默认值时，配置仍加载，字面量 ${VAR} 留着，并警告。CLAUDE_PROJECT_DIR 在子进程环境里，JSON 里展开它需要默认值，例如 ${CLAUDE_PROJECT_DIR:-.}。

项目服务器要审批

交互会话里，.mcp.json 里的服务器会先停在待批准。重置选择：claude mcp reset-project-choices。

常见状态：

⏸ Pending approval：还没批准，跑交互 claude 处理
✘ Rejected：落在 disabledMcpjsonServers
⊘ Disabled for this project：在 /mcp 关掉了，可再打开

仓库里提交的 enableAllProjectMcpServers / enabledMcpjsonServers，在你还没信任该工作区之前，claude mcp list / get 不会拿它们当批准。克隆下来的仓库不能自己给自己放行。用户设置、托管设置、--settings 里的批准在未信任目录仍生效。

claude -p、Agent SDK、云端会话没有弹窗，项目服务器会直接加载。要挡住就用 disabledMcpjsonServers、--setting-sources，或 --strict-mcp-config。

两套开关别混：

disabledMcpServers / enabledMcpServers：/mcp 里按项目开关，存在 ~/.claude.json
enabledMcpjsonServers / disabledMcpjsonServers：批准或拒绝 .mcp.json 条目

Tool Search 和输出

默认开启 Tool Search：启动只带服务器名和说明，工具定义用到再进上下文。ENABLE_TOOL_SEARCH=false|true|auto|auto:N。非官方 ANTHROPIC_BASE_URL、Azure 上的 Foundry、以及部分早期云模型会退回全量加载。某个服务器要每次都在场，设 "alwaysLoad": true。

描述和服务器说明大约截到 2KB。输出超过约 1 万 token 会警告，默认上限约 2.5 万，用 MAX_MCP_OUTPUT_TOKENS 调。

钩子匹配 MCP 工具用 mcp__<server>__<tool>。mcp__memory 是精确字符串，匹配不到；用 mcp__memory__.*。插件带来的工具名更长：mcp__plugin_<plugin>_<server>__<tool>。

主会话里一次 MCP 调用跑超过约两分钟，会进后台任务，阈值见 /tasks。用 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 改阈值，0 关闭。

OAuth 可在 /mcp 完成，也可 claude mcp login <name>。无浏览器环境加 --no-browser。从 Claude Desktop 导入只在 macOS 和 WSL。

组织侧固定名单走托管 MCP（managed-mcp.json 与 allow / deny 列表），不是普通用户设置。以你当前托管文档为准。

日常够用：2 到 4 个真在用的服务器，项目共享走 .mcp.json，密钥用环境变量展开，批准留在用户侧，不要指望仓库里的开关替你点头。

MCP 的 local、project、user：.mcp.json 为什么不能自己批准自己 ​

三个作用域 ​

项目服务器要审批 ​

Tool Search 和输出 ​

MCP 的 local、project、user：`.mcp.json` 为什么不能自己批准自己

三个作用域

项目服务器要审批

Tool Search 和输出