Claude API 接入远程 MCP(MCP Connector)怎么写:Messages 请求直连、认证与限制

不用自己在后端写 MCP 客户端循环,Claude API 的 MCP Connector 支持在 Messages 请求里通过 mcp_servers 和 mcp_toolset 直连远程服务器。本文讲清 beta 请求头、Bearer 认证、工具白名单与当前限制。

NNathaniel bigo··原创首发·AI 辅助撰写
12 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

  1. 服务端直连,免去自建 MCP 客户端循环:在 Messages API 请求里声明 mcp_servers 和 mcp_toolset,Anthropic 服务端会自动连接你的远程 MCP 地址、拉取工具列表并在同一次请求内完成调用与结果回传。
  2. 必须携带专用 Beta 标识:当前调用需在 HTTP 头传入 "anthropic-beta": "mcp-client-2025-11-20"(使用官方 SDK 时走 client.beta.messages.create 并传 betas=["mcp-client-2025-11-20"])。
  3. 只支持远程 HTTP 传输,不支持本地 stdio:目标 MCP 服务器必须提供公网可达的 HTTPS 地址(支持 Streamable HTTP 或 SSE 传输),且目前只支持 MCP 的 Tools(工具) 能力,不支持 Resources 和 Prompts。
  4. 生产环境务必用 mcp_toolset 做工具收敛:通过 default_config 和 configs 可以只放行必要的几个工具,或开启 defer_loading 避免一次性把几十个工具描述全塞进上下文。
  5. 国内免卡开通与账号服务入口:自有账号免上号自助开通可见本站 Claude Pro 充值页 与 Claude Max 充值页;缺可用账号或遇身份核验可查看 Claude 注册说明 与 Claude KYC 认证协助。

MCP Connector 直连远程工具四步

图:本站根据 Claude 官方文档:MCP connector 整理的示意图

本文根据 Claude 开发者平台官方文档《MCP connector》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 官方网站。

适用于谁

  • 搜「claude api mcp connector」「claude messages api 调用远程 mcp」的后端与全栈开发者;
  • 想让线上业务接口直接调用 Notion、Linear 或公司自建远程 MCP 工具,不想自己在业务服务里维护一套 MCP 客户端状态机的人;
  • 连上远程 MCP 后发现工具太多导致输入 token 激增,想按白名单筛选工具的人。

如果你不是自己写 API 代码,而是想在网页版或本地命令行里直接挂载现成连接器,可以看 /guides/claude-connectors 或 /guides/claude-code-mcp-setup。

一、最小可用请求怎么写(Python 与 cURL)

与常规客户端工具(详见 /guides/claude-tool-use-basics)最大的区别在于:使用 MCP Connector 时,你需要在请求体顶层传 mcp_servers 定义连接信息,再在 tools 数组里用 mcp_toolset 引用该服务器的 name。

按官方文档整理的 Python SDK 最小调用示例:

python
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "帮我查一下当前远程服务里有哪些可用工具,并查询最新一条工单状态。"}
    ],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "ticket-mcp",
            "authorization_token": "YOUR_OAUTH_BEARER_TOKEN",
        }
    ],
    tools=[
        {
            "type": "mcp_toolset",
            "mcp_server_name": "ticket-mcp",
        }
    ],
    betas=["mcp-client-2025-11-20"],
)

print(response.content)

对应的原生 cURL 请求头与核心结构如下:

bash
curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "查询最新工单状态"}],
    "mcp_servers": [{
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "ticket-mcp",
      "authorization_token": "YOUR_OAUTH_BEARER_TOKEN"
    }],
    "tools": [{"type": "mcp_toolset", "mcp_server_name": "ticket-mcp"}]
  }'

同一条请求里可以配置多个远程 MCP 服务器,只要每个条目在 mcp_servers 里的 name 唯一,并在 tools 里各自配一条对应的 mcp_toolset 即可,也可以和普通自定义工具或联网搜索工具混用。

二、认证方式与工具白名单过滤

把远程 MCP 接进生产接口时,有两项配置不能省:

1. Bearer 令牌认证(authorization_token)

大多数远程业务 MCP 服务器都受 OAuth 或 API 密钥保护。你在 mcp_servers 条目里填入 authorization_token 后,Anthropic 服务端向该 URL 发起请求时会自动带上 Authorization: Bearer <token> 请求头。注意,MCP Connector 本身不替你跑浏览器 OAuth 跳转或刷新过期令牌,你的应用后端需要先拿好有效访问令牌再传给 Messages API。

2. 用 default_config 与 configs 控制暴露哪些工具

一个成熟的第三方 MCP 服务器动辄暴露二三十个增删改查工具,全量挂载既浪费输入 token,又有误触写操作的风险。官方推荐在 mcp_toolset 中用「默认全关 + 显式白名单」的写法:

json
{
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "ticket-mcp",
      "default_config": {
        "enabled": false,
        "defer_loading": true
      },
      "configs": {
        "list_tickets": { "enabled": true },
        "get_ticket_detail": { "enabled": true }
      }
    }
  ]
}
  • 白名单模式:设 default_config.enabled 为 false,只在 configs 里把只读或安全工具设为 enabled: true;
  • 黑名单模式:保持默认启用,只在 configs 里把高危删除工具设为 enabled: false;
  • 按需延迟加载(defer_loading):开启后可避免在开局一次性加载冗长的工具 Schema,适合挂载大型工具集的场景。
