文档中心

AgentKit

网关

将现有 REST API / OpenAPI 接入为 MCP 工具

面向已拥有存量 REST API / OpenAPI 的企业开发者，您可以通过 AgentKit Gateway 的 HTTP 转 MCP 协议模式，把工单、订单、审批、CRM 等后端接口一键包装成 Agent 可调用的 MCP 工具，无需改造后端代码。本文覆盖从准备 OpenAPI 文件、创建 MCP 服务、配置入站/出站认证、生成工具集，到 Agent 代码集成与结果验证的完整闭环流程。

场景概述

企业内部往往已经沉淀了大量 REST 风格的业务系统：工单系统、订单中心、审批流、CRM、内部知识库检索接口等。要让 Agent 调用这些系统，通常有两条路：

改造后端：让每个系统重新实现一套 MCP 协议，此方案成本高、周期长，且需要业务团队配合。

在网关侧转换：由 AgentKit Gateway 读取 OpenAPI 描述文件，自动把每个 HTTP 接口映射为一个 MCP 工具，此方案可实现后端零改造。

HTTP 转 MCP 就是第二条路径。它由 Gateway 在入口层完成协议翻译：Agent 侧发起标准的 tools/list、tools/call 请求，Gateway 根据 OpenAPI 定义翻译成后端能识别的 HTTP 请求（GET / POST / PUT / DELETE + JSON Body），并把响应回传给 Agent。

除了协议翻译，Gateway 在入口层还统一提供以下能力：

统一入站认证：Agent 调用 Gateway 时通过 API Key 或 OAuth JWT 校验身份，避免后端接口直接对外暴露。

统一出站凭据注入：后端系统需要的 API Key / Bearer Token / OAuth Token 集中托管，不进入 Agent 代码。

统一工具治理：多个后端 API 可以聚合成一个 MCP 服务或 MCP 工具集入口对 Agent 暴露。

核心概念

HTTP 转 MCP

HTTP 转 MCP 是 AgentKit Gateway 提供的一种协议模式。Gateway 读取 OpenAPI 文件，把每个 path 和 method（例如 POST /v1/estimate-calories）的组合自动生成为一个 MCP 工具（例如 estimate_calories）。

工具名与描述：默认从 OpenAPI 的 operationId 与 summary / description 提取。

工具入参 Schema：从 OpenAPI 的 parameters 与 requestBody 提取，直接暴露给模型。

OpenAPI 文件

OpenAPI 文件是描述 REST API 的标准 YAML / JSON 文件，包含服务地址、路径、方法、参数、请求体与响应体结构。

在本文中，OpenAPI 文件是 HTTP 转 MCP 的唯一工具来源——工具名称、描述、参数、Schema 全部来自 OpenAPI 定义。文件质量直接决定模型选工具与传参的准确性。

MCP 代理 vs HTTP 转 MCP

对比项	MCP 代理	HTTP 转 MCP
后端要求	后端已实现 MCP 协议（Streamable HTTP）	后端为普通 REST / HTTP 服务，具备 OpenAPI 3.0 描述
工具定义来源	由后端 MCP Server 的 tools/list 动态返回	由 Gateway 读取 OpenAPI 文件后自动生成
后端改造成本	需实现 MCP 协议	零改造，只需提供 OpenAPI 文件
典型场景	已有自建或第三方 MCP Server	存量工单、订单、审批、CRM 等 REST API

MCP 工具集（MCP Toolset）

MCP 工具集是对 MCP 工具进行组织、筛选与检索的入口。在 HTTP 转 MCP 场景下：

一份 OpenAPI 通常会生成十几到上百个工具，可以通过 MCP 工具集只挑选真正需要暴露给 Agent 的工具。

多个后端系统（工单 + 审批 + CRM）可以聚合到同一个 MCP 工具集，Agent 只对接一个工具入口。

工具数量较多时，可开启语义检索模式，模型按用户意图从工具集中动态挑选工具，降低单次 Prompt 中的工具描述占用。

前提条件

已开通AgentKit服务。若未开通，请登录AgentKit控制台，根据系统引导开通产品。

已通过 VeADK 构建 Agent，并且该 Agent 已发布至 AgentKit 控制台智能体运行时，详细操作可参考使用 VeADK 开发并部署智能体。

已完成对应后端服务的创建及业务的部署。本文操作后端服务部署在云服务器中，相关操作详见购买并使用云服务器实例。

