通过 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 问题 ENG-4521 中描述的功能，并在 GitHub 上创建 PR。”
分析监控数据：”检查 Sentry 和 Statsig 以检查 ENG-4521 中描述的功能的使用情况。”
查询数据库：”根据我们的 PostgreSQL 数据库，查找使用功能 ENG-4521 的 10 个随机用户的电子邮件。”
集成设计：”根据在 Slack 中发布的新 Figma 设计更新我们的标准电子邮件模板”
自动化工作流：”创建 Gmail 草稿，邀请这 10 个用户参加关于新功能的反馈会议。”
对外部事件做出反应：MCP 服务器也可以充当频道，将消息推送到您的会话中，因此当您不在时，Claude 可以对 Telegram 消息、Discord 聊天或 webhook 事件做出反应。

查找和构建 MCP 服务器

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

在连接每个服务器之前，请验证您信任该服务器。获取外部内容的服务器可能会使您面临 [提示注入风险](/zh-CN/security#protect-against-prompt-injection)。

要构建您自己的服务器，请参阅 MCP 服务器指南了解协议基础知识，以及 Claude 连接器构建文档了解身份验证、测试和 Directory 提交。

您也可以使用官方的 mcp-server-dev plugin 让 Claude 为您搭建服务器。

在 Claude Code 会话中，运行：

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


如果 Claude Code 报告找不到 marketplace，请先运行 `/plugin marketplace add anthropics/claude-plugins-official`，然后重试安装。安装完成后，运行 `/reload-plugins` 在当前会话中激活它。

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

Claude 会询问您的用例，并搭建一个远程 HTTP 或本地 stdio 服务器。

安装 MCP 服务器

MCP 服务器可以根据您的需求以多种方式进行配置：

选项 1：添加远程 HTTP 服务器

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

theme

# 基本语法
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，因此从服务器文档复制的配置无需修改即可工作。

选项 2：添加远程 SSE 服务器

SSE (Server-Sent Events) 传输已弃用。请在可用的地方使用 HTTP 服务器。

theme

# 基本语法
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"

选项 3：添加本地 stdio 服务器

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

Claude Code 在生成的服务器的环境中设置 CLAUDE_PROJECT_DIR，指向项目根目录，因此您的服务器可以解析项目相对路径，而无需依赖工作目录。这与 hooks 在其 CLAUDE_PROJECT_DIR 变量中接收的目录相同。从服务器进程内部读取它，例如 Node 中的 process.env.CLAUDE_PROJECT_DIR 或 Python 中的 os.environ["CLAUDE_PROJECT_DIR"]。您的服务器也可以调用 MCP roots/list 请求，该请求返回启动 Claude Code 的目录。

此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此在项目或用户范围的 .mcp.json command 或 args 中通过 ${VAR} 扩展引用它需要一个默认值，例如 ${CLAUDE_PROJECT_DIR:-.}。插件提供的 MCP 配置直接替换 ${CLAUDE_PROJECT_DIR}，不需要默认值。

theme

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

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

**重要：选项顺序**

所有选项（--transport、--env、--scope、--header）必须在服务器名称之前。然后 --（双破折号）将服务器名称与传递给 MCP 服务器的命令和参数分开。

例如：

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

这可以防止 Claude 的标志与服务器标志之间的冲突。

选项 4：添加远程 WebSocket 服务器

WebSocket 服务器保持持久的双向连接，适合于向 Claude 主动推送事件的远程 MCP 服务器。当您的服务器仅响应请求时，请改用 HTTP，因为 HTTP 支持 OAuth 和 claude mcp add --transport 标志，而 WebSocket 两者都不支持。

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

theme

1 2	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 服务器：

theme

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

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

# 删除服务器
claude mcp remove github

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

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

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

如果您的请求需要来自仍在后台连接的服务器的工具，Claude 会在继续之前等待该服务器。启用工具搜索（这是默认设置）后，等待发生在 ToolSearch 调用内部。在没有工具搜索的配置中，例如 Vertex AI、自定义 ANTHROPIC_BASE_URL 或 ENABLE_TOOL_SEARCH=false，Claude 改为使用 WaitForMcpServers 工具。

服务器名称 workspace 保留供内部使用。如果您的配置定义了具有该名称的服务器，Claude Code 会在加载时跳过它，并显示一条警告，要求您重命名它。

动态工具更新

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 响应、连接被拒绝或超时）上最多重试初始连接三次，如果仍然无法连接，则将服务器标记为失败。身份验证和未找到错误不会重试，因为它们需要配置更改才能解决。

使用频道推送消息

MCP 服务器也可以直接将消息推送到您的会话中，以便 Claude 可以对外部事件（如 CI 结果、监控警报或聊天消息）做出反应。要启用此功能，您的服务器声明 claude/channel 功能，并在启动时使用 --channels 标志选择加入。请参阅 Channels 以使用官方支持的频道，或 Channels reference 以构建您自己的频道。

提示：

使用 --scope 标志指定配置的存储位置：
- local（默认）：仅在当前项目中对您可用（在较旧版本中称为 project）
- project：通过 .mcp.json 文件与项目中的每个人共享
- user：在所有项目中对您可用（在较旧版本中称为 global）
使用 --env 标志设置环境变量（例如，--env KEY=value）
使用 MCP_TIMEOUT 环境变量配置 MCP 服务器启动超时（例如，MCP_TIMEOUT=10000 claude 设置 10 秒超时）
通过向该服务器的 .mcp.json 条目添加 timeout 字段（以毫秒为单位）来设置每个服务器的工具执行超时，例如 "timeout": 600000 表示十分钟。这仅对该服务器覆盖 MCP_TOOL_TIMEOUT 环境变量
当 MCP 工具输出超过 10,000 个令牌时，Claude Code 将显示警告。要增加此限制，请设置 MAX_MCP_OUTPUT_TOKENS 环境变量（例如，MAX_MCP_OUTPUT_TOKENS=50000）
使用 /mcp 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证

每个服务器的 timeout 是每个工具调用的硬时钟限制，来自服务器的进度通知不会延长它。低于 1000 的值被限制为一秒。对于 HTTP 和 SSE 服务器，每个请求的 fetch 首字节预算有 60 秒的最小值，无论此值如何，因此只有工具调用监视程序遵守较小的值。

插件提供的 MCP 服务器

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

插件 MCP 服务器的工作原理：

插件在插件根目录的 .mcp.json 中或在 plugin.json 中内联定义 MCP 服务器
启用插件时，其 MCP 服务器会自动启动
插件 MCP 工具与手动配置的 MCP 工具一起出现
插件服务器通过插件安装进行管理（不是 /mcp 命令）

示例插件 MCP 配置：

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

theme

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

或在 plugin.json 中内联：

theme

{
  "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 服务器：

theme

1 2	# 在 Claude Code 中，查看所有 MCP 服务器，包括插件服务器 /mcp

插件服务器在列表中出现，并带有指示它们来自插件的指示符。

插件 MCP 服务器的优势：

捆绑分发：工具和服务器打包在一起
自动设置：无需手动 MCP 配置
团队一致性：安装插件时每个人都获得相同的工具

有关使用插件捆绑 MCP 服务器的详细信息，请参阅插件组件参考。

MCP 安装范围

MCP 服务器可以在三个不同的范围级别进行配置。您选择的范围控制服务器在哪些项目中加载以及配置是否与您的团队共享。管理员还可以通过托管配置在企业级别部署服务器。

范围	加载位置	与团队共享	存储位置
本地	仅当前项目	否	`~/.claude.json`
项目	仅当前项目	是，通过版本控制	项目根目录中的 `.mcp.json`
用户	您的所有项目	否	`~/.claude.json`

本地范围

本地范围是默认范围。本地范围的服务器仅在您添加它的项目中加载，并对您保持私密。Claude Code 将其存储在 ~/.claude.json 中该项目的路径下，因此相同的服务器不会出现在您的其他项目中。对个人开发服务器、实验配置或包含您不想在版本控制中的凭据的服务器使用本地范围。

MCP 服务器的"本地范围"术语与一般本地设置不同。MCP 本地范围的服务器存储在 `~/.claude.json`（您的主目录）中，而一般本地设置使用 `.claude/settings.local.json`（在项目目录中）。有关设置文件位置的详细信息，请参阅[设置](/zh-CN/settings#settings-files)。

theme

# 添加本地范围的服务器（默认）
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 运行时的结果：

theme

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

项目范围

项目范围的服务器通过在项目根目录中存储配置在 .mcp.json 文件中来启用团队协作。此文件设计为检入版本控制，确保所有团队成员都可以访问相同的 MCP 工具和服务。添加项目范围的服务器时，Claude Code 会自动创建或更新此文件，使用适当的配置结构。

theme

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

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

theme

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

出于安全原因，Claude Code 在使用来自 .mcp.json 文件的项目范围的服务器之前会提示批准。如果您需要重置这些批准选择，请使用 claude mcp reset-project-choices 命令。

用户范围

用户范围的服务器存储在 ~/.claude.json 中，并提供跨项目可访问性，使其在您机器上的所有项目中可用，同时对您的用户帐户保持私密。此范围适用于个人实用程序服务器、开发工具或您在不同项目中经常使用的服务。

theme

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

范围层次结构和优先级

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

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

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

`.mcp.json` 中的环境变量扩展

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

支持的语法：

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

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

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

带有变量扩展的示例：

theme

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

如果未设置所需的环境变量且没有默认值，Claude Code 将无法解析配置。

实际示例

{/* ### 示例：使用 Playwright 自动化浏览器测试

1	claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

然后编写并运行浏览器测试：

1	Test if the login flow works with test@example.com

1	Take a screenshot of the checkout page on mobile

Verify that the search feature returns results
``` */}

### 示例：使用 Sentry 监控错误

```bash theme={null}
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

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

theme

/mcp

然后调试生产问题：

theme

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

theme

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

theme

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

示例：连接到 GitHub 进行代码审查

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

theme

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

然后使用 GitHub：

theme

1	审查 PR #456 并建议改进

theme

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

theme

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

示例：查询您的 PostgreSQL 数据库

theme

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

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

theme

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

theme

显示订单表的架构

theme

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

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

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

当服务器响应 401 Unauthorized 或 403 Forbidden 时，Claude Code 将远程服务器标记为需要身份验证。任一状态代码都会在 /mcp 中标记该服务器，以便您可以完成 OAuth 流程。返回指向其授权服务器的 WWW-Authenticate 标头的自定义服务器获得与任何其他远程服务器相同的自动发现。

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

例如：

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

在 Claude Code 中，使用命令：

theme
1
/mcp


然后按照浏览器中的步骤登录。

提示：

身份验证令牌安全存储并自动刷新
使用 /mcp 菜单中的”清除身份验证”撤销访问权限
如果您的浏览器没有自动打开，请复制提供的 URL 并手动打开
如果浏览器重定向在身份验证后失败并出现连接错误，请将浏览器地址栏中的完整回调 URL 粘贴到 Claude Code 中出现的 URL 提示中
OAuth 身份验证适用于 HTTP 服务器

使用固定的 OAuth 回调端口

某些 MCP 服务器需要预先注册的特定重定向 URI。默认情况下，Claude Code 为 OAuth 回调选择随机可用端口。使用 --callback-port 固定端口，使其与 http://localhost:PORT/callback 形式的预注册重定向 URI 匹配。

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

theme

# 使用动态客户端注册的固定回调端口
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

使用预配置的 OAuth 凭据

某些 MCP 服务器不支持通过动态客户端注册进行自动 OAuth 设置。如果您看到类似”不兼容的身份验证服务器：不支持动态客户端注册”的错误，服务器需要预配置的凭据。Claude Code 也支持使用客户端 ID 元数据文档 (CIMD) 而不是动态客户端注册的服务器，并自动发现这些服务器。如果自动发现失败，请首先通过服务器的开发者门户注册 OAuth 应用，然后在添加服务器时提供凭据。

通过服务器的开发者门户创建应用，并记下您的客户端 ID 和客户端密钥。

许多服务器还需要重定向 URI。如果是这样，请选择一个端口并以 `http://localhost:PORT/callback` 的格式注册重定向 URI。在下一步中使用该相同的端口与 `--callback-port`。

选择以下方法之一。用于 `--callback-port` 的端口可以是任何可用的端口。它只需要与您在上一步中注册的重定向 URI 匹配。

<Tabs>
  <Tab title="claude mcp add">
    使用 `--client-id` 传递您的应用的客户端 ID。`--client-secret` 标志使用掩盖的输入提示输入密钥：

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

  </Tab>

  <Tab title="claude mcp add-json">
    在 JSON 配置中包含 `oauth` 对象，并将 `--client-secret` 作为单独的标志传递：

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

  </Tab>

  <Tab title="claude mcp add-json（仅回调端口）">
    使用 `--callback-port` 而不使用客户端 ID 来固定端口，同时使用动态客户端注册：

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

  </Tab>

  <Tab title="CI / 环境变量">
    通过环境变量设置密钥以跳过交互式提示：

    theme
1
2
3
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

  </Tab>
</Tabs>

在 Claude Code 中运行 `/mcp` 并按照浏览器登录流程。提示：

客户端密钥安全地存储在您的系统钥匙链（macOS）或凭据文件中，而不是在您的配置中
如果服务器使用没有密钥的公共 OAuth 客户端，仅使用 --client-id 而不使用 --client-secret
--callback-port 可以与或不与 --client-id 一起使用
这些标志仅适用于 HTTP 和 SSE 传输。它们对 stdio 服务器没有影响
使用 claude mcp get <name> 验证为服务器配置了 OAuth 凭据

覆盖 OAuth 元数据发现

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

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

theme

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

URL 必须使用 https://。authServerMetadataUrl 需要 Claude Code v2.1.64 或更高版本。元数据 URL 的 scopes_supported 覆盖上游服务器公开的范围。

限制 OAuth 范围

设置 oauth.scopes 以固定 Claude Code 在授权流程中请求的范围。这是限制 MCP 服务器到安全团队批准的子集的支持方式，当上游授权服务器公开的范围超过您想要授予的范围时。该值是单个空格分隔的字符串，与 RFC 6749 §3.3 中的 scope 参数格式匹配。

theme

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

oauth.scopes 优先于 authServerMetadataUrl 和服务器在 /.well-known 发现的范围。将其保留未设置以让 MCP 服务器确定请求的范围集。

如果授权服务器在 scopes_supported 中公开 offline_access，Claude Code 会将其附加到固定范围，以便可以在没有新浏览器登录的情况下刷新访问令牌。

如果服务器稍后为工具调用返回 403 insufficient_scope，Claude Code 会使用相同的固定范围重新进行身份验证。当您需要的工具需要固定范围之外的范围时，扩展 oauth.scopes。

使用动态标头进行自定义身份验证

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

theme

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

命令也可以是内联的：

theme

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

要求：

命令必须将字符串键值对的 JSON 对象写入标准输出
命令在 shell 中运行，超时时间为 10 秒
动态标头覆盖任何具有相同名称的静态 headers

助手在每次连接时运行（在会话启动和重新连接时）。没有缓存，因此您的脚本负责任何令牌重用。

Claude Code 在执行助手时设置这些环境变量：

变量	值
`CLAUDE_CODE_MCP_SERVER_NAME`	MCP 服务器的名称
`CLAUDE_CODE_MCP_SERVER_URL`	MCP 服务器的 URL

使用这些来编写一个为多个 MCP 服务器服务的单个助手脚本。

`headersHelper` 执行任意 shell 命令。在项目或本地范围定义时，它仅在您接受工作区信任对话框后运行。

从 JSON 配置添加 MCP 服务器

如果您有 MCP 服务器的 JSON 配置，您可以直接添加它：

theme

# 基本语法
claude mcp add-json <name> '<json>'

# 示例：添加带有 JSON 配置的 HTTP 服务器
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# 示例：添加带有 JSON 配置的 stdio 服务器
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# 示例：添加带有预配置 OAuth 凭据的 HTTP 服务器
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

theme

1	claude mcp get weather-api

提示：

确保 JSON 在您的 shell 中正确转义
JSON 必须符合 MCP 服务器配置架构
您可以使用 --scope user 将服务器添加到您的用户配置而不是项目特定的配置

从 Claude Desktop 导入 MCP 服务器

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

theme

1 2	# 基本语法 claude mcp add-from-claude-desktop

运行命令后，您将看到一个交互式对话框，允许您选择要导入的服务器。

theme

1	claude mcp list

提示：

此功能仅在 macOS 和 Windows Subsystem for Linux (WSL) 上有效
它从这些平台上的标准位置读取 Claude Desktop 配置文件
使用 --scope user 标志将服务器添加到您的用户配置
导入的服务器将具有与 Claude Desktop 中相同的名称
如果具有相同名称的服务器已存在，它们将获得数字后缀（例如，server_1）

使用来自 Claude.ai 的 MCP 服务器

如果您已使用 Claude.ai 帐户登录 Claude Code，您在 Claude.ai 中添加的 MCP 服务器会自动在 Claude Code 中可用：

在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 添加服务器。在 Team 和 Enterprise 计划上，仅管理员可以添加服务器。在 Claude.ai 中完成任何必需的身份验证步骤。在 Claude Code 中，使用命令：

theme
1
/mcp


Claude.ai 服务器在列表中出现，并带有指示它们来自 Claude.ai 的指示符。

从 v2.1.161 开始，您从未登录过的连接器会折叠在 claude.ai 部分末尾的 Show unused connectors 行后面，因此组织预配的列表不会填满面板。选择该行以展开它们。您之前登录过的连接器即使当前需要重新身份验证，也会保持可见。

Claude.ai 连接器仅在您的活跃身份验证方法是您的 Claude.ai 订阅时才会被获取。当 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、apiKeyHelper 或第三方提供商（如 Bedrock 或 Vertex）处于活跃状态时，它们不会被加载，即使您之前运行过 /login。如果 /mcp 未列出您添加的连接器，请运行 /status 以确认哪种身份验证方法处于活跃状态，取消设置该环境变量或删除 apiKeyHelper 设置，然后运行 /login 以选择您的 Claude.ai 帐户。

您在 Claude Code 中添加的服务器优先于指向相同 URL 的 claude.ai 连接器。发生这种情况时，/mcp 会将连接器列为隐藏，并显示如何删除重复项（如果您更希望使用连接器）。

要在 Claude Code 中禁用 claude.ai MCP 服务器，请将 ENABLE_CLAUDEAI_MCP_SERVERS 环境变量设置为 false：

theme

1	ENABLE_CLAUDEAI_MCP_SERVERS=false claude

将 Claude Code 用作 MCP 服务器

您可以将 Claude Code 本身用作 MCP 服务器，其他应用程序可以连接到它：

theme

1 2	# 启动 Claude 作为 stdio MCP 服务器 claude mcp serve

您可以通过将此配置添加到 claude_desktop_config.json 在 Claude Desktop 中使用它：

theme

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

**配置可执行文件路径**：`command` 字段必须引用 Claude Code 可执行文件。如果 `claude` 命令不在您的系统 PATH 中，您需要指定可执行文件的完整路径。

要查找完整路径：

theme

1	which claude

然后在您的配置中使用完整路径：

theme

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

没有正确的可执行文件路径，您会遇到类似 spawn claude ENOENT 的错误。

提示：

服务器提供对 Claude 的工具（如 View、Edit、LS 等）的访问权限。
在 Claude Desktop 中，尝试要求 Claude 读取目录中的文件、进行编辑等。
请注意，此 MCP 服务器仅向您的 MCP 客户端公开 Claude Code 的工具，因此您自己的客户端负责为单个工具调用实现用户确认。

MCP 输出限制和警告

当 MCP 工具产生大量输出时，Claude Code 可帮助管理令牌使用情况，以防止压倒您的对话上下文：

输出警告阈值：当任何 MCP 工具输出超过 10,000 个令牌时，Claude Code 显示警告
可配置限制：您可以使用 MAX_MCP_OUTPUT_TOKENS 环境变量调整最大允许的 MCP 输出令牌
默认限制：默认最大值为 25,000 个令牌
范围：环境变量适用于不声明自己限制的工具。声明 anthropic/maxResultSizeChars 的工具对文本内容使用该值，无论 MAX_MCP_OUTPUT_TOKENS 设置为什么。返回图像数据的工具仍受 MAX_MCP_OUTPUT_TOKENS 限制

要为产生大量输出的工具增加限制：

theme

1 2	export MAX_MCP_OUTPUT_TOKENS=50000 claude

这在使用以下 MCP 服务器时特别有用：

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

为特定工具提高限制

如果您正在构建 MCP 服务器，您可以通过在工具的 tools/list 响应条目中设置 _meta["anthropic/maxResultSizeChars"] 来允许单个工具返回大于默认持久化到磁盘阈值的结果。Claude Code 将该工具的阈值提高到注释值，最高为 500,000 个字符的硬上限。

这对于返回本质上很大但必要的输出的工具很有用，例如数据库架构或完整文件树。没有注释，超过默认阈值的结果会被持久化到磁盘，并在对话中被文件引用替换。

theme

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

对于文本内容，注释独立于 MAX_MCP_OUTPUT_TOKENS 应用，因此用户不需要为声明它的工具提高环境变量。返回图像数据的工具仍受令牌限制。

如果您经常遇到特定 MCP 服务器的输出警告，而您不控制这些服务器，请考虑增加 `MAX_MCP_OUTPUT_TOKENS` 限制。您也可以要求服务器作者添加 `anthropic/maxResultSizeChars` 注释或对其响应进行分页。注释对返回图像内容的工具没有影响；对于这些，提高 `MAX_MCP_OUTPUT_TOKENS` 是唯一的选择。

响应 MCP 引发请求

MCP 服务器可以在任务中途使用引发来请求您的结构化输入。当服务器需要无法自行获取的信息时，Claude Code 会显示交互式对话框并将您的响应传递回服务器。您无需进行任何配置：当服务器请求时，引发对话框会自动出现。

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

表单模式：Claude Code 显示一个对话框，其中包含服务器定义的表单字段（例如，用户名和密码提示）。填写字段并提交。
URL 模式：Claude Code 打开浏览器 URL 以进行身份验证或批准。在浏览器中完成流程，然后在 CLI 中确认。

要自动响应引发请求而不显示对话框，请使用 Elicitation hook。

如果您正在构建使用引发的 MCP 服务器，请参阅 MCP 引发规范以了解协议详细信息和架构示例。

使用 MCP 资源

MCP 服务器可以公开资源，您可以使用 @ 提及来引用，类似于您引用文件的方式。

引用 MCP 资源

在您的提示中键入 `@` 以查看来自所有连接的 MCP 服务器的可用资源。资源与文件一起出现在自动完成菜单中。使用格式 `@server:protocol://resource/path` 来引用资源：

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


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

您可以在单个提示中引用多个资源：

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

提示：

资源在引用时会自动获取并作为附件包含
资源路径在 @ 提及自动完成中可进行模糊搜索
Claude Code 在服务器支持时自动提供列出和读取 MCP 资源的工具
资源可以包含 MCP 服务器提供的任何类型的内容（文本、JSON、结构化数据等）

使用 MCP 工具搜索进行扩展

工具搜索通过延迟工具定义直到 Claude 需要它们来保持 MCP 上下文使用低。仅工具名称和服务器说明在会话启动时加载，因此添加更多 MCP 服务器对您的上下文窗口的影响最小。

工作原理

工具搜索默认启用。MCP 工具被延迟而不是预先加载到上下文中，Claude 使用搜索工具在任务需要时发现相关的工具。仅 Claude 实际使用的工具进入上下文。从您的角度来看，MCP 工具的工作方式与之前完全相同。

如果您更喜欢基于阈值的加载，请设置 ENABLE_TOOL_SEARCH=auto 以在工具适合上下文窗口的 10% 内时预先加载架构，仅延迟溢出部分。有关所有选项，请参阅配置工具搜索。

对于 MCP 服务器作者

如果您正在构建 MCP 服务器，启用工具搜索时服务器说明字段会变得更有用。服务器说明可帮助 Claude 了解何时搜索您的工具，类似于 skills 的工作方式。

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

您的工具处理的任务类别
Claude 应何时搜索您的工具
您的服务器提供的关键功能

Claude Code 将工具描述和服务器说明截断为每个 2KB。保持它们简洁以避免截断，并将关键详细信息放在开头。

配置工具搜索

工具搜索默认启用：MCP 工具被延迟并按需发现。Claude Code 在 Vertex AI 上默认禁用它。当 ANTHROPIC_BASE_URL 指向非第一方主机时，它也被禁用，因为大多数代理不转发 tool_reference 块。显式设置 ENABLE_TOOL_SEARCH 以覆盖任一回退。

工具搜索需要支持 tool_reference 块的模型：Sonnet 4 及更高版本，或 Opus 4 及更高版本。Haiku 模型不支持它。在 Vertex AI 上，工具搜索支持 Claude Sonnet 4.5 及更高版本以及 Claude Opus 4.5 及更高版本。

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

值	行为
（未设置）	所有 MCP 工具被延迟并按需加载。在 Vertex AI 上或当 `ANTHROPIC_BASE_URL` 是非第一方主机时回退到预先加载
`true`	所有 MCP 工具被延迟。Claude Code 即使在 Vertex AI 上和通过代理也会发送 beta 标头。对于早于 Sonnet 4.5 或 Opus 4.5 的 Vertex AI 模型或不支持 `tool_reference` 块的代理，请求会失败
`auto`	阈值模式：如果工具适合上下文窗口的 10% 内，则预先加载，否则延迟
`auto:N`	阈值模式，带有自定义百分比，其中 `N` 是 0-100。例如，`auto:5` 表示 5%
`false`	所有 MCP 工具预先加载，无延迟

theme

# 使用自定义 5% 阈值
ENABLE_TOOL_SEARCH=auto:5 claude

# 完全禁用工具搜索
ENABLE_TOOL_SEARCH=false claude

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

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

theme

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

豁免服务器延迟

如果服务器的工具应始终对 Claude 可见而无需搜索步骤，请在该服务器的配置中将 alwaysLoad 设置为 true。来自该服务器的每个工具随后在会话启动时加载到上下文中，无论 ENABLE_TOOL_SEARCH 设置如何。对于 Claude 在每个回合都需要的少量工具，请使用此选项，因为每个预先加载的工具会消耗本来可用于您的对话的上下文。

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

theme

{
  "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 服务器的命令。MCP 提示以 `/mcp__servername__promptname` 的格式出现。

theme

1	/mcp__github__list_prs

许多提示接受参数。在命令后面用空格分隔传递它们：

theme
1
/mcp__github__pr_review 456


theme
1
/mcp__jira__create_issue "Bug in login flow" high

提示：

MCP 提示从连接的服务器动态发现
参数根据提示的定义参数进行解析
提示结果直接注入到对话中
服务器和提示名称被规范化（空格变为下划线）

托管 MCP 配置

对于需要对用户可以连接的 MCP 服务器进行集中控制的组织，请参阅托管 MCP 配置。它涵盖使用 managed-mcp.json 部署固定服务器集、使用 allowedMcpServers 和 deniedMcpServers 限制服务器，以及当服务器被阻止时用户看到的内容。

通过 MCP 将 Claude Code 连接到工具

使用 MCP 可以做什么

查找和构建 MCP 服务器

安装 MCP 服务器

选项 1：添加远程 HTTP 服务器

选项 2：添加远程 SSE 服务器

选项 3：添加本地 stdio 服务器

选项 4：添加远程 WebSocket 服务器

管理您的服务器

动态工具更新

自动重新连接

使用频道推送消息

插件提供的 MCP 服务器

MCP 安装范围

本地范围

项目范围

用户范围

范围层次结构和优先级

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

实际示例

示例：连接到 GitHub 进行代码审查

示例：查询您的 PostgreSQL 数据库

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

使用固定的 OAuth 回调端口

使用预配置的 OAuth 凭据

覆盖 OAuth 元数据发现

限制 OAuth 范围

使用动态标头进行自定义身份验证

从 JSON 配置添加 MCP 服务器

从 Claude Desktop 导入 MCP 服务器

使用来自 Claude.ai 的 MCP 服务器

将 Claude Code 用作 MCP 服务器

MCP 输出限制和警告

为特定工具提高限制

响应 MCP 引发请求

使用 MCP 资源

引用 MCP 资源

使用 MCP 工具搜索进行扩展

工作原理

对于 MCP 服务器作者

配置工具搜索

豁免服务器延迟

将 MCP 提示用作命令

执行 MCP 提示

托管 MCP 配置

`.mcp.json` 中的环境变量扩展