Claude 会员充值与成品号提示:国内银行卡在结账页被拒时,可通过本站支付宝、微信支付或 AlipayHK 获取 iOS 订阅卡密自助开通 Claude Pro 或高配额 Claude Max(全程无需上号交密码);需要现成账号可了解 Claude Pro 成品号 与 Claude Max 5x 成品号(注:Anthropic 消费者条款禁止共享转让账号且违规可终止无退款,成品号均明确标注不质保封号)。

三、响应结构怎么读与常见报错排查

请求返回后,响应的 content 数组里会出现两类专门针对 MCP 的内容块,无需你的客户端再去跑工具回传:

  • mcp_tool_use:记录 Claude 决定调用哪个服务器(server_name)、哪个工具(name)以及传入的参数(input);
  • mcp_tool_result:记录远程 MCP 服务器返回的执行结果或报错信息(is_error),紧接着 Claude 会基于结果生成最终的 text 回复。

MCP Connector 调用报错或工具不生效排查

图:本站根据 Claude 官方文档:MCP connector 整理的示意图

如果联调报错(通用状态码对照见 /guides/claude-api-error-codes),优先核对以下四条官方限制:

  1. 只支持 Tools 原语:MCP 规范里的 Resources(资源读取)和 Prompts(提示模板)目前不会通过 API 的 MCP Connector 暴露;
  2. 必须是公网可达 HTTPS:不能填 localhost、127.0.0.1 或本地命令行 npx 启动的 stdio 服务;内网服务若要接入,需走安全网关或官方受控隧道方案;
  3. 检查 Beta 头拼写:漏传 mcp-client-2025-11-20 或拼错名称,API 会直接报参数不识别(400 invalid_request_error);
  4. 计费说明:MCP Connector 本身不收额外功能费,但远程服务器返回的工具描述和 mcp_tool_result 内容都会计入标准输入输出 token。如果团队日常更多是在本地终端用现成的编程代理调 MCP,直接开通 Claude Code 订阅服务 会比自己手写一套 API 工具链省事得多。

常见问题

问:MCP Connector 需要我的客户端收到 mcp_tool_use 后自己去请求远程服务器吗?

答:不需要。只要是配在 mcp_servers 里的远程服务器,Anthropic 服务端会在单次 API 调用内部自动完成工具列表拉取和远程执行,直接把结果拼好返回给你。

问:能不能在 Amazon Bedrock 或 Google Vertex AI 上用这个 MCP Connector?

答:官方Availability 说明中,服务端直连的外部网络类工具在不同云托管平台的支持进度与原生 Claude API(api.anthropic.com)存在差异,跨云调用前请先查核官方文档顶部的平台支持表。

问:多轮对话时,历史消息里的 mcp_tool_use 和 mcp_tool_result 要怎么传回下一轮?

答:和普通多轮 Messages 调用一样,直接把上一轮助手返回的完整 response.content 原样追加进 messages 历史列表即可,不要手动删改其中的工具调用块。

问:人在国内没有外币信用卡,怎么订阅或升级 Claude 付费套餐?

答:可在本站 AI 会员充值总览页 选择 Claude Pro 自助充值 或 Claude Max 充值,付款后即时发卡密、24 小时自助兑换且可开具增值税发票;实时价格与售后边界(含封号不质保)以商品页当天展示为准。

相关教程

参考资料

  • Claude 开发者平台文档:MCP connector — https://platform.claude.com/docs/en/agents-and-tools/mcp-connector

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  2. 02

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 开源本地部署(Docker Compose)与提示词版本管理(Prompt Management)从零上手教程

    企业内网严禁业务日志出境,又想免费拥有大模型调用链追踪与不发版热更新提示词的能力?本文按 Langfuse 官方文档整理 Docker Compose 本地一键启动(含 ClickHouse 架构注意事项)、密钥配置与 Prompt Management 标签化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入门教程:给 LangGraph 与原生 OpenAI / Claude 接口加调用链追踪、Token 成本统计与免费层限额

    智能体多步调用总是找不到哪一轮提示词跑偏、单次请求到底烧了多少 Token?本文按 LangSmith 官方文档讲清环境变量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 与 @traceable 追踪原生接口,以及 Developer 免费层额度与留存规则。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效读英文文献:PDF 翻译插件、批注导出精读与防捏造参考文献流程

    在 Zotero 里读英文顶会论文怎么无缝联动 Claude 与 ChatGPT?本文整理 Translate for Zotero 划词翻译配置、高亮批注导出精读提示词,以及杜绝 AI 捏造假 DOI 参考文献的核验闭环。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 与本地 Ollama 做个人双链笔记问答:主流插件配置与隐私脱敏边界

    想在 Obsidian 里基于自己的双链笔记库做 AI 问答又担心隐私外泄?本文对比 Copilot 与 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 与本地 Ollama 的步骤及敏感目录隔离规则。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~