MCP 概述

HTTP 服务器是连接到远程 MCP 服务器的推荐选项。这是云服务最广泛支持的传输方式

# 基本语法
claude mcp add --transport http <name> <url>

# 真实示例：连接到 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带有 Bearer 令牌的示例
claude mcp add --transport http secure-api https://api.example.com/mcp \
       --header "Authorization: Bearer your-token"

在通过 .mcp.json、~/.claude.json 或 claude mcp add-json 中的 JSON 配置 MCP 服务器时，type 字段接受 streamable-http 作为 http 的别名

MCP 规范对此传输使用名称 streamable-http，因此从服务器文档复制的配置无需修改即可工作

没有 type 但有 url 的 JSON 条目是配置错误，因为 Claude Code 将没有 type 的条目读取为 stdio 服务器

Claude Code 会跳过该服务器并报告 MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry

在 v2.1.202 之前，Claude Code 将此配置错误报告为 command: expected string, received undefined

SSE (Server-Sent Events) 传输已弃用

请在可用的地方使用 HTTP 服务器

# 基本语法
claude mcp add --transport sse <name> <url>

# 真实示例：连接到 Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 带有身份验证标头的示例
claude mcp add --transport sse private-api https://api.company.com/sse \
       --header "X-API-Key: your-key-here"

Stdio 服务器作为机器上的本地进程运行

它们非常适合需要直接系统访问或自定义脚本的工具

Claude Code 在生成的服务器的环境中设置 CLAUDE_PROJECT_DIR ，指向 项目根目录 ，因此服务器可以解析项目相对路径，而无需依赖工作目录

这与 hooks 在其 CLAUDE_PROJECT_DIR 变量中接收的目录相同。从服务器进程内部读取它

例如 Node 中的 process.env.CLAUDE_PROJECT_DIR 或 Python 中的 os.environ["CLAUDE_PROJECT_DIR"]

CLAUDE_PROJECT_DIR 是稳定的项目根目录，在会话中途添加或删除工作目录时不会改变。限制自己的文件系统访问到一组允许目录的服务器应该改为实现 MCP roots/list 请求。Claude Code 使用会话的启动目录加上您通过 –add-dir、/add-dir 或 additionalDirectories 设置授予的每个额外工作目录来回答 roots/list。当该集合改变时，Claude Code 发送 notifications/roots/list_changed

在 v2.1.203 之前，roots/list 仅返回启动目录，Claude Code 不发送 notifications/roots/list_changed

此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此在项目或用户范围的 .mcp.json command 或 args 中通过 ${VAR} 扩展引用它需要一个默认值

例如 ${CLAUDE_PROJECT_DIR:-.}

插件提供的 MCP 配置直接替换 ${CLAUDE_PROJECT_DIR}，不需要默认值

# 基本语法
claude mcp add [options] <name> -- <command> [args...]

# 真实示例：添加 Airtable 服务器
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
       -- npx -y airtable-mcp-server

注意：使用 – 分隔服务器参数。对于 stdio 服务器，–（双破折号）将 Claude 自己的选项（如 –transport、–env 和 –scope）与运行服务器的命令和参数分开。– 之后的所有内容都会原封不动地传递给服务器

例如：claude mcp add --transport stdio myserver -- npx server → 运行 npx server

claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080
→ 运行 python server.py --port 8080，环境中有 KEY=value

没有 --，Claude Code 会尝试将服务器的标志（如上面的 --port）解析为自己的选项

--env 接受多个 KEY=value 对。如果服务器名称直接跟在 --env 之后，CLI 会将该名称读取为另一对并拒绝它

因此请在 --env 和服务器名称之间放置至少一个其他选项，如上面的示例所示

WebSocket 服务器保持持久的双向连接，适合于向 Claude 主动推送事件的远程 MCP 服务器

当您的服务器仅响应请求时，请改用 HTTP

因为 HTTP 支持 OAuth 和 claude mcp add --transport 标志，而 WebSocket 两者都不支持

在 .mcp.json 中或使用 claude mcp add-json 配置 WebSocket 服务器：

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 字段

• 身份验证仅限于Header，因此在 headers 中传递静态令牌或在连接时使用 headersHelper 生成一个

  claude mcp add --transport 标志不接受 ws
  

