通过 MCP 将 Claude Code 连接到工具

了解如何用模型上下文协议（Model Context Protocol）把 Claude Code 连接到你的工具。

Claude Code 可以通过模型上下文协议（Model Context Protocol，MCP）——一种用于 AI 与工具集成的开源标准——连接数百种外部工具和数据源。MCP 服务器让 Claude Code 能够访问你的工具、数据库和 API。

当你发现自己总是把另一个工具（例如问题跟踪系统或监控看板）中的数据复制粘贴到对话里时，就应该连接一个服务器。连接之后，Claude 可以直接读取并操作那个系统，而不必依赖你粘贴的内容。

如果你要连接第一个服务器，请先阅读MCP 快速开始，其中有分步教程。本页是完整的参考文档。

借助 MCP 能做什么

连接好 MCP 服务器后，你可以让 Claude Code：

• 根据问题跟踪系统实现功能：“实现 JIRA issue ENG-4521 中描述的功能，并在 GitHub 上创建一个 PR。”
• 分析监控数据：“检查 Sentry 和 Statsig，查看 ENG-4521 中描述的功能的使用情况。”
• 查询数据库：“根据我们的 PostgreSQL 数据库，找出 10 个使用过功能 ENG-4521 的随机用户的邮箱。”
• 整合设计：“根据 Slack 中发布的新 Figma 设计稿，更新我们的标准邮件模板”
• 自动化工作流：“创建 Gmail 草稿，邀请这 10 位用户参加关于新功能的反馈会议。”
• 响应外部事件：一个 MCP 服务器也可以充当一个Channel，把消息推送进你的会话，这样 Claude 就能在你不在时响应 Telegram 消息、Discord 聊天或 Webhook 事件。

查找与构建 MCP 服务器

在 Anthropic 目录中浏览经过审核的连接器。目录中的连接器使用与 Claude Code 相同的 MCP 基础设施，因此你可以用 claude mcp add 添加其中列出的任何远程服务器。

要构建你自己的服务器，关于协议基础请参阅MCP 服务器指南，关于身份验证、测试和提交到目录，请参阅Claude 连接器构建文档。

你也可以让 Claude 用官方的 mcp-server-dev 插件为你搭建一个服务器的脚手架。

/plugin install mcp-server-dev@claude-plugins-official

/mcp-server-dev:build-mcp-server

安装 MCP 服务器

根据你的需求，MCP 服务器可以用几种不同的方式配置：

方式一：添加远程 HTTP 服务器

对于连接远程 MCP 服务器，HTTP 服务器是推荐的方式。这是云端服务中支持最广泛的传输方式。

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
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，因此从服务器文档中复制的配置无需修改即可使用。

一个有 url 但没有 type 的 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 服务器

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

方式三：添加本地 stdio 服务器

Stdio 服务器作为本地进程运行在你的机器上。它们非常适合那些需要直接访问系统资源或运行自定义脚本的工具。

Claude Code 会在生成的服务器进程环境中设置 CLAUDE_PROJECT_DIR 为项目根目录，因此你的服务器可以解析项目相对路径，而不必依赖当前工作目录。这与钩子在其 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}，不需要默认值。

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

方式四：添加远程 WebSocket 服务器

WebSocket 服务器维持一个持久的双向连接，适合那些会主动向 Claude 推送事件的远程 MCP 服务器。如果你的服务器只响应请求，请改用 HTTP，因为 HTTP 支持 OAuth 和 claude mcp add --transport 标志，而 WebSocket 都不支持。

在 .mcp.json 中配置 WebSocket 服务器，或使用 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 字段。身份验证只能通过请求头进行，因此请在 headers 中传入一个静态令牌，或用 headersHelper 在连接时生成一个。claude mcp add --transport 标志不接受 ws。

管理你的服务器

配置完成后，你可以用以下命令管理你的 MCP 服务器：

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get github

# Remove a server
claude mcp remove github

# (within Claude Code) Check server status
/mcp

来自 .mcp.json 中、正在等待你批准的项目范围服务器，会在 claude mcp list 中显示为 ⏸ Pending approval。交互式运行 claude 即可审阅并批准它们。claude mcp get <name> 会将待批准的服务器显示为 ⏸ Pending approval，被拒绝的服务器显示为 ✗ Rejected。

