You need to enable JavaScript to run this app.
文档中心
AgentKit

AgentKit

请输入
  • 文档首页
    • AgentKitAgentKit用户指南网关MCP 服务通过私网域名方式接入网关实例
复制全文
下载 pdf
我的收藏
网关
MCP 服务通过私网域名方式接入网关实例
复制全文
下载 pdf
我的收藏
MCP 服务通过私网域名方式接入网关实例
当您希望在 AgentKit 平台让 Agent 通过 MCP 调用现有的 HTTP 服务，但后端服务（MCP Server）不开放公网访问、仅能在私网通过域名访问时，可以参考本文完成接入。​
适用场景​
  • MCP Server 部署在 VPC、企业 IDC 或第三方云上私网环境。​
  • MCP Server 以私网域名对内提供访问。​
  • 需要通过 AgentKit 专属网关统一承接 MCP 服务入口，并在私网安全边界内完成调用。​
方案概述​
本文假定后端业务部署在第三方云上（如“腾讯云”）VPC，后端以腾讯云 Private DNS 中的私网域名对内暴露，现在需要在 AgentKit 中把该私网域名作为 MCP 服务后端，并将 MCP 服务关联到 AgentKit 专属网关使用。​
在上述场景下，需要以 AgentKit 专属网关承接 MCP 请求，通过私网出口访问后端服务，并通过私网 DNS 转发完成目标域名解析。实施时可按四层理解：专属网关入口、MCP 服务映射、私网网络连通、私网 DNS 解析。四层配置完整后，Agent 才能稳定调用后端能力。​
​
层级​
需要完成的配置​
目的​
专属网关​
创建支持私网访问的专属网关，并绑定用于出入网的 VPC 与子网。​
  1. 专属网关内 MCP 服务配置私网域名时指定 VPC 与子网信息。​
  1. 调用 SpaceNetwork 相关 API，配置其私网 VPC 出口，要与专属网关关联的 VPC 和子网配置一致。​
提供统一接入入口，并确定基础网络边界，使网关出站访问指定私网域名时可进入火山 VPC，进而可通过火山 VPC 访问至连通的腾讯云网络环境。​
MCP 服务​
按固定域名方式接入后端服务，并且网络类型为“私网”。​
将后端接口映射为可被 Agent 调用的 MCP 工具能力。​
私网网络​
打通专属网关所在网络（火山引擎）与后端所在网络（腾讯云）的路由与安全策略。​
火山引擎账号下承载 AgentKit 私网出站的 VPC，与腾讯云业务 VPC 通过 TR/CEN + 专线实现私网互通。​
保证 AgentKit 专属网关出站流量能到达腾讯云业务 Server 的私网 IP。​
私网 DNS​
将目标私网域名的解析请求转发到权威 DNS 或入站 DNS Endpoint。​
  1. 在腾讯云 Private DNS 创建入站 Endpoint，记录入站服务 IP 和 DNS 端口。​
  1. 调用 SpaceNetwork 相关 API，把腾讯云入站 Endpoint 的 IP 和端口配置为对应私网域名解析目标。​
保证 AgentKit 在火山侧解析目标私网域名时，能把 DNS 查询转发到腾讯云 Private DNS。​
​
前提条件​
  1. 已完成相关网络准备。​
  • 已放通业务端口，以及 DNS 所需的 UDP/TCP 53（如使用自定义 DNS 端口，以实际端口为准）。本文操作需要创建腾讯云 Private DNS 入站 Endpoint，在腾讯云 Private DNS 的“内网解析 / 服务地址”中新建入站终端节点，选择已与火山 VPC 互通的腾讯云 VPC，并记录入站服务 IP 地址。DNS 端口按标准使用 53，建议同时放通 UDP 53 和 TCP 53。相关配置可参考腾讯云官方文档 Private DNS 服务地址。​