配置后，可以使用这些命令管理您的 MCP 服务器：

# 列出所有配置的服务器
claude mcp list

# 获取特定服务器的详细信息
claude mcp get github

# 删除服务器
claude mcp remove github

# （在 Claude Code 中）检查服务器状态
/mcp

来自 .mcp.json 的项目范围服务器如果等待批准，会在 claude mcp list 中显示为 ⏸ 待批准。运行 claude 交互式命令来审查和批准它们。claude mcp get <name> 将待批准的服务器显示为 ⏸ 待批准，将被拒绝的服务器显示为 ✗ 已拒绝

从 v2.1.196 开始，claude mcp list 和 claude mcp get 仅从未检入存储库的设置文件中读取 .mcp.json 批准

直到通过在其中运行 claude 并接受工作区信任对话框来信任工作区

克隆的存储库无法批准其自己的服务器：
提交到项目的 .claude/settings.json 的 enableAllProjectMcpServers 或 enabledMcpjsonServers 在不受信任的文件夹中被忽略

服务器保持在 ⏸ 待批准 状态，而不是被连接和健康检查

这些来源的批准仍然适用于不受信任的文件夹：

• 用户 ~/.claude/settings.json
• 托管设置
• 使用 –settings 传递的设置

未跟踪的 .claude/settings.local.json 中的批准也适用，但仅在接受该文件夹或其父目录之一的信任对话框后：Claude Code 运行 git 来检查文件是否被跟踪，并且仅在受信任的文件夹中运行该检查。在从未信任过的文件夹中，文件的批准会等待信任对话框，除非该文件夹是自己的配置主目录：您的主目录，或一个您已将其 .claude 设置为 CLAUDE_CONFIG_DIR 的目录

在 v2.1.207 之前，未跟踪的 .claude/settings.local.json 在从未信任过的文件夹中批准了服务器

任何设置文件中的 disabledMcpjsonServers 条目仍然会拒绝该服务器

/mcp 面板在每个连接的服务器旁边显示工具计数，并标记声称工具功能但未公开任何工具的服务器

配置为空 url 的远程服务器在 /mcp、claude mcp list 和/plugin管理器中显示为 未配置，Claude Code 不会尝试连接到它。插件可以包含一个占位符条目，如下所示，用于稍后配置的连接器，因此 Claude Code 不会将其报告为错误或设置问题。服务器在 /mcp 中的详细视图读取 未为此服务器配置 URL；设置条目的 url 以连接它

在 v2.1.208 之前，Claude Code 将空 url 报告为配置问题，并提示重新连接

如果请求需要来自仍在后台连接的服务器的工具，Claude 会在继续之前等待该服务器。启用工具搜索（这是默认设置）后，等待发生在 ToolSearch 调用内部

在没有工具搜索的配置中，例如 Google Cloud 的 Agent Platform、自定义 ANTHROPIC_BASE_URL 或 ENABLE_TOOL_SEARCH=false

Claude 改为使用 WaitForMcpServers 工具

某些服务器名称为 Claude Code 的内置服务器保留：workspace、claude-in-chrome、computer-use、Claude Preview 和 Claude Browser。如果您的配置定义了具有保留名称的服务器，Claude Code 会在加载时跳过它，并显示一条警告，要求您重命名它。claude mcp add 会以错误拒绝保留名称

Claude Preview 和 Claude Browser 都命名了 Claude Code 桌面应用的预览窗格使用的内置服务器

在 v2.1.205 之前，Claude Browser 不是保留的，因此用户配置的服务器可以在该名称下注册

Claude Code 支持 MCP list_changed 通知，允许 MCP 服务器动态更新其可用工具、提示和资源，而无需您断开连接并重新连接。当 MCP 服务器发送 list_changed 通知时，Claude Code 会自动刷新来自该服务器的可用功能

如果 HTTP 或 SSE 服务器在会话中途断开连接，Claude Code 会自动以指数退避方式重新连接：最多五次尝试，从一秒延迟开始，每次加倍。服务器在 /mcp 中显示为待处理状态，同时重新连接正在进行中。五次失败尝试后，服务器被标记为失败，可以从 /mcp 手动重试

Stdio 服务器是本地进程，不会自动重新连接

相同的退避策略也适用于 HTTP 或 SSE 服务器在启动时初始连接失败的情况

