AgentKit
AgentKit
文档指南
请输入
- 文档首页
AgentKitAgentKit用户指南网关接入已有 MCP Server 到 AgentKit 网关
复制全文
下载 pdf接入已有 MCP Server 到 AgentKit 网关
文档反馈
问问助手作为已拥有自建或第三方 MCP Server （Model Context Protocol Server）的企业开发者，可以通过 AgentKit 将已有 MCP Server 作为后端服务统一接入至 AgentKit 的 MCP 服务。本文从连通性验证、创建 MCP 服务、配置 MCP 工具集到 Agent 代码集成与结果检查，为您详细介绍已有 MCP Server 接入 AgentKit 的全流程操作。
场景概述
在企业已经部署了自建 MCP Server（例如内部知识库检索、工单系统工具），或计划接入第三方 MCP Server（例如 GitHub MCP、Notion MCP）场景下，可以通过 AgentKit 统一接入这些 MCP Server，而不是让每个 Agent 分别直连后端端点。
AgentKit 网关转发 MCP 请求，不改变后端 MCP 协议行为，并在入口层提供以下能力：
- 统一入站认证：为 MCP 服务增加统一的访问控制，避免后端端点裸暴露。
- 统一工具发现：通过 MCP 工具集（Toolset）集中管理工具入口，降低多 Agent 场景的配置成本。
核心概念
Streamable HTTP
Streamable HTTP 是 MCP 的一种传输方式，基于 HTTP 请求承载 JSON-RPC（JSON Remote Procedure Call）消息，支持以流式方式返回结果。
在本文中，后端 MCP Server 需要提供可被 AgentKit 网关调用的 Streamable HTTP 端点，例如https://your-mcp-server.internal:8080/mcp/v1（路径可自定义）。
tools/list 与 tools/call
- tools/list：用于枚举后端 MCP Server 提供的工具列表，返回result.tools数组。
- tools/call：用于调用某个工具，通常包含工具名与入参（例如 {"query": "xxx"}）。
MCP 工具集（Toolset）
MCP 工具集用于在 AgentKit 中对工具进行组织、检索与授权管理。
- 网关会将后端已有 MCP Server 的 tools/list 响应透传给平台侧。
- 在 AgentKit 中，可以将 MCP 服务关联到 MCP 工具集，实现工具的统一编排与管理。
前提条件
- 已开通AgentKit服务。若未开通，请登录AgentKit控制台，根据系统引导开通产品。
- 已通过 VeADK 构建 Agent，并且该 Agent 已发布至 AgentKit 控制台智能体运行时，详细操作可参考使用 VeADK 开发并部署智能体。
- 已有 MCP Server 可正常运行，且后端必须实现 MCP 协议的 Streamable HTTP 传输端点，能响应 tools/list 与 tools/call 请求，如：https://your-mcp-server.internal:8080/mcp/v1。
- 已具备可访问的网络环境，即 AgentKit 网关能访问已有 MCP Server 地址。
说明
当前 AgentKit 网关暂不支持私网 IP 地址作为后端，建议您使用如下两种方式实现网络环境的可达性。
- 同 VPC：火山引擎同 VPC（Virtual Private Cloud）下子网间网络默认互通，可内网直达。
- 公网域名：公网域名需放行出站策略，可为已有 MCP Server 所在 VPC 配置 NAT网关，详细操作可参考使用SNAT功能访问公网、使用DNAT功能向公网提供服务。
- 已准备出站凭据。已有 MCP Server 作为后端服务，需提前准备 API Key / Token 以作为 AgentKit 中 MCP 服务的出站凭据（例如Authorization: Bearer <token>或自定义 Header）。
- （可选）已创建网关实例。本文演示操作均以共享模式创建 MCP 服务和 MCP 工具集。如需在生产环境中使用，建议选择专属网关模式，需提前创建网关实例，详见创建企业网关实例。
操作限制
- AgentKit 网关仅支持 MCP 2025-03-26 及之后协议版本的 Streamable HTTP 传输，不支持直接接入 stdio 传输 / SSE（Server-Sent Events）-only 的 MCP Server。如需接入，请先使用 mcp-proxy 或同类工具将 stdio 进程或 SSE-only 服务封装为 Streamable HTTP 端点，再按本文流程接入。
- 如果接入的已有 MCP Server 是第三方 MCP Server（例如 GitHub MCP、Notion MCP），需额外注意 AgentKit 网关要能访问第三方公网域名，确保出站安全组与代理策略允许 AgentKit 网关的访问请求。
操作步骤
下文以“企业自建内部 MCP Server”为例，介绍完整的已有 MCP Server 接入 AgentKit MCP 服务的流程。本文操作假设有 2 个 自建的内部 MCP Server，且均部署在第三方云上（如阿里云），本文通过公网访问后端服务（自建的内部 MCP Server）的方式，实现网络的可达性。
步骤一：验证已有 MCP Server 可达性
向已有 MCP Server 的 Streamable HTTP 端点发送一次 tools/list 请求，用于验证网络连通性与协议可用性。示例请求代码如下：
curl -i -N --max-time 20 \
-X POST 'https://<mcp server url>' \
-H 'Authorization: Bearer <apikey>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
--data-raw '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {
"name": "curl-mcp-smoke-test",
"version": "1.0.0"
}
}
}'
参数配置表
参数 | 说明 | 取值样例 |
<mcp server url> | 替换为已有 MCP Server 的调用地址，可在已有 MCP Server 的基本信息中获取。以火山引擎 MCP 服务为例，其他 MCP 服务类似：  | https://s8u4ei27vq8gixxxxxx.apigateway-xx-xxxx.comtest/mcp |
<apikey> | 替换为已有 MCP Server 的 API Key 信息，可在基本信息中获取。以火山引擎 MCP 服务为例，其他 MCP 服务类似：  | O0omgYOtt6-DseOtxxxxxx |
Content-Type | 请求体为 JSON。 | application/json |
jsonrpc | JSON-RPC 协议版本。 | 2.0 |
method | 调用的方法名。 | tools/list |
id | 请求标识，用于匹配响应。 | 1 |
返回 JSON-RPC 响应，并包含 result.tools 数组表明已有 MCP Server 可达；若出现超时、拒绝连接或报错 5xx，请先排查网络、路径与已有 MCP Server 状态，再继续后续操作。
步骤二：创建 MCP 服务并配置入站认证和出站认证
- 登录AgentKit控制台。
- 在左侧导航树中选择“网关 > MCP 接入”，在 MCP 服务页签单击“创建 MCP 服务”按钮。
-
- 参照下表配置参数。
说明
- 基本信息
- 参数说明图示名称配置 MCP 服务的名称，创建成功后不支持修改，此处配置为：mcp_service_n5z3e0jb。
所属网关选择 MCP 服务所属的网关类型，此处配置为：共享模式。- 专属网关（推荐）：MCP 服务运行在您独立创建的网关实例上，资源专属不共享，可提供稳定的容量保障。
- 共享模式：MCP 服务运行在平台统一提供的共享网关资源上，无需创建网关实例。
注意本操作用于演示使用共享模式，实际生产环境中请使用专属网关。接入方式选择接入 MCP 服务的方式，此处选择导入 MCP 服务。协议支持当前仅支持 Streamable HTTP 协议。访问路径配置新创建 MCP 服务的访问路径，此处简化操作配置为默认的/mcp。
- 网络配置
- 参数说明图示网络配置配置 MCP 服务的网络访问方式，即新创建 MCP 服务能被哪种网络访问。此处配置为：公网访问、私网访问，VPC选择“Default”，子网选择“Subnet-KBA0”。注意当前 MCP 工具集暂不支持添加仅开启“私网访问”的 MCP 服务，若您要使用私网访问的方式从 MCP 工具集中暴露 MCP 服务中的工具，请同时开启公网访问，即配置为：公网访问、私网访问。
- 公网访问：希望被 Trae / Codex 等外部服务访问，选择此方式。公网访问为默认访问方式。
- 私网访问：希望被 AgenKit 上的 Agent 访问，不对外提供服务，仅在内部使用，选择此方式。地域下的任意一个 VPC 和子网，每个可用区支持最多选择一个子网。
- 认证信息
- 参数说明图示入站身份认证配置 MCP 服务身份认证方式，此处配置为：API Key / apikey_xfj5ew80（此为系统自动生成的名称）。入站身份认证是构建服务访问的第一道安全屏障，确保只有经过授权的主体才能调用 MCP 服务，避免非法访问、数据泄露和恶意攻击。
- API Key：输入名称后，将自动为 MCP 服务创建和绑定 API Key，MCP 服务创建成功后，可在 MCP 服务详情页查看。
注意生产环境中所有 MCP 服务必须开启入站认证。未开启入站认证的 MCP 端点等同于把内部业务 API 暴露到公网，可能被未授权访问，带来越权访问与数据泄露风险。
- 后端配置
- 参数说明图示服务类型配置 MCP 服务对接的后端服务（已有 MCP Server）类型。本文操作中已有 MCP Server 部署在第三方云上且访问方式是公网访问，所以此处配置为：固定域名，即通过公网访问后端服务 MCP Server 域名的方式，访问 MCP Server。
- 函数服务：已有 MCP Server 部署在火山引擎函数服务中。
- 容器服务：已有 MCP Server 部署在火山引擎容器服务中。
- 云服务器：已有 MCP Server 部署在火山引擎云服务器中。
- 固定域名：已有 MCP Server 已在公网暴露，可通过域名直接访问。
域名配置第一个作为后端服务 MCP Server 的 url。无需修改端口号，HTTP 协议端口号默认是 80，HTTPS 协议端口号默认是 443。出站凭据配置 MCP 服务的出站授权，允许 Agent 使用该凭据访问下游资源，此处配置为：API Key / agentkit_model_key，此 API Key 为新添加的 API Key，配置信息为“前提条件”中准备的已有 MCP Server 的 API Key 信息。- 添加 API Key：
- 在 API Key下拉框中，单击底部“添加”按钮。
-
- 参考下图配置 API Key 信息，创建名为“agentkit_model_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 Server 对接 AgentKit 的 MCP 服务创建。
- 参考上述步骤2 ～ 步骤4，完成第二个已有 MCP Server 对接 AgentKit 的 MCP 服务创建。
- 基本信息
- 参数说明图示名称配置 MCP 服务的名称，此处配置为：mcp_service_j3hrfb4m。
所属网关选择 MCP 服务所属的网关类型，此处配置为：共享模式。接入方式选择接入 MCP 服务的方式，此处选择导入 MCP 服务。协议支持当前仅支持 Streamable HTTP 协议。访问路径此处配置为默认的/mcp。
- 网络配置
- 参数说明图示网络配置配置 MCP 服务的网络访问方式，此处配置为：公网访问和私网访问，VPC 选择“Default”，子网选择“Subnet-KBA0”。
- 认证信息
- 参数说明图示入站身份认证配置 MCP 服务身份认证方式，此处配置为：API Key / apikey_skrgvbq7（此为系统自动生成的名称）。注意生产环境中所有 MCP 服务需开启入站认证。未开启入站认证的 MCP 端点等同于把内部业务 API 暴露到公网，可能被未授权访问，带来越权访问与数据泄露风险。
- 后端配置
- 参数说明图示服务类型配置 MCP 服务对接的后端服务（已有 MCP Server）类型，此处配置为：固定域名。
域名配置第二个作为后端服务 MCP Server 的 url，无需修改端口号。出站凭据配置 MCP 服务的出站授权。此处配置为：API Key / inspection_api_key，此 API Key 为新添加的 API Key，配置信息为“前提条件”中准备的已有 MCP Server 的 API Key 信息。添加 API Key 操作步骤如下：- 在 API Key下拉框中，单击底部“添加”按钮。
-
- 参考下图配置 API Key 信息，创建名为“agentkit_model_key”的 API Key。本文使用的出站凭据为 API Key 为Authorization: Bearer sk-abc456，对应的填写信息为：
- API Key：sk-abc456
- Location：Header
- Parameter Name：Authorization
-
- 操作成功可分别在新创建的 MCP 服务“基本信息”页签下，看到对应服务的 MCP 访问端点。
-
步骤三：配置 MCP 工具集（Toolset）
注意
- 此步骤为可选操作，操作场景说明如下：
- 必须操作：通过 AgentKit 控制台创建 Agent 并在 Agent 中集成从 REST API / OpenAPI 转换的工具。
- 可以跳过：通过 VeADK 在 Agent 中集成从 REST API / OpenAPI 转换的工具；MCP 服务中的暴露的 MCP 工具数量较少，无需使用 MCP 工具集进行分类管理。
- 本文由于有两个 MCP 服务，为便于工具管理，所以本文操作需要配置 MCP 工具集。
- 在左侧导航树中选择“网关 > 接入”，在 MCP 工具集页签单击“创建 MCP 工具集”按钮。
-
- 在创建页面，参照下表配置参数。
- 参数说明图示基本信息MCP工具集名称配置 MCP 工具集的名称，创建成功后不可修改，此处配置为：mcp_toolset_doc。
所属网关选择 MCP 工具集所属的网关类型，此处配置为：共享模式。访问路径配置 MCP 工具集的访问路径，默认为/mcp，此处保持默认。网络配置网络配置配置 MCP 工具集的网络访问方式，即新创建 MCP 工具集能被哪种网络访问。此处配置和 MCP 服务的配置保持一致，为：公网访问和私网访问，VPC 选择“Default”，子网选择“Subnet-KBA0”。注意MCP 服务和 MCP 工具集的网络配置是相互独立的，互不影响。MCP 服务的网络配置定义 MCP 服务能被哪种网络访问，MCP 工具集的网络配置定义 MCP 工具集能被哪种网络访问，即：Agent 可通过 MCP 服务允许的访问方式直接调用 MCP 服务中的工具，也可以通过 MCP 工具集允许的访问方式调用工具集中已添加的工具。
认证信息入站身份认证配置 MCP 工具集的身份认证方式。入站身份认证是构建服务访问的第一道安全屏障，确保只有经过授权的主体才能调用 MCP 服务，避免非法访问、数据泄露和恶意攻击。此处配置为：API Key / apikey_0zr88gxy（此为系统自动生成的名称）。- API Key：输入名称后，将自动为 MCP 服务创建和绑定 API Key，MCP 服务创建成功后，可在MCP服务详情页查看。
注意- API Key 与OAuth JWT 为互斥的认证方式，同一 MCP 工具集仅可启用其中一种。
- API Key 模式最多可配置 1 个，OAuth JWT 模式最多可绑定 5 个客户端。
工具管理调用模式Agent 调用工具集时支持全量返回工具，也支持通过语义匹配或标签筛选目标工具。由于本操作使用的工具数量较少，所以此处配置为：全量返回。- 全量返回：连接 MCP 工具集后将直接返回内部所有 MCP 工具。当工具数量较少时，例如 20 个以内，建议选择该模式。
- 语义检索：基于调用意图与工具描述进行语义匹配，返回匹配程度最高的工具。 当工具数量较多，且调用方为通用类 Agent 时，建议选择该模式。
- 标签检索：基于工具标签准确筛选所需工具，当工具数量较多，且调用方为垂直领域 Agent 时， 建议选择该模式。
工具在 MCP 工具集中添加工具。单击“添加工具”按钮，在 MCP 服务中选择目标工具。支持从多个 MCP 服务中选择并组合工具，以满足您的实际业务需求。此处选择上一步创建的 2 个 MCP 服务（mcp_service_n5z3e0jb和mcp_service_j3hrfb4m）下的全部工具，即：把企业已有的自建 MCP Server 的工具接入了 AgentKit，Agent 仅需接入此 MCP 工具集就能实现统一调用这些工具。
- 单击“创建”按钮，完成 MCP 工具集的创建操作，成功创建的结果如下。
- 在新创建的 MCP 工具集“MCP 工具”页签下，可看到创建时勾选的工具。
-
- 在新创建的 MCP 工具集“调试”页签下，可按照界面步骤测试成功。
- Step 1：单击“连接测试”按钮。
- Step 2：从已有 MCP Server 接入的工具中，选择一个进行调试。
- Step 3：输入必要参数，单击“测试工具”按钮。
-
至此已成功把企业已有的自建 MCP Server 接入到 AgentKit，在 AgentKit 的 MCP 工具集中已暴露这些自建 MCP Server 的工具。后续步骤是把 MCP 工具集的信息集成到 Agent 中，集成后 Agent 可统一调用这些工具，而无需对接每个 MCP Server。
步骤四：Agent 代码集成 MCP 工具集并验证
- 在 MCP 工具集 mcp_toolset_doc 的“基本信息”页签下，获取 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中配置环境变量
- 在创建了 Agent 的虚拟环境中执行命令cd <项目根目录>，进入项目根目录。
- 执行vim .env命令，打开.env文件。
- 按i键进入编辑模式，在.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>
- 参数来源<tool_mcp_router_url>MCP 工具集调用示例中的url。<tool_mcp_router_api_key>MCP 工具集调用示例中的Authorization。
- 按esc键退出编辑模式，输入:wq保存并退出文件。
步骤五：结果验证
- 本地测试。
- 查询 Agent 可调用的 MCP工具，可看到返回的工具列表与 MCP 工具集中勾选的工具及企业已有 MCP Server 的工具一致。
-
- 将本地数据推送到线上。
- 在本地终端执行source .venv/bin/activate命令重新激活 VeADK 虚拟环境。若已在 VeADK 虚拟环境，请跳过本步骤。
- 执行cd <项目根目录>命令，进入 Agent 项目的根目录。
- 执行agentkit launch命令，发布 Agent 到 AgentKit 智能体运行时。
- 在线测试。
- 登录AgentKit控制台。在智能体运行时列表中单击目标 Agent 操作列的“在线测试”按钮。
- 输入提示词“你有哪些 MCP 工具”，成功返回企业已有 MCP Server 中的工具。
-
常见问题排查
最近更新时间：2026.09.21 11:53:34
这个页面对您有帮助吗？
有用
有用
无用
无用