说明​
如果业务 Server 或 DNS 部署在阿里云，配置思路和腾讯云相同：创建 PrivateZone 入站终端节点，记录入站流量服务 IP，并确保安全组放通 53 端口。相关配置可参考阿里云官网文档 阿里云入站终端节点。​
  • 已完成 AgentKit 专属网关网络规划。明确后续创建的专属网关、MCP 服务所在地域、项目、以及支持被私网访问的 VPC 和子网。​
  1. 已确认后端真实服务信息。​
  • 准备后端私网域名（如 mcp-api.example.internal）、端口、MCP 路径、认证信息，以及在腾讯云侧完成允许访问该后端的安全组规则配置。​
  • 后端服务可正常运行，且后端必须实现 MCP 协议的 Streamable HTTP 传输端点，能响应 tools/list 与 tools/call 请求。​
  • 准备后端服务 API Key / Token 以作为 AgentKit 中 MCP 服务的出站凭据（例如Authorization: Bearer <token>或自定义 Header）。​
  1. 已开通 AgentKit 服务。若未开通，请登录 AgentKit 控制台，根据系统引导开通产品。​
  1. 已通过 VeADK 构建 Agent，并且该 Agent 已发布至 AgentKit 控制台智能体运行时，详细操作可参考 使用 VeADK 开发并部署智能体。​
操作步骤​
步骤一：验证已有 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 状态，再继续后续操作。​
​​​
步骤二：创建网关实例​
网关实例是 AgentKit 的专属网关资源，用于为模型服务、MCP 服务和 MCP 工具集等资源提供统一访问入口。企业网关实例适用于生产环境或需要独立容量、资源隔离、访问入口统一管理和费用独立核算的业务场景。​
  1. 登录 AgentKit 控制台。​
  1. 在左侧导航树中选择“网关 > 网关总览”，在专属网关页签下单击“创建网关”按钮。​
  • ​​​
  1. 在创建页面参照下表完成参数配置。​
  • ​
    参数​
    说明​
    图示​
    基本信息​
    ​
    ​​​
    实例名称​
    输入网关实例名称，此处配置为：prod_mcp_gateway。​
    • 网关实例创建成功后，支持在实例“配置信息”中修改实例名称。​
    • 实例名称建议体现业务、环境和用途。​
    ​
    计费方式​
    选择网关实例的计费方式，当前仅支持按量计费。​
    ​
    网关类型​
    选择网关实例的类型，每种类型仅支持创建一个网关实例。此处选择：MCP 网关，MCP 网关用于接入 MCP 资源（MCP 服务和 MCP 工具集）。​
    ​
    规格配置​
    ​
    ​
    网关规格​
    选择网关实例的网关规格。此处选择：gateway_small_x2。​
    • 不同规格支持的 QPS、客户端连接数等资源上限和收取的费用均不相同，请选择合适的规格以免影响业务。​
    ​
    网络配置​
    ​
    ​​​
    ​
    可用区​
    选择网关实例部署的可用区，请至少选择 2 个可用区以保障网关实例高可用。​
    • 无论是否开启私网访问，均需选择可用区。​
    • 如果开启私网访问，需要在对应可用区下选择子网。​
    ​
    入站访问​
    选择网关实例的入站访问方式。此处配置为：私网访问、公网访问，关联的 VPC 和子网选择已和腾讯云网络打通的 VPC 和子网。​
    • 配置说明​
    • 网关实例创建成功后，网络访问方式不支持修改。​
    • 支持公网访问和私网访问，至少配置一种访问方式，可同时配置两种访问方式。​
    • 方式说明​
    • 公网访问：调用方位于公网环境，或需要跨网络访问网关实例，例如本地开发联调、跨 VPC/跨环境访问（无专线/内网互通条件时）。​
    • 私网访问：调用方位于同地域 VPC 内，或通过专线、VPN、云企业网等方式与 VPC 打通，需要将访问流量限制在内网范围内。​
    • 私有网络：选择网关实例使用的私有网络，建议优先选择与主要调用方、后端资源位于同一地域与同一网络规划下的 VPC 与子网。​
    • 子网：选择私有网络下的可用子网，每个可用区下选择 1 个子网，以保障服务高可用。​
    说明​
    如果您的调用方同时存在公网与内网（例如开发人员在公网联调、生产服务在 VPC 内调用），可以同时开启公网和私网访问，并且建议生产流量优先走私网访问，公网访问仅用于联调或应急使用。​
    ​
    观测配置​
    ​
    ​​​
    ​
    日志服务​
    是否为网关实例开启日志服务，开启后可查看网关实例的服务日志，便于排查失败、请求异常、运行错误等问题。此处配置为：开启。​
    • 日志功能：如果不开启可手动关闭日志服务开关，更多功能介绍，请参见 查看日志。​
    • 日志计费：启用日志服务后，平台将为您开通 TLS 服务，使用日志服务会产生相应费用，详见 日志计费说明。​
    ​
    日志项目​
    仅当开启日志服务后需配置此参数。选择网关实例日志写入的项目，网关实例将在此日志项目下，自动生成 agentkit-gateway-access-log 主题日志。​
    ​
    高级配置​
    ​
    ​
    所属项目​
    项目是一组资源的集合，您可以将本次创建的网关实例加至项目中并按项目维度统一管理，有利于保持资源独立，维护数据安全。有关项目的更多信息请参见 项目管理。​
    • 资源默认创建在 default 项目，一个资源只能归属于一个项目。​
    • 选定项目后，创建的网关实例只能被具有该项目权限的用户使用。创建网关实例后，您可以按需 更改实例所属项目。​
    • 若无可用项目，您可单击“新建项目”按钮进行创建，创建完成后，返回本页面即可选择新添加的项目。​
    ​
    ​
  1. 在页面右侧的配置详情和费用明细区域，确认当前配置对应的规格、网关类型、入站访问方式和费用项，阅读并勾选“我已阅读并同意 xxx”，单击“立即购买”按钮，完成操作。​