从 v2.1.121 开始，Claude Code 在瞬时错误（如 5xx 响应、连接被拒绝或超时）上最多重试初始连接三次

如果仍然无法连接，则将服务器标记为失败

身份验证和未找到错误不会重试，因为它们需要配置更改才能解决

当配置的服务器无法连接时，Claude Code 告诉 Claude 哪个服务器失败及其连接错误，包括在 ToolSearch 结果中找不到匹配工具，因此 Claude 在其响应中报告连接失败。需要工具搜索默认启用

在没有工具搜索的配置中，例如自定义 ANTHROPIC_BASE_URL、ENABLE_TOOL_SEARCH=false
或不支持工具搜索的模型，以及在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上

Claude Code 不会向 Claude 报告失败的服务器连接

在 v2.1.205 之前，Claude Code 不会将连接错误传递给 Claude，Claude 可能会响应，就像失败的服务器的工具从未配置过一样

从 v2.1.191 开始，在成功连接后运行的功能发现请求（如 tools/list、prompts/list 和 resources/list）也会在短退避的情况下最多重试三次瞬时网络和服务器错误。身份验证错误、4xx 响应和请求超时不会重试

MCP 服务器也可以直接将消息推送到会话中，以便 Claude 可以对外部事件（如 CI 结果、监控警报或聊天消息）做出反应。要启用此功能，服务器声明 claude/channel 功能，并在启动时使用 –channels 标志选择加入

请参阅 Channels 以使用官方支持的频道，或 Channels reference 以构建自己的频道

• 使用 -s 或 –scope 标志指定配置的存储位置：
  • local（默认）：仅在当前项目中对您可用。较旧版本称此范围为 project
  • project：通过 .mcp.json 文件与项目中的每个人共享
  • user：在所有项目中对您可用。较旧版本称此范围为 global
• 使用 -e 或 –env 标志设置环境变量（例如，-e KEY=value）
• –transport 和 –header 标志也接受 -t 和 -H 短形式

• 使用 MCP_TIMEOUT 环境变量配置 MCP 服务器启动超时

  例如，MCP_TIMEOUT=10000 claude 设置 10 秒超时
  

• 通过向该服务器的 .mcp.json 条目添加 timeout 字段（以毫秒为单位）来设置每个服务器的工具执行超时

  例如 "timeout": 600000 表示十分钟。这仅对该服务器覆盖 MCP_TOOL_TIMEOUT 环境变量
  

• 当 MCP 工具输出超过 10,000 个令牌时，Claude Code 将显示警告，并默认将输出限制为 25,000 个令牌

  要增加此限制，请设置 MAX_MCP_OUTPUT_TOKENS 环境变量
  
  例如，MAX_MCP_OUTPUT_TOKENS=50000）
  
  警告阈值是固定的。请参阅 MCP 输出限制和警告
  
  https://code.claude.com/docs/zh-CN/mcp#mcp-output-limits-and-warnings
  

• 使用 /mcp 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证

每个服务器的 timeout 是每个工具调用的硬时钟限制，来自服务器的进度通知不会延长它

• 低于 1000 的值被忽略，并回退到 MCP_TOOL_TIMEOUT，或在该变量未设置时回退到其约 28 小时的默认值

  在 v2.1.162 之前，低于 1000 的值被限制为一秒
  

• 对于 HTTP、SSE 或 claude.ai connector 服务器，还有第二个每请求计时器，涵盖从每个请求到服务器第一个响应字节的时间
  • 该计时器为 60 秒，除非您设置每个服务器的 timeout 或 MCP_TOOL_TIMEOUT
  • 将任一设置为 60 秒或更高会将每请求计时器提高到该值，较低的值不会缩短它
  • 未设置的 MCP_TOOL_TIMEOUT 的 28 小时默认值永远不会影响它
• Stdio 和 WebSocket 服务器没有每请求计时器

每个服务器至少 1000 的 timeout 也充当下面描述的空闲超时的下限：Claude Code 永远不会因为空闲而在每个服务器的 timeout 之前中止该服务器的工具调用

需要 Claude Code v2.1.203 或更高版本

对 MCP 服务器的工具调用如果在空闲窗口内没有发送响应和进度通知，将以错误中止，而不是等待时钟限制