已准备符合要求的 OpenAPI 文件。后端接口必须有 Swagger 2.0 或 OpenAPI 3.0 描述文件，文件中需包含服务地址、路径、方法、参数、请求体与响应体定义。

说明

当前仅支持 Swagger 2.0 与 OpenAPI 3.0 格式的 API 描述文件。若后端仅有非规范化的接口文档（例如 Word / Wiki 描述），需要先整理为 OpenAPI 3.0 规范文件后再接入。API 文件的编写规范参见 MCP服务API文件规范与示例。

已具备可访问的网络环境，即 AgentKit 网关能访问已有 MCP Server 地址。

说明

当前 AgentKit 网关暂不支持私网 IP 地址作为后端，建议您使用如下两种方式实现网络环境的可达性。

同 VPC：火山引擎同 VPC（Virtual Private Cloud）下子网间网络默认互通，可内网直达。

公网域名：公网域名需放行出站策略，可为已有 MCP Server 所在 VPC 配置 NAT网关，详细操作可参考使用SNAT功能访问公网、使用DNAT功能向公网提供服务。

出站凭据已就绪。后端 REST API 通常自身要求认证（例如Authorization: Bearer <token>或自定义 Header），需要提前准备好凭据作为 MCP 服务创建时的出站凭据。

（可选）已创建网关实例。本文演示操作均以共享模式创建 MCP 服务和 MCP 工具集。如需在生产环境中使用，建议选择专属网关模式，需提前创建网关实例，详见创建企业网关实例。

操作步骤

下文以“把制作菜谱的 REST API 接入为 MCP 工具”为例，介绍完整的操作流程。操作所需的工具/文件清单如下：

清单项	说明
OpenAPI 文件	操作使用的 OpenAPI 文件为cooking_tools_api.yaml。
后端服务部署位置	后端服务部署在云服务器中。
网络情况	AgentKit 与后端服务在同一 VPC 下。
出站凭据	本文使用的出站凭据为 API Key 为Authorization: Bearer sk-abc123。说明您在实际操作中，需使用自己后端服务的真实 API Key。
Agent 构建方式	通过 VeADK 构建的 Agent。

步骤一：准备并校验 OpenAPI 文件

从后端团队获取 OpenAPI 3.0 描述文件（.yaml 或 .json），并在本地校验其格式与关键字段是否完整。API 文件规范请参见 MCP 服务 API 文件规范与示例。

使用 Swagger Editor 或openapi-cli校验文件，确保文件无语法错误。

每个接口都有明确的operationId、summary与description信息。

入参字段带类型、required标记与自然语言description。

本文操作使用的 OpenAPI 文件为cooking_tools.yaml，一个可用的最小示例（片段）：

openapi: 3.0.0​
info:​
  title: Cooking Tools API​
  version: 1.0.0​
paths:​
  /v1/estimate-calories:​
    post:​
      operationId: estimate_calories​
      summary: 估算菜肴卡路里​
      description: 根据食材及用量估算一道菜的总热量​
      requestBody:​
        required: true​
        content:​
          application/json:​
            schema:​
              type: object​
              required: [ingredients]​
              properties:​
                ingredients:​
                  type: array​
                  description: 食材列表​
                  items:​
                    type: object​
                    required: [name, amount_g]​
                    properties:​
                      name:​
                        type: string​
                        description: 食材名称​
                      amount_g:​
                        type: number​
                        description: 用量（克）​
                servings:​
                  type: integer​
                  description: 份数，默认为 1​
      responses:​
        '200':​
          description: 估算成功​
          content:​
            application/json:​
              schema:​
                type: object​
                properties:​
                  total_calories:​
                    type: number​
                    description: 总热量（千卡）​
                  per_serving_calories:​
                    type: number​
                    description: 每份热量（千卡）​

参数配置说明

参数	说明	取值样例
openapi	规范版本。当前支持 Swagger 2.0 与 OpenAPI 3.0。	3.0.0
paths.<path>.<method>.operationId	会被映射为 MCP 工具名，建议使用小写下划线风格，具备业务含义。	estimate_calories
summary / description	被用于工具描述，直接影响模型选工具准确率。建议一句话概括“工具做什么”，加一段说明“何时应调用”。	根据食材及用量估算一道菜的总热量
parameters / requestBody	入参定义。字段名、类型、required、enum、description 都会转成模型看到的Schema。	title、priority

