claude code api 如何接入第三方 API：MCP、SDK 与实战配置指南

最后更新时间：2026-04-08。搜索 claude code api 的用户，通常不是想看概念，而是想知道怎么把内部接口、SaaS 服务和业务系统接进 Claude Code。
这篇文章按实操顺序写。你看完会明确三件事：它到底指什么、官方推荐怎么接第三方 API、以及哪些配置最容易踩坑。

快速答案（30 秒）

如果你现在就要做 claude code api 接入，可以先记住下面这组结论。这些判断决定你能不能尽快跑通。

1. 严格来说，官方没有提供一个单独叫“claude code api”的 REST 接口，让你直接把 Claude Code 当普通 HTTP 服务来调。
2. 官方推荐的第三方 API 接法有两条：用 MCP 把外部 API 暴露给 Claude Code，或者用 Claude Agent SDK 把函数包成工具。
3. 如果第三方服务本身已经有 MCP Server，优先接入；如果没有，就自己写 MCP 适配层。
4. 做这类集成时，鉴权信息应该走环境变量或请求头，不要把密钥直接写进提示词或代码注释。
5. 决定稳定性的，不是接没接上，而是权限范围、工具命名、输出大小和安全边界有没有控住。

一、claude code api 到底是什么

先把这个词讲清楚，不然很多文章一开始就会写偏。中文搜索里的 claude code api，常常混着三种需求：

1. 想让 Claude Code 直接调用第三方 API，比如 GitHub、Slack、Notion、数据库、内部业务接口。
2. 想在自己的程序里嵌入 Claude Code 的能力，让它像一个可编程 agent 一样执行任务。
3. 想把 Claude 模型本身切到第三方云厂商或外部 API 提供方上使用。

如果你的目标是“让 Claude Code 调用外部系统”，那官方答案就是 MCP。Claude Code 文档明确写了，Claude Code 可以通过 MCP 连接外部工具、数据源和 API。
如果你的目标是“在你自己的应用里编排 Claude Code 风格的 agent”，那官方答案是 Claude Agent SDK。官方也已经说明，旧的 Claude Code SDK 已经更名为 Claude Agent SDK，文档和包名都应该按新名字来写。

换句话说，今天写这类文章，不能再按旧包 @anthropic-ai/claude-code 去教，也不该把“Claude 模型 API”和“Claude Code 工具集成”混成一回事。前者是模型调用，后者是工具编排。

二、claude code api 接第三方 API 的官方路径对照

把路线先放成一个表，会比空讲术语更清楚。先判断自己是在 CLI 里扩展工具，还是在服务端里写 agent，后面的路径基本就定了：

所以，真正能落地的接入方案并不复杂：
如果你已经在用 Claude Code CLI，就优先走 MCP；如果你在写自己的应用，就优先看 Agent SDK；如果只是封装几个内部接口，不想单独部署 MCP Server，就用 Custom Tools。

三、路线一：在 Claude Code 里通过 MCP 接第三方 API

这是最标准的 Claude Code 第三方 API 接法。Claude Code 官方文档给出的核心思路很直接：MCP Server 给 Claude Code 提供访问工具、数据库和 API 的能力。
也就是说，Claude Code 自己不直接理解“你公司订单接口”是什么，它理解的是一个 MCP tool。你要做的，是把第三方 API 变成 MCP tool 暴露给它。

1. 第三方服务已经有 MCP Server

如果第三方服务本身已经提供了 MCP Server，那是最省事的情况。Claude Code 文档现在推荐优先接 HTTP 远程 MCP Server，SSE 已经是 deprecated 路线，能用 HTTP 就别再优先写 SSE。 官方命令格式是：

# 远程 HTTP MCP Server
claude mcp add --transport http my-api https://api.example.com/mcp

# 需要鉴权头时
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer $MY_API_TOKEN"

接完以后，你可以用下面几个命令确认状态：