从 v2.1.196 开始，claude mcp list 和 claude mcp get 只会从没有纳入仓库版本控制的设置文件中读取 .mcp.json 的批准信息，直到你通过在该工作区中运行 claude 并接受工作区信任对话框来信任它。一个被克隆的仓库无法自行批准自己的服务器：提交到项目 .claude/settings.json 中的 enableAllProjectMcpServers 或 enabledMcpjsonServers，在一个未受信任的文件夹中会被忽略，该服务器会保持 ⏸ Pending approval 状态，而不会被连接和健康检查。

来自以下来源的批准，在未受信任的文件夹中仍然生效：

• 你的用户级 ~/.claude/settings.json
• 统一管理设置
• 通过 --settings 传入的设置
• .claude/settings.local.json，只要 git 没有跟踪它

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

/mcp 面板会在每个已连接的服务器旁显示其工具数量，并标记出那些声明支持工具能力却没有暴露任何工具的服务器。

如果你的请求需要某个仍在后台连接中的服务器的工具，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，或 Haiku 模型——以及在 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 响应和请求超时不会重试。

用 Channel 推送消息

一个 MCP 服务器也可以直接向你的会话推送消息，让 Claude 能响应外部事件，例如 CI 结果、监控告警或聊天消息。要启用这一点，你的服务器需要声明 claude/channel 能力，并在启动时用 --channels 标志为其启用。要使用官方支持的 Channel，请参阅Channels；要构建你自己的 Channel，请参阅Channels 参考文档。

单个服务器的 timeout 是每次工具调用的硬性挂钟时间上限，来自服务器的进度通知不会延长它。低于 1000 的值会被忽略，并回退到 MCP_TOOL_TIMEOUT，或在该变量未设置时回退到其默认值（约 28 小时）。在 v2.1.162 之前，低于 1000 的值会被向上取整为一秒。

至少为 1000 的单服务器 timeout，也会为下文所述的闲置超时设置一个下限：Claude Code 永远不会比该单服务器 timeout 更早地因为闲置而中止该服务器的工具调用。需要 Claude Code v2.1.203 或更高版本。

对于 HTTP 和 SSE 服务器，单次请求的首字节获取预算下限为 60 秒。

如果对某个 MCP 服务器的工具调用在闲置窗口期内既没有响应也没有进度通知，会以错误中止，而不是一直等到挂钟时间上限。闲置超时需要 Claude Code v2.1.187 或更高版本。它适用于除 IDE 服务器和 SDK 进程内服务器之外的每种服务器类型。对于 HTTP、SSE、WebSocket 和 claude.ai 连接器服务器，闲置窗口默认为五分钟；对于 stdio 服务器，默认为 30 分钟。在 v2.1.203 之前，stdio 服务器不受闲置超时约束。

设置 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 环境变量（单位毫秒）可以更改闲置窗口，或设为 0 可关闭该检查。

插件提供的 MCP 服务器

插件可以打包 MCP 服务器，插件启用后自动提供相应的工具和集成能力。插件提供的 MCP 服务器与用户配置的服务器工作方式完全相同。

插件 MCP 服务器的工作方式：

• 插件在插件根目录的 .mcp.json 中，或直接在 plugin.json 中以内联方式定义 MCP 服务器
• 插件启用后，其 MCP 服务器会自动启动
• 插件的 MCP 工具会与手动配置的 MCP 工具一起出现
• 插件服务器通过插件安装来管理，而不是通过 /mcp 命令

插件 MCP 配置示例：

在插件根目录的 .mcp.json 中：

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

或在 plugin.json 中以内联方式定义：

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

插件 MCP 特性：

• 自动生命周期管理：会话启动时，已启用插件的服务器会自动连接。如果你在会话期间启用或禁用某个插件，运行 /reload-plugins 即可连接或断开其 MCP 服务器
• 环境变量：为插件自带的文件使用 ${CLAUDE_PLUGIN_ROOT}，为能在插件更新后仍保留的持久化状态使用 ${CLAUDE_PLUGIN_DATA}，为稳定的项目根目录使用 ${CLAUDE_PROJECT_DIR}
• 用户环境访问权限：与手动配置的服务器一样，可以访问相同的环境变量
• 多种传输类型：支持 stdio、SSE、HTTP 和 WebSocket 传输方式，但具体支持情况可能因服务器而异

查看插件 MCP 服务器：

# Within Claude Code, see all MCP servers including plugin ones
/mcp

插件服务器会带着标明其来自插件的指示符出现在列表中。

插件 MCP 工具名称：