步骤二：创建 MCP 服务并配置入站认证和出站认证

登录AgentKit控制台。

在左侧导航树中选择“网关 > MCP 接入”，在 MCP 服务页签单击“创建 MCP 服务”按钮。

参照下表配置相关参数。

说明

下表仅介绍操作必须的参数，更多参数及说明请参见创建 MCP 服务。

基本信息

参数	说明	图示
名称	配置 MCP 服务的名称，创建成功后不支持修改，此处配置为：syc_cooker。
所属网关	选择 MCP 服务所属的网关类型，此处配置为：共享模式。专属网关（推荐）：MCP 服务运行在您独立创建的网关实例上，资源专属不共享，可提供稳定的容量保障。共享模式：MCP 服务运行在平台统一提供的共享网关资源上，无需创建网关实例。注意本操作用于演示使用共享模式，实际生产环境中请使用专属网关。
接入方式	选择接入 MCP 服务的方式，此处选择 HTTP 转 MCP。
访问路径	配置 MCP 服务的访问路径，此处配置为/mcp。
API 信息	上传 Swagger 2.0 和 OpenAPI 3.0 格式的 OpenAPI 文件，此处使用提前准备的文件：cooking_tools.yaml。

网络配置

参数	说明	图示
网络配置	配置 MCP 服务的网络访问方式，即新创建 MCP 服务能被哪种网络访问。由于本文操作后端服务为云服务器，实际调用 MCP 服务的 Agent 在 AgentKit 上，所以此处配置为：公网访问、私网访问。注意当前 MCP 工具集暂不支持添加仅开启“私网访问”的 MCP 服务，若您要使用私网访问的方式从 MCP 工具集中暴露 MCP 服务中的工具，请同时开启公网访问，即配置为：公网访问、私网访问。公网访问：希望被 Trae / Codex 等外部服务访问，选择此方式。公网访问为默认访问方式。私网访问：希望被 AgentKit 上的 Agent 访问，不对外提供服务，仅在内部使用，选择此方式。地域下的任意一个 VPC 和子网，每个可用区支持最多选择一个子网。

认证信息

参数	说明	图示
入站身份认证	配置MCP服务身份认证方式，此处配置为：API Key / apikey_t1k5gdoc（此为系统自动生成的名称）。入站身份认证是构建服务访问的第一道安全屏障，确保只有经过授权的主体才能调用MCP服务，避免非法访问、数据泄露和恶意攻击。 API Key：输入名称后，将自动为 MCP 服务创建和绑定 API Key，MCP 服务创建成功后，可在 MCP 服务详情页查看。 OAuth JWT：使用 OAuth 授权模式完成访问令牌申请和 API 调用，提升安全性，同时简化配置。配置前，请确认已创建用户池和客户端。注意生产环境中所有 MCP 服务需开启入站认证。未开启入站认证的 MCP 端点等同于把内部业务 API 暴露到公网，可能被未授权访问，带来越权访问与数据泄露风险。

后端配置

参数	说明	图示
服务类型	配置 MCP 服务对接的后端服务类型，此处配置为：云服务器。
服务器	选择后端业务所部署的云服务器，并配置端口。
出站凭据	配置 MCP 服务的出站授权，允许 Agent 使用该凭据访问下游资源，此处配置为：API Key / inspection_api_key，此 API Key 为新添加的 API Key，操作步骤如下。添加 API Key：在 API Key下拉框中，单击底部“添加”按钮。参考下图配置 API Key 信息，创建名为“inspection_api_key”的 API Key。本文使用的出站凭据为 API Key 为Authorization: Bearer sk-abc123，对应的填写信息为： API Key：sk-abc123 Location：Header Parameter Name：Authorization 出站凭据类型 API Key：适用于使用固定密钥进行认证的外部服务。 OAuth Client：适用于需要通过 OAuth 2.0 流程进行认证的下游服务。 “入站身份认证”类型为“API Key”时：仅支持“机器对机器 (M2M)”类型的访问凭证。 “入站身份认证”类型为“OAuth JWT”时：同时支持“机器对机器 (M2M)”和“用户委托（USER_FEDERATION）”类型的访问凭证。

单击“创建”按钮，完成 MCP 服务的创建，成功操作结果如下。

