mcp-management

MCP 服务管理

重要：添加、移除或更新 MCP 服务后，请告知用户重启受影响的 Agent，以使更改生效。

关键：移除任何服务之前，必须使用 AskUserQuestion 征求用户确认。

快速参考（Claude Code）

# Install
claude mcp add --transport http <name> <url>
claude mcp add --transport stdio <name> -- <command> [args...]
claude mcp add-json <name> '<json>'              # Full JSON config in one shot

# List/inspect
claude mcp list
claude mcp get <name>

# Remove (confirm with user first!)
claude mcp remove <name>

# OAuth login/logout (for OAuth-protected HTTP servers)
claude mcp login <name>
claude mcp logout <name>

选项必须放在服务名称之前。截至 2026-04，推荐使用 --transport http（Streamable HTTP）；sse 即将结束生命周期。

插件 MCP 服务会在会话开始时自动连接。在会话期间启用或禁用插件后，使用 /reload-plugins 重新初始化。

多 Agent 安装（npx add-mcp）

使用 add-mcp 一次性将 MCP 服务安装到多个编码 Agent：

# Remote server (HTTP)
npx add-mcp https://mcp.example.com/mcp

# npm package (stdio)
npx add-mcp @modelcontextprotocol/server-postgres

# Local command
npx add-mcp "npx -y @org/mcp-server --flag value"

# SSE transport
npx add-mcp https://mcp.example.com/sse --transport sse

选项

标志	说明
-g, --global	全局安装，而非安装到项目级别
-a, --agent <agent>	指定目标 Agent，可重复使用
-n, --name <name>	自定义服务名称
-t, --transport <type>	HTTP（默认）或 SSE
--header <header>	自定义 HTTP 标头，可重复使用
-y, --yes	跳过确认提示
--all	安装到所有检测到的 Agent

支持的 Agent

Agent	CLI 参数	支持项目级别安装
Claude Code	claude-code	是（.mcp.json）
Claude Desktop	claude-desktop	否（仅限全局）
Cursor	cursor	是（.cursor/mcp.json）
VS Code	vscode	是（.vscode/mcp.json）
Gemini CLI	gemini-cli	是（.gemini/settings.json）
Codex	codex	是（.codex/config.toml，仅限受信任的项目）
Goose	goose	否（仅限全局）
GitHub Copilot CLI	github-copilot-cli	是（.vscode/mcp.json）
OpenCode	opencode	是（opencode.json）
Zed	zed	是（.zed/settings.json）

Codex App / 桌面应用注意事项

Codex 有两个相关界面：

• Codex CLI（codex mcp list、codex mcp get、codex mcp login）可以查看并验证 CLI 进程中的 MCP 配置。
• Codex App / 桌面应用会话只有在应用启动会话时已加载并完成身份验证的服务，才会收到其 MCP 工具。某个服务可能会出现在 codex mcp list 中，但如果当前模型轮次对应的会话是在添加、完成身份验证或重新加载该服务之前创建的，该服务仍可能不在工具列表中。

为 Codex App 配置 MCP 时：

1. 如果用户明确要求在仓库级别进行设置，优先使用项目级 .codex/config.toml。必须在 ~/.codex/config.toml 中将该项目设为受信任，使用 [projects."/absolute/path"] trust_level = "trusted"。
2. 对于使用 OAuth 的 HTTP 服务，运行：

   codex mcp login <server-name>
   

   然后确认 codex mcp list 显示 Auth: OAuth。
3. 对于使用 bearer token 的 HTTP 服务，优先使用 Codex 原生的 bearer token 环境变量形式，而不是硬编码请求头：

   codex mcp add <name> --url https://example.com/mcp --bearer-token-env-var EXAMPLE_API_KEY
   

   如果直接编写 .codex/config.toml，应使用以下格式：

   [mcp_servers.example]
   type = "http"
   url = "https://example.com/mcp"
   bearer_token_env_var = "EXAMPLE_API_KEY"
   

   某些第三方安装程序会写入 http_headers.Authorization = "Bearer ${EXAMPLE_API_KEY}"；Codex CLI 可能会将其显示为 bearer token 服务，但原生字段更清晰。