说明​
下图价格仅为示例没有指导意义，具体费用请以实际控制台展示为准。​
  • ​​​
步骤二：创建 MCP 服务​
  1. 在网关实例页面，单击新创建的网关实例名称。​
  • ​​​
  1. 在 MCP 页签下 MCP 服务中，单击“创建 MCP 服务”按钮。​
  • ​​​
  1. 参照下表配置参数。​
说明​
下表仅介绍操作必须的参数，更多参数及说明请参见 创建 MCP 服务。​
  • 基本信息​
  • ​
    参数​
    说明​
    图示​
    名称​
    配置 MCP 服务的名称，创建成功后不支持修改，此处配置为：mcp_service_fgajjno5。​
    ​​​
    ​
    ​
    ​
    ​
    ​
    所属网关​
    选择 MCP 服务所属的网关类型，此处配置为：专属网关，系统默认选择当前专属网关 prod_mcp_gateway。​
    • 专属网关：MCP 服务运行在您独立创建的网关实例上，资源专属不共享，可提供稳定的容量保障。​
    • 共享模式：MCP 服务运行在平台统一提供的共享网关资源上，无需创建网关实例。​
    ​
    接入方式​
    选择接入 MCP 服务的方式，此处选择导入 MCP 服务。​
    ​
    协议支持​
    当前仅支持 Streamable HTTP 协议。​
    ​
    访问路径​
    配置新创建 MCP 服务的访问路径，此处简化操作配置为默认的/mcp。​
    ​
    ​
  • 认证信息​
  • ​
    参数​
    说明​
    图示​
    入站身份认证​
    配置 MCP 服务身份认证方式，此处配置为：API Key / apikey_f2ti3mtv（此为系统自动生成的名称）。​
    入站身份认证是构建服务访问的第一道安全屏障，确保只有经过授权的主体才能调用 MCP 服务，避免非法访问、数据泄露和恶意攻击。​
    • API Key：输入名称后，将自动为 MCP 服务创建和绑定 API Key，MCP 服务创建成功后，可在 MCP 服务详情页查看。​
    • OAuth JWT：使用 OAuth 授权模式完成访问令牌申请和 API 调用，提升安全性，同时简化配置。配置前，请确认已 创建用户池 和 客户端。​
    注意​
    生产环境中所有 MCP 服务必须开启入站认证。未开启入站认证的 MCP 端点等同于把内部业务 API 暴露到公网，可能被未授权访问，带来越权访问与数据泄露风险。​
    ​​​
    ​
    ​
    ​
    ​
  • 后端配置​
  • ​
    参数​
    说明​
    图示​
    服务类型​
    配置 MCP 服务对接的后端服务（已有 MCP Server）类型。本文操作中已有 MCP Server 部署在腾讯云上且访问方式是私网访问，即通过私网访问后端服务 MCP Server 域名的方式，访问 MCP Server。此处配置为：固定域名。​
    • 函数服务：已有 MCP Server 部署在火山引擎函数服务中。​
    • 容器服务：已有 MCP Server 部署在火山引擎容器服务中。​
    • 固定域名：已有 MCP Server 已在公网暴露，可通过域名直接访问。​
    ​​​
    ​
    ​
    ​
    网络类型​
    选择 MCP 服务的网络访问类型，此处配置为：私网。​
    私网访问场景下，MCP 服务默认使用所属网关实例的入站 VPC 作为私网出口。​
    ​
    域名​
    配置第一个作为后端服务 MCP Server 的 url。无需修改端口号，HTTP 协议端口号默认是 80，HTTPS 协议端口号默认是 443。​
    ​
    出站凭据​
    配置 MCP 服务的出站授权，允许 Agent 使用该凭据访问下游资源，此处配置为：API Key / inspection_api_key，此 API Key 为新添加的 API Key，配置信息为“前提条件”中准备的后端服务 API Key 信息。​
    • 添加 API Key：​
    1. 在 API Key下拉框中，单击底部“添加”按钮。​
    • ​​​
    1. 参考下图配置 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）”类型的访问凭证。​
    ​
    ​
  1. 单击“创建”按钮，完成 MCP Server 对接 AgentKit 的 MCP 服务创建。​