claude mcp list
claude mcp get my-api
# 在 Claude Code 会话里查看状态
/mcp

这条路的优点，是你几乎不用自己写适配层。
只要对方 MCP Server 文档写得清楚，你直接把它加进来，再控制允许哪些工具能跑就行。对大多数外部系统接入场景来说，这是最先该尝试的路线。

2. 第三方服务没有 MCP Server

这时你就不能直接把 REST API 地址塞给 Claude Code 了。正确做法是自己写一个轻量 MCP 适配层，把第三方 API 包成工具。
官方 MCP 文档和 MCP 官方 Quickstart 都是沿着这个方向写的：先实现 MCP Server，再把它挂到 Claude 或 Claude Code 上。 在 Claude Code 侧，接本地 stdio MCP Server 的命令长这样：

claude mcp add --transport stdio --env MY_API_KEY=$MY_API_KEY order-api \
  -- python server.py --port 8080

这里有两个容易错的点，而且都很常见，尤其是在第一次本地联调时：

1. --transport、--env、--scope 这些参数都要放在 server name 之前。
2. -- 后面才是你真正运行的 MCP Server 命令。

如果你把顺序写错，这类集成表面上看起来像是“接不上”，其实只是 CLI 参数被解析错了。

3. .mcp.json 适合团队共享

如果你不想每个同事都手动敲 claude mcp add，可以把配置收进项目根目录的 .mcp.json。官方 SDK 文档也说明了，mcpServers 可以直接放进配置文件自动加载，团队配好环境变量就能复用。

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

这个写法对团队很重要，因为它把这套接法从“个人技巧”变成了“项目配置”。
你可以把域名、server name 和 headers 结构统一下来，只让每个人自己注入环境变量。

四、路线二：用 Claude Agent SDK 直接把第三方 API 包成工具

如果你的目标不是纯 CLI，而是要在自己的 Node.js、Python 或服务端程序里调 Claude agent，那么更适合走 Agent SDK。
这里要特别注意一个时效性变化：官方已经明确写了，Claude Code SDK 已经更名为 Claude Agent SDK。现在 TypeScript 包名应该写成 @anthropic-ai/claude-agent-sdk，不是旧包名。

1. 用 mcpServers 接现成的 MCP

官方文档给出的 TypeScript 结构是这样的：