在新创建的 MCP 服务“基本信息”页签下，可看到 Gateway 为该服务生成的 MCP 访问端点（Agent 侧连接的地址）。

在新创建的 MCP 服务“MCP 工具”页签下，能看到由 OpenAPI 自动生成的工具，且工具数量与 OpenAPI 中path × method的组合数一致。

步骤三：配置 MCP 工具集（Toolset）

注意

此步骤为可选操作，操作场景说明如下：

必须操作：通过 AgentKit 控制台创建 Agent 并在 Agent 中集成从 REST API / Open API 转换的工具。

可以跳过：通过 VeADK 在 Agent 中集成从 REST API / Open API 转换的工具。

本文使用 VeADK 的方式创建 Agent 并集成 MCP，为了覆盖全流程操作，所以本文操作会配置 MCP 工具集。

在左侧导航树中选择“网关 > 接入”，在 MCP 工具集页签单击“创建 MCP 工具集”按钮。

在创建页面，参照下表配置参数。

参数	说明	图示
基本信息
MCP工具集名称	配置 MCP 工具集的名称，创建成功后不可修改，此处配置为：mcp_toolset_syc。
所属网关	选择 MCP 工具集所属的网关类型，此处配置为：共享模式。
访问路径	配置 MCP 工具集的访问路径，默认为/mcp，此处保持默认。
网络配置
网络配置	配置 MCP 工具集的网络访问方式，即新创建 MCP 工具集能被哪种网络访问。由于本文操作后端服务为云服务器，实际调用 MCP 工具集的 Agent 在 AgentKit 上，所以此处配置为：私网访问。公网访问：希望被 Trae / Codex 等外部服务访问，选择此方式。公网访问为默认访问方式。私网访问：希望被 AgentKit 上的 Agent 访问，不对外提供服务，仅在内部使用，选择此方式。地域下的任意一个 VPC 和子网，每个可用区支持最多选择一个子网。
认证信息
入站身份认证	配置 MCP 工具集的身份认证方式，此处配置为：API Key / apikey_hcrtmlsvdoc（此为系统自动生成的名称）。入站身份认证是构建服务访问的第一道安全屏障，确保只有经过授权的主体才能调用 MCP 服务，避免非法访问、数据泄露和恶意攻击。包括如下配置方式： API Key：输入名称后，将自动为MCP服务创建和绑定API Key，MCP服务创建成功后，可在MCP服务详情页查看。 OAuth JWT：使用OAuth授权模式完成访问令牌申请和API调用，提升安全性，同时简化配置。配置前，请确认已创建用户池和客户端。注意 API Key 与OAuth JWT 为互斥的认证方式，同一 MCP 工具集仅可启用其中一种。 API Key 模式最多可配置 1 个，OAuth JWT 模式最多可绑定 5 个客户端。
工具管理
调用模式	Agent 调用工具集时支持全量返回工具，也支持通过语义匹配或标签筛选目标工具。此处配置为：语义检索。全量返回：连接 MCP 工具集后将直接返回内部所有 MCP 工具。当工具数量较少时，例如 20 个以内，建议选择该模式。语义检索：基于调用意图与工具描述进行语义匹配，返回匹配程度最高的工具。当工具数量较多，且调用方为通用类Agent时，建议选择该模式。标签检索：基于工具标签准确筛选所需工具，当工具数量较多，且调用方为垂直领域 Agent 时，建议选择该模式。
工具	在 MCP 工具集中添加工具。单击“添加工具”按钮，在 MCP 服务中选择目标工具。支持从多个 MCP 服务中选择并组合工具，以满足您的实际业务需求。此处选择上一步创建的 MCP 服务（syc_cooker）下的“estimate_calories”、“generate_cooking_steps”和“ingredient_substitute”工具，以及其他 MCP 服务中的一些工具。

单击“创建”按钮，完成 MCP 工具集的创建操作，成功创建的结果如下。

在新创建的 MCP 工具集“MCP 工具”页签下，可看到创建时勾选的工具。

在新创建的 MCP 工具集“调试”页签下，可按照界面步骤测试成功。

Step 1：单击“连接测试”按钮。

Step 2：输入跟此次工具相关的提示词，系统自动匹配最合适的工具。本文操作演示中，由 REST API / OpenAPI 转换的工具为烹饪相关，此处输入“做大米饭”。

Step 3：系统根据提示词检索出可用的工具，选择一个目标工具进行调试。