来自插件打包的 MCP 服务器的工具，其可调用名称中同时包含插件名称和服务器键。完整形式是 mcp__plugin_<插件名称>_<服务器名称>__<工具名称>，其中任何 A-Z、a-z、0-9、_ 和 - 之外的字符都会被替换为 _。对于打包在名为 my-plugin 的插件中的 database-tools 服务器，其 query 工具的可调用名称是：

mcp__plugin_my-plugin_database-tools__query

在权限规则、某个技能的 allowed-tools 列表、子智能体的 tools 字段，或钩子匹配器中引用该工具时，请使用这个完整名称。一个针对裸服务器键编写的钩子匹配器，例如 mcp__database-tools__.*，永远不会对一个插件打包的服务器触发。

该服务器本身以限定名称 plugin:<插件名称>:<服务器名称> 注册，例如 plugin:my-plugin:database-tools。在需要一个已配置服务器名称的地方使用这个名称，例如mcp_tool 钩子的 server 字段。

插件 MCP 服务器的优势：

• 打包分发：工具和服务器打包在一起
• 自动搭建：无需手动配置 MCP
• 团队一致性：安装该插件的所有人都能获得相同的工具

关于打包 MCP 服务器到插件中的详情，请参阅插件组件参考。

MCP 安装范围

MCP 服务器可以配置在三种范围中。你选择的范围控制着该服务器会加载到哪些项目中，以及该配置是否与你的团队共享。管理员也可以通过统一管理配置在企业级别部署服务器。

Local 范围

Local 范围是默认值。一个 local 范围的服务器只会加载到你添加它时所在的项目中，并且只对你私有。Claude Code 会把它存储在 ~/.claude.json 中该项目对应的路径下，因此同一个服务器不会出现在你的其他项目中。对于个人开发服务器、实验性配置，或你不想纳入版本控制的带凭据服务器，请使用 local 范围。

# Add a local-scoped server (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
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"
        }
      }
    }
  }
}

Project 范围

Project 范围的服务器通过把配置存储在你项目根目录下的 .mcp.json 文件中来实现团队协作。这个文件是设计用来纳入版本控制的，确保所有团队成员都能访问相同的 MCP 工具和服务。当你添加一个 project 范围的服务器时，Claude Code 会自动创建或更新这个文件，使用合适的配置结构。

# Add a project-scoped server
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 文件的 project 范围服务器之前，先提示你批准。如果你需要重置这些批准选择，请使用 claude mcp reset-project-choices 命令。

User 范围

User 范围的服务器存储在 ~/.claude.json 中，提供跨项目的可访问性，使其在你机器上的所有项目中都可用，同时仍只对你的用户账号私有。这个范围非常适合个人实用工具服务器、开发工具，或你在不同项目中经常用到的服务。

# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

范围层级与优先级

当同一个服务器在多个地方都有定义时，Claude Code 只会连接一次，使用优先级最高的来源的定义。会使用该来源的完整服务器条目；字段不会跨范围合并。

1. Local 范围
2. Project 范围
3. User 范围
4. 插件提供的服务器
5. claude.ai 连接器

这三种范围按名称匹配重复项。插件和连接器则按端点匹配，因此一个指向与上述某个服务器相同网址或命令的插件或连接器，会被视为重复项。

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

Claude Code 支持在 .mcp.json 文件中展开环境变量，让团队既能共享配置，又能为特定机器的路径和敏感值（例如 API 密钥）保留灵活性。

支持的语法：

• ${VAR}：展开为环境变量 VAR 的值
• ${VAR:-default}：如果设置了 VAR 则展开为它的值，否则使用 default

可展开的位置： 环境变量可以在以下位置展开：

• command：服务器可执行文件的路径
• args：命令行参数
• env：传给该服务器的环境变量
• url：用于 HTTP 服务器类型
• headers：用于 HTTP 服务器身份验证

带变量展开的示例：

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

如果某个必需的环境变量未设置、且没有默认值，Claude Code 会解析配置失败。

实用示例

示例：用 Sentry 监控错误

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

用你的 Sentry 账号进行身份验证：

/mcp

然后调试生产环境问题：

What are the most common errors in the last 24 hours?

Show me the stack trace for error ID abc123

Which deployment introduced these new errors?

示例：连接 GitHub 用于代码审查

GitHub 的远程 MCP 服务器通过一个以请求头传入的 GitHub 个人访问令牌进行身份验证。要获取一个，打开你的 GitHub 令牌设置，生成一个能访问你想让 Claude 处理的仓库的新细粒度令牌，然后添加该服务器：

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

