安装与范围的细节

版本要求与措辞以官方为准。

四种传输方式

HTTP（推荐）：连接远程 MCP 服务器最推荐、云服务里支持最广的传输。

claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token"

用 JSON 配置（.mcp.json、~/.claude.json、claude mcp add-json）时，type 字段接受 streamable-http 作为 http 的别名（MCP 规范里这个传输叫 streamable-http）。只有 url 没有 type 的 JSON 条目是配置错误：Claude Code 把没有 type 的条目当作 stdio 服务器，会跳过它并报告需要加 "type": "http"；"type": "sdk" 的进程内服务器只能由 SDK 宿主应用（如 Agent SDK 应用或桌面应用）注册，写在 .mcp.json 里会被跳过。--output-format stream-json 运行时，被跳过的 --mcp-config 条目会出现在 system/init 事件的 mcp_server_errors 字段里，脚本可据此检测。

SSE（已弃用）：有些服务仍只提供 SSE 端点。同样用 claude mcp add --transport http <名称> <URL>，Claude Code 先试 HTTP 传输，必要时切到 SSE；较早版本或想直接走 SSE 时传 --transport sse（如 claude mcp add --transport sse asana https://mcp.asana.com/sse，可加 --header "X-API-Key: ..."）。

stdio（本地进程）：适合需要直接访问系统或自定义脚本的工具。Claude Code 在被派生的服务器环境里设置 CLAUDE_PROJECT_DIR（项目根），所以服务器不必依赖工作目录就能解析项目相对路径；它在项目中途增删工作目录时保持稳定，限制自己文件系统访问范围的服务器应实现 MCP 的 roots/list。该变量设在服务器的环境里，而不是 Claude Code 自己的环境里，所以在 .mcp.json 的 command 或 args 里用 ${VAR} 展开去引用它是行不通的（它只对服务器进程本身可见）。

claude mcp add [选项] <名称> -- <命令> [参数...]
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

-- 把 Claude 自己的选项（--transport、--env、--scope）与启动服务器的命令及参数分开，-- 之后的一切原样交给服务器；没有 --，Claude Code 会把服务器的标志（如 --port）当作自己的选项去解析。--env 可接多个 KEY=value，但如果服务器名紧跟在 --env 后面会被当成另一个键值对而被拒绝，所以在 --env 与服务器名之间至少放一个别的选项（如 --transport stdio）。

WebSocket（远程）：持久的双向连接，适合会主动向 Claude 推送事件的远程服务器；服务器只响应请求时用 HTTP（它支持 OAuth 和 claude mcp add 的更多功能）。在 .mcp.json 里或用 claude mcp add-json 配置：

claude mcp add-json events-server '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

type: "ws" 接受与 http 相同的 url、headers、headersHelper、timeout、alwaysLoad 字段；认证只能用请求头（静态令牌，或用 headersHelper 在连接时生成）。

通用提示：-s/--scope 选存储位置（local 默认，仅你在当前项目；project 通过 .mcp.json 与项目成员共享；user 你在所有项目）；-e/--env 设环境变量；--transport、--header 有 -t、-H 简写；启动超时用 MCP_TIMEOUT（如 MCP_TIMEOUT=10000 claude 为 10 秒）；给某个服务器单独设工具执行超时就在它的 .mcp.json 条目里加毫秒数的 timeout（如 600000，覆盖该服务器的 MCP_TOOL_TIMEOUT，是每次工具调用的硬性墙钟上限，进度通知不会延长它，小于 1000 的值被忽略，≥1000 的值还充当空闲超时的下限，需要 v2.1.203+）；工具输出超过 10000 token 会警告，默认上限 25000，用 MAX_MCP_OUTPUT_TOKENS 调整；用 /mcp 对需要 OAuth 2.0 的远程服务器认证。

把别的客户端的说明改写成 Claude Code 命令

MCP 服务器不专属于 Claude Code，说明可能是为 Claude Desktop、Cursor 等写的，没有 claude mcp add 命令。找说明里的三种东西：一个 URL（如 https://mcp.example.com/mcp，说明服务器是远程的）、一个启动命令（如 npx -y @example/mcp-server，在你机器上运行）、一个 mcpServers JSON 块（为别的客户端设置文件写的配置）。每个命令默认写入 local 作用域。

• 来自 URL：https:// 端点用 --transport http 添加（说明里说端点用 SSE 就按 SSE 的写法）；wss:// 端点用 WebSocket 的写法。说明还给了 API Key 或令牌头，就用 --header 传入。
• 来自 npx、uvx 或二进制命令：把整条命令放在 -- 之后，让 -y 这类标志传给启动服务器的命令；环境变量用 --env 传：claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server。
• 来自 mcpServers JSON 块：别的客户端写的 mcpServers 块用的外层键和条目形状 Claude Code 能读，但要把 mcpServers 里面的对象（不是外层包装）传给 claude mcp add-json。有两种条目要先修：有 url 没有 type——加上与端点匹配的 "type": "http"、"sse" 或 "ws"；键里含字母、数字、连字符、下划线之外的字符——选一个只含这些字符的服务器名。例如 claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'；想与团队共享就加 --scope project。