步骤三：配置火山侧私网出口 VPC​
后端服务类型为私网域名时，需额外调用网络侧 API 完成相关私网出口网络配置，服务才能正常通信。​
  1. 单击 此处，在跨服务访问请求页面单击“立即授权”按钮，创建 ServiceRoleForPrivateLink 角色，允许私网连接访问您账号下的其他云服务资源，用于网络打通。​
  • ​​​
  1. 返回 AgentKit 控制台 网关实例页面，单击网关名称 prod_mcp_gateway ，在“配置信息”页签下获取“私有网络”、“子网”、“空间网络服务（SpaceNetwork）”与“出向网络服务（EgressService）” ID 信息。​
  • ​​​
  1. 新增私网出口，配置的 VPC、子网必须是与 AgentKit 网关实例入站配置中的 VPC 和子网严格一致，此处配置等同于 MCP 服务的出站网络配置。​
  • ​​​
  1. 查看空间信息，获取出口 ID（PrivateEgressEndpoint ID）。​
  • ​​​
步骤四：配置私网 DNS 解析​
完成网络互通后，还需要确保专属网关能够解析后端服务的私网域名。​
参考 开启私网出口，配置查到的“出向网络服务（EgressService）”ID，开启私网出口域名解析。本文操作需要把腾讯云 Private DNS 入站 Endpoint 的 IP 地址和端口传入。​
说明​
建议按私网域名后缀维度配置，例如客户后端是 mcp-api.service.internal.example.com，则解析范围应覆盖 service.internal.example.com或实际私有域的根域。​
​
配置项​
推荐填写​
校验方式​
DNS Server IP​
腾讯云入站 Endpoint 的入站服务 IP，如果存在多个 IP，需全部填写。​
从火山 VPC 子网到该 IP 的 53 端口可达。​
DNS Server Port​
53​
说明​
如果云厂商页面展示了自定义端口，以页面实际端口为准。​
安全组和 ACL 同时放通 UDP/TCP 53。​
Domain​
实际待转发的私网域名，避免把全部 DNS 请求都转发到腾讯云。​
此处应该与在 AgentKit 中 MCP 服务填写的后端服务“固定域名”保持一致。此信息可在 MCP 服务基本信息中获取。​
​​​
解析该域名返回腾讯云私网 IP 地址。​
​
步骤五：Agent 代码集成 MCP 工具集并验证​
此处在通过 VeADK 构建的 Agent 中集成 MCP 工具集，目的是在 Agent 代码中连接 AgentKit 网关暴露的 MCP 端点，并携带入站凭证完成工具发现与工具调用。​
  1. 在 MCP 服务 mcp_service_fgajjno5 的“基本信息”页签下，获取 MCP 服务的 URL 信息和入站身份认证 API Key。​
  • ​​​
  1. 在火山引擎 访问控制控制台 “API 访问密钥”下，单击“创建 Access Key”按钮创建 Access Key，创建成功后复制 Access Key ID（AK）和 Secret Access Key（SK）信息。​
  • ​​​
  1. 您本地 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中配置环境变量​
  1. 在创建了 Agent 的虚拟环境中执行命令cd <项目根目录>，进入项目根目录。​
  1. 执行vim .env命令，打开.env文件。​
  1. 按i键进入编辑模式，在.env文件中，填写如下内容添加 MCP 服务配置。​
  • ​
    # MCP服务的地址（URL），支持在工具集调用示例中获取。​
    MCP_SERVICE_URL=<mcp_router_url>​
    # MCP服务的入站 API Key凭证​
    MCP_SERVICE_API_KEY=<mcp_router_api_key>​
    ​
  • ​
    参数​
    来源​
    <mcp_router_url>​
    MCP 服务调用示例中的url。​
    <mcp_router_api_key>​
    MCP 服务调用示例中的Authorization。​
    ​
  1. 按esc键退出编辑模式，输入:wq保存并退出文件。​