然后就可以操作 GitHub 了：

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 数据库

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

然后就可以用自然语言查询你的数据库了：

What's our total revenue this month?

Show me the schema for the orders table

Find customers who haven't made a purchase in 90 days

对远程 MCP 服务器进行身份验证

许多云端 MCP 服务器都需要身份验证。Claude Code 支持 OAuth 2.0 以实现安全连接。

当远程服务器响应 401 Unauthorized 或 403 Forbidden 时，Claude Code 会将其标记为需要身份验证。这两种状态码都会在 /mcp 中标记该服务器，方便你完成 OAuth 流程。

从 v2.1.195 开始，当令牌刷新因服务器拒绝已存储的刷新令牌而失败时，Claude Code 会立即显示一条指向 /mcp 的提示。那里该已连接服务器的菜单会提供“重新身份验证”选项，方便你在下一次工具调用失败之前重新登录。

一个返回指向其授权服务器的 WWW-Authenticate 响应头的自定义服务器，会获得与其他任何远程服务器一样的自动发现机制。

从 v2.1.193 开始，当一个或多个已配置的服务器需要身份验证时，Claude Code 还会显示一条启动提示，因此你不必打开 /mcp 才能发现哪些服务器需要登录。

非交互模式下没有 /mcp 面板，因此 Claude Code 无法为你运行 OAuth 流程。从 v2.1.196 开始，当在启用了默认设置的工具搜索的 claude -p 或 Agent SDK 运行期间，一个已配置的服务器需要身份验证时，Claude Code 会告诉 Claude 该服务器的工具在你授权之前不可用。这样 Claude 就可以指出哪个服务器需要登录，而不是表现得好像该服务器从未配置过一样。请从交互式会话中用 /mcp 或 claude mcp login <name> 完成登录。

如果你为该服务器配置了 headers.Authorization，而该服务器拒绝了这个请求头，Claude Code 会把该连接报告为失败，而不是回退到 OAuth。请检查该令牌对该 MCP 端点是否有效，或移除该请求头以使用 OAuth 流程。

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

/mcp

从命令行进行身份验证

从 v2.1.186 开始，claude mcp login <name> 可以直接从你的 shell 运行某个已配置服务器的 OAuth 流程，因此你不需要在会话内打开 /mcp 面板。

claude mcp login sentry

之后要清除已存储的凭据，运行 claude mcp logout <name>。

从 v2.1.191 开始，该命令能检测到本地没有可用的浏览器（例如在 SSH 会话中，或在没有显示服务器的 Linux 上），并直接打印授权网址，而不是尝试打开浏览器。在你本机上打开该网址，然后把浏览器地址栏中的完整重定向网址粘贴回该提示。粘贴这一步需要一个交互式终端，因此请用 ssh -t 连接。传入 --no-browser，即使检测到本地有浏览器，也强制显示网址提示。

claude mcp login sentry --no-browser

使用固定的 OAuth 回调端口

有些 MCP 服务器要求预先注册一个特定的重定向 URI。默认情况下，Claude Code 会为 OAuth 回调随机选择一个可用端口。使用 --callback-port 可以固定该端口，使其匹配一个预先注册的、形如 http://localhost:PORT/callback 的重定向 URI。

你可以单独使用 --callback-port（配合动态客户端注册），也可以与 --client-id 一起使用（配合预先配置的凭据）。

# Fixed callback port with dynamic client registration
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

使用预先配置的 OAuth 凭据

有些 MCP 服务器不支持通过动态客户端注册（Dynamic Client Registration）自动完成 OAuth 搭建。如果你看到类似“Incompatible auth server: does not support dynamic client registration”的错误，说明该服务器需要预先配置的凭据。Claude Code 也支持使用客户端 ID 元数据文档（CIMD）而非动态客户端注册的服务器，并能自动发现它们。如果自动发现失败，请先通过该服务器的开发者门户注册一个 OAuth 应用，然后在添加该服务器时提供这些凭据。

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

覆盖 OAuth 元数据发现

让 Claude Code 指向一个特定的 OAuth 授权服务器元数据网址，以绕过默认的发现链。当 MCP 服务器的标准端点出错，或你想通过内部代理路由发现请求时，可以设置 authServerMetadataUrl。默认情况下，Claude Code 会先检查 /.well-known/oauth-protected-resource 处的 RFC 9728 受保护资源元数据，然后回退到 /.well-known/oauth-authorization-server 处的 RFC 8414 授权服务器元数据。

