命令字典
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
管理MCP服务器连接和OAuth认证
/mcp 是 Claude Code 会话内 slash 命令,打开一个交互式面板,用于查看当前 session 中所有 MCP(Model Context Protocol)服务器的实时连接状态、可用工具列表,以及处理需要 OAuth 认证的服务器授权流程。
官方文档将其定位为项目初始设置阶段的核心入口之一:
"Use
/mcpand/agentsto set up any servers or subagents the project needs." — code.claude.com/docs/en/commands
关键区分:/mcp(会话内 slash 命令)与 claude mcp(终端 CLI 子命令)是两套不同的接口:
/mcp | claude mcp | |
|---|---|---|
| 执行位置 | Claude Code 会话输入框 | 操作系统终端 |
| 管理层面 | 运行时(当前 session 的连接状态) | 持久化配置(磁盘上的服务器定义) |
| 典型动作 | 查看状态、触发 OAuth、重新连接 | add / list / get / remove 服务器 |
在 Claude Code 会话输入框中直接输入并回车:
/mcp
无需附加参数。面板展示:
claude mcp CLI 子命令这些命令在终端(不是会话内)执行,修改磁盘上的持久化配置:
# 添加本地进程服务器(stdio transport)
claude mcp add --transport stdio my-server npx -y @myorg/my-mcp-server
# 添加远程 HTTP 服务器(推荐)
claude mcp add --transport http notion https://mcp.notion.com/mcp
# 添加时指定 Header(Bearer Token)
claude mcp add --transport http my-api \
--header "Authorization: Bearer ${MY_TOKEN}" \
https://api.example.com/mcp
# 按作用域指定存储位置
claude mcp add --scope project --transport http shared-server https://...
# 列出所有已配置服务器
claude mcp list
# 查看单个服务器详情
claude mcp get <server-name>
# 删除服务器
claude mcp remove <server-name>
# 从 Claude Desktop 导入现有配置
claude mcp add-from-claude-desktop
# 用 JSON 字面量添加服务器
claude mcp add-json <name> '<json>'
claude mcp add 的 --scope 参数控制配置写入位置:
| 作用域 | 存储路径 | 适用场景 |
|---|---|---|
local(默认) | ~/.claude.json | 本项目私有,不提交版本控制 |
project | .mcp.json(项目根目录) | 团队共享,提交到仓库 |
user | ~/.claude.json | 跨项目全局个人配置 |
三种 transport 类型对比:
| Transport | 适用场景 | 备注 |
|---|---|---|
stdio | 本地进程、npm 包 | 本地工具推荐选择 |
http | 远程服务器 | 远程工具推荐选择,支持 OAuth |
sse | 旧版 Server-Sent Events | 已废弃,建议迁移至 http |
.mcp.json(project scope,可提交 git)放在项目根目录、--scope project 写出的就是这个文件。下面这份示范了三种 transport,并用环境变量展开避免把 token 提交进仓库:
{
"mcpServers": {
"notion": {
"type": "http",
"url": "https://mcp.notion.com/mcp"
},
"internal-api": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${INTERNAL_API_TOKEN}"
}
},
"local-tools": {
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR}/tools/mcp-server.js"],
"env": {
"LOG_LEVEL": "info"
}
}
}
}
${VAR:-default} 环境变量展开:.mcp.json 里 command/args/env/url/headers 这些位置支持两种语法——
${VAR}:直接展开,未定义则报错(适合强制要求的 token)。${VAR:-default}:未定义时回退到 default(适合可选的 base URL、开关)。这正是"配置进 git、密钥不进 git"的关键:仓库里提交 Bearer ${INTERNAL_API_TOKEN},每个开发者把真实 token 放在各自的 shell/.env 里,.mcp.json 本身永远不含明文 token。
/permissions 联动:把 MCP 工具加进 allowlistMCP 工具的权限标识符格式是 mcp__<server>__<tool>(与 hooks 的 matcher 同一套命名)。当 Claude 第一次要调用某个 MCP 工具(如 Notion 的搜索)时会停下来征求授权;想免去反复确认,可把它写进 allowlist:
/permissions,在 Allow 规则里加一条 mcp__notion__search(精确允许 Notion server 的 search 这一个工具);settings.json 的 permissions.allow 数组里加 "mcp__notion__search",提交到 .claude/settings.json 让团队共享;mcp__notion(不带 __<tool> 后缀即覆盖整个 server)。这样配置后,mcp__notion__search 不再触发停下来的授权提示。注意这与 hooks 里 mcp__brave-search__.* 那种正则 matcher 不是一回事:/permissions 规则是前缀/精确语义,hooks matcher 才走正则。
对于需要 OAuth 的远程 MCP 服务器(如 GitHub、Make),在会话内通过 /mcp 完成认证,无需退出当前工作:
claude mcp add --transport http <name> <url> 配置/mcp,面板中该服务器显示"需要认证"启动时认证提示(v2.1.193):自 v2.1.193 起,若有 MCP 服务器需要认证,Claude Code 会在会话启动时直接显示一条提示,指向
/mcp让你立即完成 OAuth,而不必等到第一次工具调用失败才发现服务器没连上。来源:Claude Code changelog v2.1.193 —— "Added a startup notice when MCP servers need authentication, pointing at/mcp"。
/mcp | /agents | /permissions | |
|---|---|---|---|
| 管理对象 | MCP 服务器(外部工具) | Subagent 实例(并行执行单元) | 工具调用权限(允许/拒绝记录) |
| 运行时/持久 | 运行时 | 运行时 | 运行时 |
| 典型使用时机 | 会话初始、OAuth 续期 | 启动并行任务 | 审查或修改已授权的工具访问 |
官方文档推荐在项目第一个 session 中同时运行 /mcp 和 /agents,再用 /permissions 设置工具调用审批规则。
/mcp 确认所需服务器全部连接正常,再开始下发任务,避免执行到一半才发现工具不可用。/mcp 完成重新授权,不必重启。.mcp.json 用 --scope project 提交到仓库,团队成员 clone 后用 /mcp 验证连接。/mcp 改不了持久化配置:/mcp 只管当前 session 的运行时状态。要添加、删除服务器定义,必须在终端运行 claude mcp add / claude mcp remove。
stdio 服务器空闲断线:stdio transport 服务器在空闲后会断开连接,且在 Claude Desktop 的 Claude Code 面板中无法用 /mcp 重新连接(需重启整个应用)。CLI 版可通过 /mcp 面板触发重连(GitHub issue #54136)。
SSE transport 已废弃:--transport sse 已不推荐使用,应替换为 --transport http,否则可能遭遇兼容性问题。
修复服务器列表对屏幕阅读器和放大镜的焦点跟踪
修复关闭 /mcp 面板对话框后在记录中遗留 '(no content)' 行的问题
现在将未登录的 claude.ai 连接器折叠在「Show unused connectors」行后
修复当 MCP server 拥有长名称或多行描述时的 tool list 和 tool detail rendering bug
Reconnect 现在无需重启即可获取 .mcp.json 编辑
修复服务器列表在超过终端高度时无法滚动
现在显示已连接服务器的工具数,并标记连接但工具数为 0 的服务器
现在显示被手动添加的相同 URL 服务器隐藏的 claude.ai connectors,并澄清授权消息
修复使用 headersHelper 配置的服务器隐藏 OAuth 操作,以及自定义请求头 HTTP/SSE MCP 服务器卡在需要认证的问题
修复 `/mcp` 菜单为使用 `headersHelper` 配置的 MCP servers 提供 OAuth 特定操作的问题
修复了打开该dialog时的input deadlock问题
添加了原生 MCP 服务器管理对话,可在聊天面板中启用/禁用服务器和管理 OAuth 认证。
修复 `/mcp reconnect` 命令在给定不存在的服务器名称时冻结 CLI 的问题
添加 enable 子命令替代之前的 @-mention 方式来启用/禁用 MCP servers
新增 enable 和 disable 子命令用于快速切换 MCP 服务器
支持通过 @ 提及来启用/禁用 MCP 服务器
/mcp 命令现在显示 MCP 工具的注释和标题
改进了 /mcp 命令的输出
新增详细的 MCP server tools 显示