每个 claude mcp add、add-json 成功时打印一行 Added ...；用 claude mcp get <名称> 检查 Claude Code 是否真的连上了。管理命令：claude mcp list、claude mcp get <名称>、claude mcp remove <名称>（移除远程服务器时同时删除为它存储的 OAuth 令牌和客户端注册）、会话里的 /mcp。还可以用 JSON 添加：claude mcp add-json <名称> '<json>'（注意 shell 转义、JSON 要符合 MCP 服务器配置 schema、可加 --scope user），以及从 Claude Desktop 导入：claude mcp add-from-claude-desktop（仅 macOS 和 WSL，读取 Desktop 配置文件的标准位置，弹出对话框选要导入的服务器；名称含字母数字连字符下划线之外字符的服务器无法导入并被逐个报告；重名的会加数字后缀如 server_1；用 --scope user 加到用户配置）。

安装范围

Local 是默认：只在你添加它的项目里加载，对你私有；Claude Code 把它存在 ~/.claude.json 里该项目路径之下（projects → 项目路径 → mcpServers）。注意 MCP 的「local 范围」不同于一般的 local 设置：前者存在主目录的 ~/.claude.json，后者存在项目里的 .claude/settings.local.json。Project 把配置存在项目根的 .mcp.json 里支持团队协作，添加时 Claude Code 自动创建或更新该文件，用标准格式（{"mcpServers": {"shared-server": {"type": "http", "url": "https://example.com/mcp"}}}）；出于安全，交互会话里使用 .mcp.json 的项目范围服务器前会请你批准，用 claude mcp reset-project-choices 重置批准选择。claude -p、Agent SDK 会话和云会话无法显示该提示，会不经询问就加载项目范围的服务器；想阻止就把它加入 disabledMcpjsonServers（在任何权限模式下都阻止）、用 --setting-sources 或 SDK 的 settingSources 完全排除项目设置，或用 --strict-mcp-config 启动（Claude Code 只用你经 --mcp-config 传入的 MCP 服务器）。User 存在 ~/.claude.json，跨项目可用且仅限你的账号，适合个人常用工具和跨项目服务。

优先级：同一服务器在多处定义时，Claude Code 只连一次，使用最高优先级来源的定义，整个条目取自该来源（字段不跨范围合并）。顺序：1 Local；2 Project；3 User；4 插件提供的服务器；5 claude.ai 连接器。三个范围之间按名称匹配重复；插件和连接器按端点匹配（指向与上面某个已启用服务器相同的 URL 或命令就算重复）。两个 URL 写法只差协议或主机大小写、协议默认端口（如 https 的 :443）、末尾斜杠时视为同一端点；路径、查询串、用户信息或非默认端口不同则不是。你组织通过 managedMcpServers 托管设置提供的服务器排在这些之上，有重复时连组织的那个。

.mcp.json 里的环境变量展开

支持 ${VAR}（展开为环境变量值）和 ${VAR:-default}（VAR 已设置则用它，否则用默认值），可用于 command、args、env、url（HTTP 类型）、headers：

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

引用的变量没设置又没有默认值时，配置仍会加载：Claude Code 在 claude mcp list 里为该服务器报告缺失变量警告，并把未展开的 ${VAR} 文本原样使用。凭证变量在远程服务器的 url 和 headers 里读作空：为了防止项目的 .mcp.json 或插件把你的 Claude Code 或云服务商凭证发给任意主机，Claude Code 不展开这些变量，包括 Claude Code 自己的凭证（ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN）、云服务商凭证（AWS_BEARER_TOKEN_BEDROCK）和环境里携带的其他凭证（HTTPS_PROXY、NPM_TOKEN 等）；被覆盖的名字无论你是否设置都读作空，:-default 回退也被忽略；服务商基础 URL（如 ANTHROPIC_BASE_URL）仍会展开；集合之外的名字（如 API_KEY）按字面展开；想把被覆盖的凭证给服务器，就把它复制到你自己命名的变量再引用。在 claude --debug-file /tmp/claude-debug.log 的日志里搜 never expanded toward 可看到这类提示。本地、项目、用户范围的服务器在 /mcp 详情页、claude mcp list/get 输出里按名称显示 ${VAR} 引用而不是解析后的值（/mcp 详情页需要 v2.1.268+）。

实用示例

GitHub 代码评审：GitHub 的远程 MCP 服务器用作为请求头传入的个人访问令牌（fine-grained token）认证：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"

claude mcp add 只保存配置、不验证凭证，所以占位值也被接受但之后连接会失败，用 /mcp 验证连接。然后可以说「Review PR #456 and suggest improvements」「Create a new issue for the bug we just found」「Show me all open PRs assigned to me」。查询 PostgreSQL：DBHub（@bytebase/dbhub）是通过 --dsn 传入的连接串把 Claude 接到关系型数据库的 MCP 服务器，连接串里用只读数据库用户：

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

用 /mcp 确认 db 显示 connected，然后自然地提问：「What's our total revenue this month?」「Show me the schema for the orders table」。