在你服务器 .mcp.json 配置中的 oauth 对象里设置 authServerMetadataUrl：

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

该网址必须使用 https://。authServerMetadataUrl 需要 Claude Code v2.1.64 或更高版本。该元数据网址中的 scopes_supported 会覆盖上游服务器所声明的作用域。

限制 OAuth 作用域

设置 oauth.scopes 可以固定 Claude Code 在授权流程中请求的作用域。当上游授权服务器声明的作用域比你想授予的更多时，这是将某个 MCP 服务器限制为安全团队认可的子集的受支持方式。该值是一个以空格分隔的单一字符串，格式与 RFC 6749 §3.3 中的 scope 参数一致。

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes 的优先级高于 authServerMetadataUrl 以及该服务器在 /.well-known 处发现的作用域。留空不设置，即可让该 MCP 服务器自行决定请求的作用域集合。

从 v2.1.196 开始，当未设置 oauth.scopes 时，Claude Code 会请求该服务器 WWW-Authenticate 响应头或其受保护资源元数据中提供的作用域，如果两者都没有提供，则不发送任何 scope 参数。它不再从自动发现的授权服务器元数据中请求完整的 scopes_supported 目录。请求那整份目录，会导致那些声明仅管理员或模板作用域的身份提供方，以 invalid_scope 错误拒绝该授权请求。从已配置的 authServerMetadataUrl 获取的元数据，仍会将其 scopes_supported 作为请求的作用域提供。

如果授权服务器在 scopes_supported 中声明了 offline_access，Claude Code 会将其追加到固定的作用域中，这样访问令牌就可以在不重新进行浏览器登录的情况下刷新。

如果该服务器之后对某次工具调用返回了 403 insufficient_scope，Claude Code 会用相同的固定作用域重新进行身份验证。当你需要的某个工具要求固定作用域之外的作用域时，请扩大 oauth.scopes。

使用动态请求头实现自定义身份验证

如果你的 MCP 服务器使用的是 OAuth 之外的身份验证方案，例如 Kerberos、短期令牌，或内部 SSO，可以使用 headersHelper 在连接时生成请求头。Claude Code 会运行该命令，并将其输出合并到连接请求头中。

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

该命令也可以是内联的：

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

要求：

• 该命令必须向 stdout 写入一个字符串键值对组成的 JSON 对象
• 该命令在一个带有 10 秒超时限制的 shell 中运行
• 动态请求头会覆盖同名的任何静态 headers

该辅助脚本会在每次连接时（会话启动和重连时）全新运行一次。没有缓存机制，因此任何令牌复用都由你的脚本自行负责。

从 v2.1.193 开始，如果某次工具调用返回 401 Unauthorized 或 403 Forbidden，Claude Code 会自动重新运行该辅助脚本，用新的请求头重新连接，并重试该次调用一次。只有在这次重试也失败时，Claude Code 才会在 /mcp 中把该服务器标记为需要身份验证。

Claude Code 在执行该辅助脚本时会设置以下环境变量：

利用这些变量，可以编写一个能服务多个 MCP 服务器的单一辅助脚本。

对于插件提供的服务器，该辅助脚本运行时其工作目录也会设为该插件的根目录，因此一个相对的 headersHelper 路径会在插件目录内解析，而不是相对于会话的工作目录解析。需要 Claude Code v2.1.195 或更高版本。

从 JSON 配置添加 MCP 服务器

如果你已经有某个 MCP 服务器的 JSON 配置，可以直接添加它：

# Basic syntax
claude mcp add-json <name> '<json>'

# Example: Adding an HTTP server with JSON configuration
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Example: Adding a stdio server with JSON configuration
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Example: Adding an HTTP server with pre-configured OAuth credentials
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

claude mcp get weather-api

从 Claude Desktop 导入 MCP 服务器

如果你已经在 Claude Desktop 中配置了 MCP 服务器，可以将它们导入：

# Basic syntax 
claude mcp add-from-claude-desktop 

claude mcp list 

通过 claude mcp 命令添加的服务器名称只能包含字母、数字、短横线和下划线。Claude Desktop 不施加这个限制，因此如果一个 Claude Desktop 服务器的名称包含其他字符（例如空格），就无法被导入。导入过程会报告每个被拒绝的名称，并仍会导入你选中的其他服务器。在 v2.1.205 之前，第一个无效的名称会中止整个导入过程，你选中的服务器都不会被添加。