Step 4：输入菜名，单击“测试工具”按钮。

步骤四：Agent 代码集成 MCP 工具集并验证

此处在通过 VeADK 构建的 Agent 中集成 MCP 工具集，目的是在 Agent 代码中连接 Gateway 暴露的 MCP 端点，并携带入站凭证完成工具发现与工具调用。

在 MCP 工具集 mcp_toolset_syc 的“基本信息”页签下，获取 MCP 工具集的 URL 信息和入站身份认证 API Key。

在火山引擎访问控制控制台“API 访问密钥”下，单击“创建 Access Key”按钮创建 Access Key，创建成功后复制 Access Key ID（AK）和 Secret Access Key（SK）信息。

您本地 VeADK 构建的 Agent 项目结构如下所示，需为 Agent 添加 AK/SK 信息和 MCP 工具集信息。

项目结构

your_project
├── __init__.py # 模块导出文件
├── .env # 环境变量文件，需要在这里配置您所需的环境变量信息
└── agent.py # Agent 定义文件

在本地环境设置环境变量

在您本地终端中执行如下命令，设置环境变量，添加 AK/SK 信息。

注意

由于 AK/SK 属于高敏感凭据，直接写入.env等静态配置文件存在泄露风险，在本地开发环境中配置火山引擎 AK/SK 时，推荐通过终端会话级环境变量导出的方式管理。

# 平台的 AK 和 SK。
export VOLCENGINE_ACCESS_KEY=<your_access_key>
export VOLCENGINE_SECRET_KEY=<your_secret_key>

在.env中配置环境变量

在.env文件中，填写如下内容添加 MCP 工具集配置。

# MCP工具集的地址（URL），支持在工具集调用示例中获取。
TOOL_MCP_ROUTER_URL=<tool_mcp_router_url>
# MCP工具集的入站 API Key凭证
TOOL_MCP_ROUTER_API_KEY=<tool_mcp_router_api_key>

参数	来源
<your_access_key>	平台的 Access Key ID（AK）的信息。
<your_secret_key>	平台的 Secret Access Key（SK）的信息。
<tool_mcp_router_url>	MCP 工具集调用示例中的url。
<tool_mcp_router_api_key>	MCP 工具集调用示例中的Authorization。

操作结果：Agent 已成功自动识别 MCP 工具集中的工具，返回的工具列表与 MCP 工具集中勾选的工具一致。

步骤五：结果验证

本地测试。

在本地向 Agent 发送提示词“使用 MCP 工具内容，告诉我水煮蛋的步骤”，Agent 能成功调用 MCP 工具集中的工具处理任务。

将代码推送至 AgentKit 控制台智能体运行时中。

在本地终端执行source .venv/bin/activate命令重新激活 VeADK 虚拟环境。若已在 VeADK 虚拟环境，请跳过本步骤。

执行cd <项目根目录>命令，进入 Agent 项目的根目录。

执行agentkit launch命令，发布 Agent 到 AgentKit 智能体运行时。

在线测试。

输入提示词“你有哪些 MCP 工具”，成功返回由 REST API 接入的、制作菜谱的工具。

常见问题排查

问题表现	可能原因	解决建议
创建 MCP 服务时工具列表为空	OpenAPI 文件缺少paths或operationId。	用 Swagger Editor 校验文件，补齐每个接口的operationId后重新上传。
创建 MCP 工具集后响应字段与 OpenAPI 定义不一致	OpenAPI 文件中的responses定义不准确。	修正 OpenAPI 文件中的responses定义。
模型选错工具或传参不对	OpenAPI 文件中summary/description/ 字段description过于简略。	为每个接口补充“工具做什么何时应调用”的自然语言描述；把关键字段定义为enum。
Gateway 返回401（入站）	入站凭证缺失或错误。	确认 Authorization 头格式；核对 API Key 或 JWT 是否与入站认证方式一致。
后端返回401 / 403（出站）	出站凭据错误或过期。	更新 Credential Provider 中的凭据值；确认 Prefix、ParameterName 与后端一致。
后端返回400参数错误	OpenAPI 中的字段名或类型与实际接口不一致。	用 Postman 等工具直连后端验证真实契约，修正 OpenAPI 后重新上传。

最近更新时间：2026.09.21 11:53:35

这个页面对您有帮助吗？

有用

无用