4. 添加、移除、编辑 Codex App MCP 服务或登录后，告知用户完全重启 Codex App。应用重启后，现有会话即可收到新提供的工具；仅当 tool_search 在现有会话中仍找不到服务工具时，才将创建新会话作为备用方案。
5. 验证分为两个层面：

   codex mcp list
   codex mcp get <server-name>
   

   可确认 Codex CLI、配置和身份验证状态。在 Codex App 会话中，还要使用 tool_search 搜索特定服务的工具名称（例如 supabase execute_sql 或 render list_services）。如果 tool_search 未返回任何工具，而 codex mcp list 显示正确，通常是因为 App／会话未重新加载，或该服务仅配置在 App 未加载的范围内。
6. 如果 Codex App 未读取项目级 .codex/config.toml，可暂时将该服务重复配置到用户级 ~/.codex/config.toml 中，以便诊断；然后重启 App，确认工具是否出现。如果用户只需要仓库级设置，之后请删除用户级重复配置。

示例

# Install to Claude Code and Cursor only
npx add-mcp -a claude-code -a cursor https://mcp.stripe.com

# Install npm package to all agents, globally
npx add-mcp -g --all @modelcontextprotocol/server-postgres

# Install with custom name and headers
npx add-mcp -n my-api --header "Authorization: Bearer TOKEN" https://api.example.com/mcp

# List available agents
npx add-mcp list-agents

有关特定 Agent 的配置路径、格式和转换方式，请参阅 references/multi-agent.md。

搜索 MCP 服务

当用户要求查找或安装 MCP 服务时，请参阅 references/search.md，了解：

• 官方供应商服务查找（始终优先尝试）
• MCP Registry API 查询（备用方案）
• 已知官方服务表格
• 用户选择模板格式

信任层级：官方供应商 > MCP 参考服务 > 已验证合作伙伴 > 社区

添加服务（Claude Code）

使用环境变量

--env CLI 标志对特殊字符的处理并不可靠。请改用以下方式：

1. 添加服务，但不设置环境变量：

   claude mcp add --transport stdio <name> -- npx -y @package/mcp-server
   

2. 编辑配置文件以添加环境变量。文件位置请参阅 references/scopes.md。

先收集配置

安装前，检查服务是否需要 API 密钥或令牌。运行安装命令前，使用 AskUserQuestion 收集所需值。

更新服务

没有直接的更新命令。可选方案：

1. 直接编辑配置（更改凭据时优先采用）
2. 移除后重新添加（先向用户确认是否移除）
3. 对于经常更改的凭据，使用环境变量

对于 OAuth 服务（GitHub、Sentry）：在 Claude Code 中运行 /mcp 以重新进行身份验证。

移除服务

移除前，始终通过 AskUserQuestion 向用户确认。

claude mcp remove <server-name>

对于 .mcp.json 中按项目范围配置的服务，获得用户确认后，请从文件中删除对应条目。

OpenCode 专属说明

对于 OpenCode（anomalyco/opencode v1.14.x）：

• 顶层键为 mcp（不是 mcpServers）；每个服务都必须声明 type: "local" 或 type: "remote"
• 对于本地服务，command 是单个数组 ["bin", "arg1", "arg2"]，没有单独的 args 字段
• 环境变量放在 environment 下（不是 env）
• 将每个服务的 enabled: false 设为禁用状态，无需移除
• 对 OAuth 服务（例如 GitHub），使用 opencode mcp auth <name> / opencode mcp logout <name>
• 在 v1.14.x 中，插件 tool.execute.* 钩子不会针对 MCP 工具调用触发；请改用 permission 规则

完整的 OpenCode MCP 参考，请参阅 references/opencode-mcp.md。

参考

• 搜索和已知服务：references/search.md
• 多 Agent 安装：references/multi-agent.md
• OpenCode MCP：references/opencode-mcp.md
• 传输类型：references/transports.md
• 作用域和配置文件：references/scopes.md
• 故障排除：references/troubleshooting.md

作用域摘要（Claude Code）

作用域	标志	配置位置	使用场景
本地	--scope local（默认）	~/.claude.json	个人开发服务
项目	--scope project	.mcp.json	团队共享服务
用户	--scope user	~/.claude.json	跨项目工具

环境变量语法

在配置文件中：${VAR} 或 ${VAR:-default}

Windows 说明

对 npx 使用 cmd /c 包装器：

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package