从 claude.ai 使用 MCP 服务器

如果你已经用 claude.ai 账号登录了 Claude Code，你在 claude.ai 中添加的 MCP 服务器会自动在 Claude Code 中可用：

/mcp

从 v2.1.161 开始，你从未登录过的连接器会被折叠在 claude.ai 部分末尾的一行 Show unused connectors 之后，这样一个由组织统一配置的列表就不会占满整个面板。选中该行即可展开它们。你之前登录过的连接器，即使当前需要重新进行身份验证，也始终保持可见。

只有当你当前生效的身份验证方式是你的 claude.ai 订阅时，才会获取来自 claude.ai 的连接器。当 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、apiKeyHelper，或诸如 Amazon Bedrock 或 Google Cloud 的 Agent Platform 这样的第三方服务商生效时，即使你之前运行过 /login，这些连接器也不会加载。

如果 /mcp 没有列出你添加的某个连接器，运行 /status 确认当前生效的身份验证方式，取消设置那个环境变量，或移除 apiKeyHelper 设置，然后运行 /login 选择你的 claude.ai 账号。

你在 Claude Code 中添加的服务器，相对于一个指向同一网址的 claude.ai 连接器具有优先权。发生这种情况时，/mcp 会将该连接器列为隐藏状态，并说明如果你更想使用该连接器，该如何移除这个重复项。

有些由 Anthropic 托管的连接器，例如 Microsoft 365、Gmail 和 Google Calendar，不支持通过 Claude Code 进行本地 OAuth，因为其上游身份提供方只接受 claude.ai 注册过的重定向网址。从 v2.1.162 开始，在 /mcp 中对这些托管服务之一进行身份验证，会显示一条消息，引导你改到 claude.ai 的“Settings → Connectors”中连接它。一旦在那里连接成功，该连接器就会自动出现在 Claude Code 中。

禁用 claude.ai 连接器

要在 Claude Code 中禁用 claude.ai 的 MCP 服务器，请在任意设置范围中将 disableClaudeAiConnectors 设为 true：

{
  "disableClaudeAiConnectors": true
}

这个设置遵循“任一来源为真即生效”的语义：任何设置来源中的 true 都具有优先权。一个已纳入版本控制的项目 .claude/settings.json 可以让某个仓库退出使用云端连接器，但项目级的 false 无法重新启用一个已被用户级或策略级 true 禁用的连接器。通过 --mcp-config 显式传入的服务器不受此影响。

你也可以将 ENABLE_CLAUDEAI_MCP_SERVERS 环境变量设为 false，这对当前 shell 会话有同样的效果：

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

要屏蔽个别 claude.ai 连接器而不是全部屏蔽，可将它们按名称或网址模式添加到 deniedMcpServers 中。例如，一个值为 "claude.ai Slack" 的 serverName 条目会屏蔽 Slack 连接器。要只为当前项目切换某个连接器的开关，请使用 /mcp 面板。

将 Claude Code 用作 MCP 服务器

你可以把 Claude Code 本身用作一个供其他应用连接的 MCP 服务器：

# Start Claude as a stdio MCP server
claude mcp serve

你可以在 Claude Desktop 中使用它，方法是将以下配置添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

which claude

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

MCP 输出限制与警告

当 MCP 工具产生大量输出时，Claude Code 会帮助管理 Token 用量，以避免压垮你的对话上下文：

• 输出警告阈值：当任何 MCP 工具的输出超过 10,000 个 Token 时，Claude Code 会显示一条警告
• 可配置的上限：你可以用 MAX_MCP_OUTPUT_TOKENS 环境变量调整允许的最大 MCP 输出 Token 数
• 默认上限：默认最大值是 25,000 个 Token
• 适用范围：该环境变量适用于未声明自己上限的工具。设置了 anthropic/maxResultSizeChars 的工具会改为对文本内容使用该值，无论 MAX_MCP_OUTPUT_TOKENS 设为多少。返回图像数据的工具仍受 MAX_MCP_OUTPUT_TOKENS 约束

要为产生大量输出的工具提高上限：

export MAX_MCP_OUTPUT_TOKENS=50000
claude

这在使用以下这类 MCP 服务器时尤其有用：

• 查询大型数据集或数据库
• 生成详细的报告或文档
• 处理大量的日志文件或调试信息

为特定工具提高上限