步骤五：结果验证​
  1. 本地测试。​
  1. 查询 Agent 可调用的 MCP工具，可看到返回的工具列表与 MCP 服务中爆破的工具及后端 MCP Server 的工具一致。​
  • ​​​
  1. 将本地数据推送到线上。​
  1. 在本地终端执行source .venv/bin/activate命令重新激活 VeADK 虚拟环境。若已在 VeADK 虚拟环境，请跳过本步骤。​
  1. 执行cd <项目根目录>命令，进入 Agent 项目的根目录。​
  1. 执行agentkit launch命令，发布 Agent 到 AgentKit 智能体运行时。​
  1. 在线测试。​
  1. 登录 AgentKit 控制台。在智能体运行时列表中单击目标 Agent 操作列的“在线测试”按钮。​
  1. 输入提示词“你有哪些 MCP 工具”，成功返回企业已有 MCP Server 中的工具。​
  • ​​​
常见问题​
​
问题​
处理方法​
域名解析失败​
通常与转发规则未生效、转发域范围配置不匹配、DNS 入站 Endpoint 不可达、或 53 端口未放通有关。建议按「DNS 可达性 → 转发规则命中 → 权威 DNS 记录」的顺序排查。​
域名可解析但服务不可达​
说明 DNS 配置已生效，但网络链路或安全策略仍存在问题。建议检查路由表、业务端口放通、后端监听地址与安全组规则。​
​
​
最近更新时间：2026.10.29 11:43:27
这个页面对您有帮助吗？
有用
有用
无用
无用