空闲超时需要 Claude Code v2.1.187 或更高版本

• 它适用于除 IDE 服务器和 SDK 进程内服务器之外的每种服务器类型

• 空闲窗口对于 HTTP、SSE、WebSocket 和 claude.ai connector 服务器默认为五分钟，对于 stdio 服务器默认为 30 分钟

  在 v2.1.203 之前，stdio 服务器不受空闲超时的限制
  

在毫秒中设置 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 环境变量以更改空闲窗口，或将其设置为 0 以禁用检查

Plugins 可以捆绑 MCP 服务器，在启用插件时自动提供工具和集成。插件 MCP 服务器的工作方式与用户配置的服务器相同。

本地范围是默认范围。本地范围的服务器仅在您添加它的项目中加载，并保持私密。Claude Code 将其存储在 ~/.claude.json 中该项目的路径下，因此相同的服务器不会出现在其他项目中

对个人开发服务器、实验配置或包含您不想在版本控制中的凭据的服务器使用本地范围

MCP 服务器的”本地范围”术语与一般本地设置不同。MCP 本地范围的服务器存储在 ~/.claude.json（主目录）中，而一般本地设置使用 .claude/settings.local.json（在项目目录中）

有关设置文件位置的详细信息，请参阅设置

https://code.claude.com/docs/zh-CN/settings#settings-files

# 添加本地范围的服务器（默认）
claude mcp add --transport http stripe https://mcp.stripe.com

# 显式指定本地范围
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

该命令将服务器写入 ~/.claude.json 中当前项目的条目。下面的示例显示从 /path/to/your/project 运行时的结果：

{
    "projects": {
        "/path/to/your/project": {
            "mcpServers": {
                "stripe": {
                    "type": "http",
                    "url": "https://mcp.stripe.com"
                }
            }
        }
    }
}

项目范围的服务器通过在项目根目录中存储配置在 .mcp.json 文件中来启用团队协作。此文件设计为检入版本控制，确保所有团队成员都可以访问相同的 MCP 工具和服务

添加项目范围的服务器时，Claude Code 会自动创建或更新此文件，使用适当的配置结构

# 添加项目范围的服务器
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

生成的 .mcp.json 文件遵循标准化格式：

{
    "mcpServers": {
        "shared-server": {
            "command": "/path/to/server",
            "args": [],
            "env": {}
        }
    }
}

出于安全原因，Claude Code 在使用来自 .mcp.json 文件的项目范围的服务器之前会提示批准

如果需要重置这些批准选择，请使用 claude mcp reset-project-choices 命令

用户范围的服务器存储在 ~/.claude.json 中，并提供跨项目可访问性，使其在机器上的所有项目中可用，同时对您的用户帐户保持私密

此范围适用于个人实用程序服务器、开发工具或您在不同项目中经常使用的服务

# 添加用户服务器
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

当具有相同名称的服务器在多个位置定义时，Claude Code 连接到它一次，使用来自最高优先级源的定义。整个服务器条目来自该源；字段不会跨范围合并。

1. 本地范围
2. 项目范围
3. 用户范围
4. 插件提供的服务器
5. claude.ai 连接器

三个范围按名称匹配重复项

插件和连接器按端点匹配，因此指向与上述服务器相同的 URL 或命令的连接器被视为重复项

Claude Code 支持 .mcp.json 文件中的环境变量扩展，允许团队共享配置，同时为特定于机器的路径和 API 密钥等敏感值保持灵活性

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

使用 Sentry 帐户进行身份验证：

/mcp 

然后调试生产问题：

过去 24 小时内最常见的错误是什么？

显示我错误 ID abc123 的堆栈跟踪

哪个部署引入了这些新错误？

GitHub 的远程 MCP 服务器使用作为标头传递的 GitHub 个人访问令牌进行身份验证。要获取一个，请打开 GitHub 令牌设置，生成一个新的细粒度令牌，具有希望 Claude 使用的存储库的访问权限，然后添加服务器：

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

然后使用 GitHub：

审查 PR #456 并建议改进

为我们刚发现的错误创建新问题

显示分配给我的所有开放 PR

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

然后自然地查询您的数据库：

本月我们的总收入是多少？

显示订单表的架构

查找 90 天内未进行购买的客户