如果你在构建一个 MCP 服务器，可以在该工具 tools/list 响应条目中设置 _meta["anthropic/maxResultSizeChars"]，允许个别工具返回超过默认落盘阈值的结果。Claude Code 会将该工具的阈值提高到标注的值，上限为 500,000 个字符。

这对于那些本身就会返回大量但必要输出的工具很有用，例如数据库模式或完整的文件树。没有这个标注时，超过默认阈值的结果会被落盘保存，并在对话中替换为一个文件引用。

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

对于文本内容，这个标注独立于 MAX_MCP_OUTPUT_TOKENS 生效，因此对于声明了这个标注的工具，用户不需要提高该环境变量。返回图像数据的工具仍受 Token 上限约束。

带根级组合关键字的工具输入模式

有些 MCP 服务器会将某个工具的输入模式声明为一个 JSON Schema 联合类型，在模式的顶层使用 anyOf、oneOf 或 allOf。Claude API 不接受在模式根层级使用这些关键字。它确实接受嵌套在 properties 内部的组合关键字，Claude Code 会原样发送这些内容。

从 Claude Code v2.1.195 开始，带有根级组合关键字的工具仍会保持可用。在把该工具发送给 API 之前，Claude Code 会将该模式扁平化为一个单一对象，并在该工具的描述前加上一句说明，告诉 Claude 哪些参数组是相关联的：

• allOf：合并每个分支的属性，且每个分支的 required 列表仍然生效
• anyOf 和 oneOf：合并每个分支的属性，且每个分支的 required 列表会在工具描述中说明，而不是由模式强制执行

你的服务器会收到 Claude 选择的任意参数，因此仍应在服务器端校验这些参数组合。

当 Claude Code 无法生成一个 API 能接受的模式时，或在没有收到启用该重写功能的远程配置的部署上（例如一台离线机器），它会跳过那一个工具，在该服务器的日志中记录原因，并让该服务器的其他工具保持可用。早于 v2.1.195 的版本会跳过每一个输入模式带有根级 anyOf、oneOf 或 allOf 的工具。

要求为特定工具批准

如果你在构建一个 MCP 服务器，可以在该工具 tools/list 响应条目中将 _meta["anthropic/requiresUserInteraction"] 设为 true，将该工具标记为每次调用都需要显式批准。该值必须是 JSON 布尔值 true；任何其他值都会被忽略。

Claude Code 会在每次调用该工具时显示权限提示，即使在 acceptEdits、auto 和 bypassPermissions 权限模式下也是如此，并且不会为它提供“不再询问”选项。匹配该工具的允许规则也不会跳过这个提示。在从不提示的 dontAsk 模式下，Claude Code 会改为直接拒绝该调用。

这个提示必须送达一个人。在使用 --permission-prompt-tool 的非交互模式下，提示工具对一个被标记工具返回的 allow 结果，会被转换为拒绝，并附带消息 MCP tool requires user interaction; not supported via --permission-prompt-tool。Agent SDK 的 canUseTool 回调确实会收到这些调用，并可以批准它们，因为该 SDK 主机应当会将它们展示给用户。

请将这个机制用于那些权限提示本身就是重点的工具，例如一个同意或授权步骤，如果自动批准，就意味着从未有真人同意过。同一服务器的其他工具会保持正常的权限行为。

以下 tools/list 条目将一个工具标记为始终需要批准。

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

anthropic/requiresUserInteraction 标注需要 Claude Code v2.1.199 或更高版本。更早的版本会忽略它，并应用标准的权限流程。

当一个会话连接到远程控制或某个 SDK 主机时，Claude Code 会将该权限请求标记为需要用户交互，因此客户端会显示该工具的权限提示供你回答，而不是显示一个一键批准操作。

响应 MCP 征询请求

MCP 服务器可以在任务进行中使用征询（elicitation）机制向你请求结构化输入。当某个服务器需要一些它自己无法获取的信息时，Claude Code 会显示一个交互式对话框，并将你的回复传回该服务器。你这边不需要任何配置：当某个服务器请求时，征询对话框会自动出现。

服务器可以用两种方式请求输入：

• 表单模式：Claude Code 会显示一个带有该服务器定义的表单字段的对话框（例如用户名和密码提示）。填写这些字段并提交。
• 网址模式：Claude Code 会打开一个用于身份验证或批准的浏览器网址。在浏览器中完成该流程，然后在 CLI 中确认。

要在不显示对话框的情况下自动响应征询请求，请使用Elicitation 钩子。