import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
  prompt: "查询最新的订单状态，并总结给我",
  options: {
    mcpServers: {
      "order-api": {
        type: "http",
        url: "https://api.example.com/mcp",
        headers: {
          Authorization: `Bearer ${process.env.ORDER_API_TOKEN}`
        }
      }
    },
    allowedTools: ["mcp__order-api__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

这个例子本质上就是“代码里的 Claude Code 工具接入”。
你不是直接调用一个叫 Claude Code 的 HTTP 服务，而是把它的工具使用方式编程化，然后把外部 API 通过 MCP 注入进去。

2. 用 Custom Tools 直接打第三方 API

如果你的第三方 API 很简单，比如只要做“查订单”“发通知”“获取用户详情”三四个动作，那不一定非要单独写一个外部 MCP Server。
官方 Custom Tools 文档给了更轻的一条路：用 in-process MCP server 直接把函数注册成工具。

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
const getOrder = tool(
  "get_order",
  "根据订单号查询订单详情",
  {
    orderId: z.string()
  },
  async ({ orderId }) => {
    const res = await fetch(`https://api.example.com/orders/${orderId}`, {
      headers: {
        Authorization: `Bearer ${process.env.ORDER_API_TOKEN}`
      }
    });
    if (!res.ok) {
      return {
        isError: true,
        content: [{ type: "text", text: `查询失败: ${res.status}` }]
      };
    }
    const data = await res.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data) }]
    };
  }
);
const apiServer = createSdkMcpServer({
  name: "order-api",
  version: "1.0.0",
  tools: [getOrder]
});
for await (const message of query({
  prompt: "查询订单 A1001 的状态，并用中文列出风险点",
  options: {
    mcpServers: {
      "order-api": apiServer
    },
    allowedTools: ["mcp__order-api__get_order"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

如果你的场景是“只接几个内部接口，而且逻辑不复杂”，这种写法通常是成本最低的。
因为它少了一层独立服务部署。

五、做 claude code api 时，权限、鉴权和安全边界怎么收

大多数这类集成，失败都不是因为“不会写代码”，而是因为权限边界没收住。官方文档里有几件事必须明确，上线前最好逐项检查。

1. allowedTools 不要偷懒

Agent SDK 文档写得很清楚，MCP 工具即使已经连上，也需要显式授权 Claude 才能调用。工具名格式是 mcp__{server_name}__{tool_name}。你可以按需放开，实际项目里建议从最小权限开始，先只给读权限工具：

• mcp__github__list_issues
• mcp__order-api__get_order
• mcp__order-api__*

如果你把 allowedTools 一把全开，这类接入虽然会更省确认步骤，但也更容易越界执行不该跑的动作。

2. 密钥走 env 或 headers，不进提示词

官方文档明确建议把 API key、token 之类的凭证放在 env 字段或 HTTP headers 里。这意味着你应该这样做：

• CLI：--env ORDER_API_TOKEN=...
• .mcp.json：${ORDER_API_TOKEN}
• SDK：env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN }
• 远程 HTTP MCP：headers.Authorization = Bearer ...

而不是把密钥直接写到 prompt、示例输出或仓库文档里。一旦这类集成进入团队仓库，错误暴露密钥的成本会远高于你省下的那点配置时间。

3. 第三方 MCP Server 不是官方审计对象

Claude Code 的 MCP 文档有非常明确的风险提醒：第三方 MCP Server 由你自己承担信任责任，Anthropic 并没有验证所有三方 Server 的正确性和安全性。尤其是会拉取不受信任内容的 Server，更容易带来 prompt injection 风险。

所以，这套接法做到线上可用之前，至少做这几件事，而且最好把它写进团队接入清单：

1. 先用测试账号或脱敏数据联调。
2. 先只放开只读工具，再逐步放开写操作。
3. 给每个工具写清楚 description，避免模型误用。
4. 敏感系统单独做权限隔离，不要和日常调试工具混在一起。

六、如果你说的 claude code api 是“切第三方模型提供方”，该怎么配

还有一类搜索 claude code api 的人，真正想问的是：我能不能不用 Anthropic 直连，而是切到 Bedrock、Vertex 或 Azure 这类第三方提供方。这个需求官方 Agent SDK 也给了答案。 官方文档现在列出的第三方 provider 方式包括：

• Amazon Bedrock：CLAUDE_CODE_USE_BEDROCK=1
• Google Vertex AI：CLAUDE_CODE_USE_VERTEX=1
• Microsoft Foundry / Azure：CLAUDE_CODE_USE_FOUNDRY=1 这类配置和“接你自己的业务 API”不是一回事，但在搜索意图上经常被混到同一个 claude code api 关键词里。更简单地说：
• 你要接 GitHub、Notion、订单系统、CRM：走 MCP 或 Custom Tools
• 你要切 Claude 模型提供方：走 Bedrock / Vertex / Foundry 的 provider 配置

七、claude code api 最常见的 7 个坑

1. 还在用旧包名

现在官方已经把 Claude Code SDK 改名成 Claude Agent SDK。你如果还在文章或代码里写 @anthropic-ai/claude-code，这篇教程大概率就过时了。

2. HTTP 和 stdio 选反了

第三方服务给你的是 URL，就优先 HTTP；给你的是 npx xxx、python server.py、node build/index.js 这类命令，就走 stdio。别把 URL 硬包成 stdio，也别把本地脚本假装成 HTTP。

3. allowedTools 忘了配

这会导致你觉得工具“明明连上了却不执行”。不是模型坏了，而是权限层没放行。

4. API key 直接写死在仓库里

这是最常见的错误。这类能力一旦进团队流程，密钥泄露问题会比功能本身更先出事。

5. MCP tool description 写得太空

Claude 选择工具时会读 description。如果你的 description 只写“调用订单接口”，它就很难知道什么时候该调用。描述应该明确：做什么、输入是什么、有没有副作用。

6. 把只读和写操作放进同一个宽权限工具

更稳的做法是拆开：查询一个 tool、写入一个 tool、删除一个 tool。这样权限控制才有意义，也更方便你在不同环境做灰度放开。

7. 忘了处理大输出

官方 Claude Code 文档提到，MCP 工具输出太大时会触发 warning。所以数据库查询、日志分析、报表类接口，最好在工具层就分页、过滤或截断，不要把几十页结果一次性塞进上下文。

八、FAQ：做 claude code api 时最常见的问题

Q1：claude code api 有官方单独 REST 接口吗？

没有官方单独以这个名字暴露的“Claude Code REST API”给你直接 POST。官方推荐做法是 MCP 和 Claude Agent SDK。

Q2：claude code api 接第三方 API 时，优先 MCP 还是 SDK？

如果你已经在用 Claude Code CLI，优先 MCP；如果你在写自己的服务端或自动化程序，优先 Agent SDK。如果接口很简单，就直接 Custom Tools，别过度设计。

Q3：claude code api 能不能直接接公司内部私有 API？

可以，而且这正是最常见的使用场景之一。前提是你要把内部 API 包装成 MCP Server 或 SDK 工具，并把鉴权、权限和日志策略提前设计好。

Q4：接入后，Claude 会不会自己乱调接口？

会不会乱调，取决于你给了哪些工具、是否配置了 allowedTools、description 写得够不够清楚，以及 permission mode 是不是开得太大。

Q5：接第三方 API 后，怎么做最小化权限？

最稳的做法是按动作拆工具，优先只读，写操作单独授权，敏感工具单独命名，并且只在项目作用域开放。

Q6：它和普通 Claude API 最大的区别是什么？

普通 Claude API 更像“你发消息给模型”；这类集成更像“你把工具系统接给一个 agent，让它自己决定什么时候调、调哪个、如何继续下一步”。

Q7：这类文章里最容易写旧的点是什么？

两个地方最容易过时：一是还在写 Claude Code SDK 旧包名；二是没跟上 Claude Code 现在更推荐 HTTP MCP，而不是继续把 SSE 写成首选方案。

九、结语

如果把这篇文章压缩成一句话，最稳的结论就是：不要去找一个并不存在的“Claude Code 通用 REST 接口”，而是按官方支持的方式把第三方 API 变成 Claude 能调用的工具。

对大多数团队来说，最实用的落地顺序是：

1. 先确认第三方服务有没有现成 MCP Server。
2. 没有就自己写一个最小 MCP 适配层，或者用 Agent SDK Custom Tools 包。
3. 用 allowedTools、环境变量和项目级配置把权限边界收紧。
4. 跑一轮真实任务，检查工具是否真能稳定进入你的开发流程。

只要这四步做对，这套能力就会变成你团队里能长期复用的一部分。

参考来源

来源（访问日期：2026-04-08）Claude Code Docs: Connect Claude Code to tools via MCP 来源（访问日期：2026-04-08）Claude API Docs: Connect to external tools with MCP 来源（访问日期：2026-04-08）Claude API Docs: Give Claude custom tools 来源（访问日期：2026-04-08）Claude API Docs: Agent SDK overview 来源（访问日期：2026-04-08）Claude API Docs: Migrate to Claude Agent SDK 来源（访问日期：2026-04-08）Model Context Protocol: Build an MCP server

相关阅读

如果你还想继续看 Claude 相关内容，可以顺着下面几篇继续读：

• Claude 可用入口列表
• Claude 使用教程
• Claude 常见问题
• claude 中文版完整指南