如果你在构建一个使用征询机制的 MCP 服务器，关于协议细节和模式示例，请参阅MCP 征询规范。

使用 MCP 资源

MCP 服务器可以暴露一些资源，你可以用 @ 提及来引用它们，就像引用文件一样。

引用 MCP 资源

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

Compare @postgres:schema://users with @docs:file://database/user-model

用 MCP 工具搜索实现规模化

工具搜索通过推迟加载工具定义、直到 Claude 真正需要它们，来保持 MCP 上下文用量处于低水平。会话启动时只加载工具名称和服务器说明，因此添加更多 MCP 服务器对你上下文窗口的影响很小。Claude Code 不会为单个服务器设置固定的工具数量上限；实际限制取决于你的上下文窗口预算。

工作原理

工具搜索默认启用。MCP 工具会被推迟加载，而不是提前载入上下文，Claude 会用一个搜索工具在任务需要时发现相关的工具。只有 Claude 实际使用的工具才会进入上下文。从你的角度看，MCP 工具的工作方式与以前完全一样。

如果你更喜欢基于阈值的加载方式，可以设置 ENABLE_TOOL_SEARCH=auto，让工具模式在其占用不超过上下文窗口 10% 时提前加载，只推迟超出部分。关于所有选项，请参阅配置工具搜索。

面向 MCP 服务器作者

如果你在构建一个 MCP 服务器，启用工具搜索后，服务器说明字段会变得更有用。服务器说明能帮助 Claude 理解何时该搜索你的工具，类似于技能的工作方式。

添加清晰、描述性的服务器说明，解释：

• 你的工具处理哪一类任务
• Claude 应该在什么时候搜索你的工具
• 你的服务器提供的关键能力

Claude Code 会将每个工具描述和服务器说明截断为 2KB。请保持简洁以避免被截断，并把关键细节放在开头附近。

配置工具搜索

工具搜索默认启用：MCP 工具会被推迟并按需发现。在 Google Cloud 的 Agent Platform 上，Claude Code 默认禁用它。当 ANTHROPIC_BASE_URL 指向一个非第一方主机时，它也会被禁用，因为大多数代理不会转发 tool_reference 块。显式设置 ENABLE_TOOL_SEARCH 可覆盖这两种回退行为。

工具搜索需要一个支持 tool_reference 块的模型。Haiku 模型不支持它。在 Google Cloud 的 Agent Platform 上，工具搜索支持 Claude Sonnet 4.5 及更高版本，以及 Claude Opus 4.5 及更高版本。

用 ENABLE_TOOL_SEARCH 环境变量控制工具搜索行为：

# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 claude

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

或在你的 settings.json 的 env 字段中设置该值。

你也可以专门禁用 ToolSearch 工具：

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

让某个服务器豁免推迟加载

如果某个服务器的工具应始终对 Claude 可见、不需要经过搜索步骤，可在该服务器的配置中将 alwaysLoad 设为 true。此后该服务器的每个工具都会在会话启动时加载到上下文中，无论 ENABLE_TOOL_SEARCH 设置如何。请将这个选项用于 Claude 每一轮都需要的少量工具，因为每个提前加载的工具都会占用本可用于你对话的上下文。

以下 .mcp.json 条目让一个 HTTP 服务器豁免推迟加载，同时让其他服务器保持推迟：

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

alwaysLoad 字段适用于所有服务器类型，需要 Claude Code v2.1.121 或更高版本。一个 MCP 服务器也可以通过在某个工具的 _meta 对象中包含 "anthropic/alwaysLoad": true，将个别工具标记为始终加载，这只对该工具单独生效。

设置 alwaysLoad: true 还会阻塞启动过程，直到该服务器连接完成，上限为标准的 5 秒连接超时。即使 MCP 启动在其他情况下默认是非阻塞的，这里也会阻塞，因为在构建第一条提示词时这些工具必须已经就位。其他服务器会继续在后台连接。

将 MCP 提示词作为命令使用

MCP 服务器可以暴露一些提示词，它们会成为 Claude Code 中可用的命令。

执行 MCP 提示词

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug in login flow" high

统一管理 MCP 配置

对于需要集中控制用户可以连接哪些 MCP 服务器的组织，请参阅统一管理 MCP 配置。其中介绍了如何用 managed-mcp.json 部署固定的服务器集合，如何用 allowedMcpServers 和 deniedMcpServers 限制服务器，以及当某个服务器被屏蔽时用户会看到什么。