文档首页/ 智能体开发平台 AgentArts/ 高代码开发/ AgentRuntime SDK参考/ MCP Gateway SDK
更新时间：2026-04-15 GMT+08:00
查看PDF
分享

MCP Gateway SDK

场景介绍

MCP Gateway CLI提供管理MCP网关及相关操作的命令行工具，支持网关和网关目标的创建、查询、更新、删除等功能。

AgentRunSDK Gateway SDK提供两种使用模式：

  • client模式：与MCP Gateway API交互的客户端。
  • cli模式：通过命令行进行生命周期管理。

Client模式

  • 创建MCP Gateway 
    def create_mcp_gateway(
    self,
    name: Optional[str] = None,
    description: Optional[str] = None,
    protocol_type: Optional[str] = "MCP",
    authorizer_type: Optional[str] = "IAM",
    agency_name: Optional[str] = None,
    authorizer_configuration: Optional[CoreGatewayAuthorizerConfiguration] = None,
    log_delivery_configuration: Optional[CoreGatewayLogDeliveryConfigurationRequestBody] = None,
    outbound_network_configuration: Optional[CoreGatewayOutboundNetworkConfiguration] = None,
) -> RequestResult
    表1 创建MCP Gateway参数说明

    参数

    类型

    是否必选

    默认值

    说明

    name

    Optional[str]

    否

    gateway-{8个随机字符后缀}

    网关名称

    description

    Optional[str]

    否

    -

    网关的详细描述

    protocol_type

    Optional[str]

    否

    MCP

    网关协议类型

    authorizer_type

    Optional[str]

    否

    IAM

    授权器类型，可选值：custom_jwt、iam、api_key

    agency_name

    Optional[str]

    否

    AgentArksCoreGateway

    网关委托身份的委托名称

    authorizer_configuration

    Optional[CoreGatewayAuthorizerConfiguration]

    否

    -

    授权器配置

    log_delivery_configuration

    Optional[CoreGatewayLogDeliveryConfigurationRequestBody]

    否

    -

    日志投递配置

    outbound_network_configuration

    Optional[CoreGatewayOutboundNetworkConfiguration]

    否

    -

    出站网络配置

    授权器配置要求：

    • 当authorizer_type = 'custom_jwt' 时，必须提供custom_jwt_authorizer配置。
    • 当authorizer_type = 'api_key' 时，必须提供key_auth配置。
  • 查询MCP Gateway信息 
    def get_mcp_gateway(self, gateway_id: str) -> ShowCoreGatewayResponse
    表2 查询MCP Gateway参数说明

    参数

    类型

    是否必选

    说明

    gateway_id

    str

    是

    要查询的Gateway的唯一标识符
  • 更新指定的MCP Gateway信息 
    def update_mcp_gateway(
    self,
    gateway_id: str,
    description: Optional[str] = None,
    authorizer_configuration: Optional[CoreGatewayAuthorizerConfiguration] = None,
    log_delivery_configuration: Optional[CoreGatewayLogDeliveryConfigurationRequestBody] = None,
) -> RequestResult
    表3 更新MCP Gateway参数说明

    参数

    类型

    是否必选

    说明

    gateway_id

    str

    是

    要更新的Gateway的唯一标识符

    description

    Optional[str]

    否

    网关的详细描述

    authorizer_configuration

    Optional[CoreGatewayAuthorizerConfiguration]

    否

    授权器配置

    log_delivery_configuration

    Optional[CoreGatewayLogDeliveryConfigurationRequestBody]

    否

    日志投递配置

    更新操作为增量更新，只传入需要更新的字段，未传入的字段将保持原值不变。

  • 删除指定的MCP Gateway信息 
    def delete_mcp_gateway(self, gateway_id: str) -> DeleteCoreGatewayResponse
    表4 更新MCP Gateway参数说明

    参数

    类型

    是否必选

    说明

    gateway_id

    str

    是

    要删除的Gateway的唯一标识符
  • 获取MCP Gateway列表 
    def list_mcp_gateways(
    self,
    name: Optional[str] = None,
    status: Optional[str] = None,
    gateway_id: Optional[str] = None,
        limit: Optional[int] = None,
    offset: Optional[int] = None) -> ListCoreGatewaysResponse
    表5 获取MCP Gateway实例列表参数说明

    参数

    类型

    是否必选

    默认值

    说明

    name

    Optional[str]

    否

    -

    按名称过滤网关，支持模糊匹配

    status

    Optional[str]

    否

    -

    按状态过滤网关

    gateway_id

    Optional[str]

    否

    -

    按网关ID过滤，支持多个ID（最多20个），用逗号分隔

    limit

    Optional[int]

    否

    50

    返回结果的最大数量

    offset

    Optional[int]

    否

    0

    返回结果的偏移量
  • 在指定的MCP Gateway下创建新的Target实例 
    def create_mcp_gateway_target(
    self,
    gateway_id: str,
    name: Optional[str] = None,
    description: Optional[str] = None,
    target_configuration: Optional[CoreGatewayTargetConfiguration] = None,
    credential_provider_configuration: Optional[CoreGatewayCredentialProviderConfiguration] = None) -> CreateCoreGatewayTargetResponse
    表6 创建MCP Target参数说明

    参数

    类型

    是否必选

    默认值

    说明

    gateway_id

    str

    是

    -

    目标Gateway的唯一标识符

    name

    Optional[str]

    否

    target-{8个随机字符后缀}

    Target服务名称

    description

    Optional[str]

    否

    -

    Target服务描述

    target_configuration

    Optional[CoreGatewayTargetConfiguration]

    否

    -

    Target服务配置，mcp_server内容必须提供

    credential_provider_configuration

    Optional[CoreGatewayCredentialProviderConfiguration]

    否

    -

    凭证提供者配置

    凭证提供者配置要求：

    • 如果不提供，credential_provider_type默认为none，表示无认证。
    • 当credential_provider_type='oauth' 时，必须提供oauth_credential_provider。
    • 当credential_provider_type='api_key' 时，必须提供api_key_credential_provider。
  • 查询指定Gateway下的特定Target实例的详细信息 
    def get_mcp_gateway_target(self, gateway_id: str, target_id: str) -> ShowCoreGatewayTargetResponse
    表7 查询MCP Target信息参数说明

    参数

    类型

    是否必选

    说明

    gateway_id

    str

    是

    Target所属Gateway的唯一标识符

    target_id

    str

    是

    要查询的Target的唯一标识符
  • 更新指定Gateway下的特定Target实例 
    def update_mcp_gateway_target(
    self,
    gateway_id: str,
    target_id: str,
    name: Optional[str] = None,
    description: Optional[str] = None,
    target_configuration: Optional[CoreGatewayTargetConfiguration] = None,
    credential_provider_configuration: Optional[CoreGatewayCredentialProviderConfiguration] = None) -> UpdateCoreGatewayTargetResponse
    表8 更新MCP Target参数信息

    参数

    类型

    是否必选

    说明

    gateway_id

    str

    是

    Target所属Gateway的唯一标识符

    target_id

    str

    是

    要更新的Target的唯一标识符

    name

    Optional[str]

    否

    Target服务名称

    description

    Optional[str]

    否

    Target服务描述

    target_configuration

    Optional[CoreGatewayTargetConfiguration]

    否

    Target服务配置

    credential_provider_configuration

    Optional[CoreGatewayCredentialProviderConfiguration]

    否

    凭证提供者配置
  • 删除指定Gateway下的特定Target实例 
    def delete_mcp_gateway_target(self, gateway_id: str, target_id: str) -> DeleteCoreGatewayTargetResponse
    表9 删除MCP Target参数说明

    参数

    类型

    是否必选

    说明

    gateway_id

    str

    是

    Target所属Gateway的唯一标识符

    target_id

    str

    是

    要删除的Target的唯一标识符
  • 查询指定Gateway下的所有Target列表 
    def list_mcp_gateway_targets(
    self,
    gateway_id: str,
    limit: Optional[int] = None,
    offset: Optional[int] = None) -> ListCoreGatewayTargetsResponse
    表10 查询指定Gateway下的Target列表参数说明

    参数

    类型

    是否必选

    默认值

    说明

    gateway_id

    str

    是

    -

    要查询Targets的Gateway的唯一标识符

    limit

    Optional[int]

    否

    50

    每页返回的最大结果数量

    offset

    Optional[int]

    否

    0

    返回结果的偏移量

CLI模式操作

  • 创建MCP Gateway 
    agentarts mcp-gateway create-mcp-gateway
    表11 创建MCP Gateway参数说明

    参数

    类型

    是否必选

    默认值

    说明

    --name

    string

    否

    gateway-{8位随机后缀}

    网关名称

    --description

    string

    否

    -

    网关描述

    --protocol-type

    string

    否

    MCP

    网关协议类型

    --agency-name

    string

    否

    -

    用于指定网关委托身份的委托名称

    --authorizer-type

    string

    否

    iam

    授权器类型（custom_jwt、iam、api_key）

    --authorizer-configuration

    JSON string

    否

    -

    授权器配置的JSON字符串

    --log-delivery-configuration

    JSON string

    否

    -

    日志投递配置的JSON字符串

    --outbound-network-configuration

    JSON string

    否

    -

    网络配置的JSON字符串

    授权器配置要求：

    • 当authorizer-type = 'custom_jwt' 时，必须提供custom_jwt_authorizer配置。
    • 当authorizer-type = 'api_key' 时，必须提供key_auth配置。

    示例：

    agentarts mcp-gateway create-mcp-gateway --name "my-gateway"   --description "测试网关"
  • 获取指定的MCP Gateway详情 
    agentarts mcp-gateway create-mcp-gateway
    表12 获取MCP Gateway详情参数说明

    参数

    类型

    是否必选

    说明

    <gateway-id>

    string

    否

    网关ID

    响应信息包含：

    • gateway_id：网关唯一标识符
    • name：网关名称
    • description：网关详细描述
    • status：网关当前状态
    • protocol_type：网关协议类型（MCP）
    • authorizer_type：授权器类型
    • agency_name：委托名称
    • authorizer_configuration：授权器配置
    • endpoint_url：网关访问的URL端点
    • log_delivery_configuration：日志投递配置
    • workload_identity：工作负载身份标识符
    • outbound_network_configuration：出站网络配置
    • created_at：网关创建时间戳
    • updated_at：网关最后更新时间戳
  • 更新指定的MCP Gateway实例 
    agentarts mcp-gateway update-mcp-gateway <gateway-id> [参数]
    表13 更新MCP网关参数说明

    参数

    类型

    是否必选

    说明

    <gateway-id>

    string

    是

    网关ID

    --description

    string

    否

    网关描述

    --authorizer-configuration

    JSON string

    否

    授权器配置的JSON字符串

    --log-delivery-configuration

    JSON string

    否

    日志投递配置的JSON字符串

    --outbound-network-configuration

    JSON string

    否

    网络配置的JSON字符串

    授权器配置要求：

    • 当authorizer-type = 'custom_jwt' 时，必须提供custom_jwt_authorizer配置
    • 当authorizer-type = 'api_key' 时，必须提供key_auth配置

    更新操作为增量更新，只传入需要更新的字段，未传入的字段将保持原值不变。

    示例：

    agentarts mcp-gateway update-mcp-gateway "gateway-123"  --description "更新后的描述"
  • 删除指定的MCP Gateway实例 
    agentarts mcp-gateway delete-mcp-gateway <gateway-id>
    表14 更新MCP网关参数说明

    参数

    类型

    是否必选

    说明

    <gateway-id>

    string

    是

    网关ID

    响应信息包含删除操作的状态和相关操作日志信息。

  • 获取MCP Gateway实例列表 
    # 列出所有网关
agentarts mcp-gateway list-mcp-gateways

# 按条件过滤
agentarts mcp-gateway list-mcp-gateways [参数]
    表15 列出MCP网关参数说明

    参数

    类型

    是否必选

    默认值

    说明

    --name

    string

    否

    -

    按名称过滤网关，支持模糊匹配

    --status

    string

    否

    -

    按状态过滤网关（如 "active"、"inactive"）

    --gateway-id

    string

    否

    -

    按网关ID过滤，支持多个ID（最多20个），用逗号分隔

    --tags

    string

    否

    -

    按标签过滤网关，支持多个标签，用逗号分隔

    --offset

    integer

    否

    0

    分页偏移量，最小 0，最大 100000

    --limit

    integer

    否

    50

    每页大小，最小 1，最大 100
  • 在指定的MCP Gateway下创建新的Target实例 
    agentarts mcp-gateway create-mcp-gateway-target <gateway-id> [参数]
    表16 创建MCP网关目标参数说明

    参数

    类型

    是否必选

    默认值

    说明

    <gateway-id>

    string

    是

    -

    网关ID

    --name

    string

    否

    		 
    target-{8位随机后缀}

    目标名称

    --description

    string

    否

    -

    目标描述

    --target-configuration

    JSON string

    否

    -

    目标服务的配置JSON字符串

    --credential-provider-configuration

    JSON string

    否

    -

    凭证提供者配置的JSON字符串

    凭证提供者配置要求：

    • 如果未提供，credential_provider_type默认为GATEWAY_IAM_ROLE，表示使用网关IAM角色。
    • 当credential_provider_type='none' 时，表示无认证。
    • 当credential_provider_type='oauth' 时，表示使用OAuth 2.0，必须提供oauth_credential_provider。
    • 当credential_provider_type='api_key' 时，表示使用API密钥，必须提供api_key_credential_provider。

    示例：

    agentarts mcp-gateway create-mcp-gateway-target "gateway-123" \     --target-configuration '{"mcp_server": {"command": "npx -y @modelcontextprotocol/server-examples echo", "env": {"VARIABLE": "value"}}}'
  • 获取MCP网关目标详情 
    agentarts mcp-gateway get-mcp-gateway-target <gateway-id> <target-id>

    功能说明：此命令用于获取指定网关下特定目标的详细信息，包括目标名称、描述、状态、端点、超时时间等所有相关配置信息。如果目标不存在，系统会返回错误提示。

    表17 获取MCP网关目标详情参数说明

    参数

    类型

    是否必选

    默认值

    说明

    <gateway-id>

    string

    是

    网关ID

    按名称过滤网关，支持模糊匹配

    <target-id>

    string

    是

    目标ID

    按状态过滤网关（如 "active"、"inactive"）
  • 更新指定Gateway下的特定Target实例 
    agentarts mcp-gateway update-mcp-gateway-target <gateway-id> <target-id> [参数]
    表18 更新MCP网关目标参数说明

    参数

    类型

    是否必选

    说明

    <gateway-id>

    string

    是

    网关ID

    <target-id>

    string

    是

    目标ID

    --name

    string

    否

    目标名称

    --description

    string

    否

    目标描述

    --target-configuration

    JSON string

    否

    目标服务的配置JSON字符串

    --credential-provider-configuration

    JSON string

    否

    凭证提供者配置的JSON字符串

    示例：

    agentarts mcp-gateway update-mcp-gateway-target "gateway-123" "target-456" \     --description "更新后的目标描述"
  • 删除指定Gateway下的特定Target实例 
    agentarts mcp-gateway delete-mcp-gateway-target <gateway-id> <target-id>
    表19 删除MCP网关目标参数说明

    参数

    类型

    是否必选

    说明

    <gateway-id>

    string

    是

    网关ID

    <target-id>

    string

    是

    目标ID
  • 查询指定Gateway下的所有Target实例列表 
    agentarts mcp-gateway list-mcp-gateway-targets <gateway-id> [参数]
    表20 列出MCP网关目标参数说明

    参数

    类型

    是否必选

    默认值

    说明

    <gateway-id>

    string

    是

    -

    网关ID

    --offset

    integer

    否

    0

    分页偏移量，最小 0，最大 100000

    --limit

    integer

    否

    50

    每页大小，最小 1，最大 100

前提条件

  • 已开通AgentArts。
  • 登录控制台获取AK/SK，详情请参考认证鉴权。
  • 已安装Python，且版本不低于3.10。查看Python版本的命令示例： 
    python --version

快速入门

  1. 创建网关。 

    # Client模式
gateway = client.create_mcp_gateway(
    name="my-gateway",
    description="我的第一个MCP网关"
)
gateway_id = gateway.gateway_id


# CLI模式
agentarts mcp-gateway create-mcp-gateway --name "my-gateway" --description "我的第一个MCP网关"

  2. 创建目标。 

    # Client模式
target = client.create_mcp_gateway_target(
    gateway_id=gateway_id,
    target_configuration={
        "mcp_server": {
            "command": "npx -y @modelcontextprotocol/server-examples echo"
        }
    }
)


# CLI模式
agentarts mcp-gateway create-mcp-gateway-target "$gateway_id" \
    --target-configuration '{"mcp_server": {"command": "npx -y @modelcontextprotocol/server-examples echo"}}'

  3. 查询信息。 

    # Client模式
gateway_info = client.get_mcp_gateway(gateway_id)
target_info = client.get_mcp_gateway_target(gateway_id, target.target_id)


# CLI模式
agentarts mcp-gateway get-mcp-gateway "$gateway_id"
agentarts mcp-gateway get-mcp-gateway-target "$gateway_id" "$target_id"

参数说明

  • 请求参数
    表21 创建MCP Gateway参数

    参数

    类型

    说明

    name

    String

    网关名称，如果不提供则默认为gateway-{8个随机字符后缀}

    description

    String

    网关的详细描述

    protocol_type

    String

    协议类型，默认为 "MCP"

    authorizer_type

    String

    授权器类型，可选值：custom_jwt、iam、api_key

    agency_name

    String

    委托名称，默认为 "AgentArksCoreGateway"

    authorizer_configuration

    Object

    授权器配置对象

    log_delivery_configuration

    Object

    日志投递配置对象

    outbound_network_configuration

    Object

    出站网络配置对象
    表22 Target配置对象

    参数

    类型

    说明

    mcp_server

    Object

    MCP服务器配置

    mcp_server.command

    String

    启动命令

    mcp_server.env

    Object

    环境变量
    表23 凭证提供者配置对象

    参数

    类型

    说明

    credential_provider_type

    String

    凭证提供者类型

    credential_provider

    Object

    凭证提供者配置
  • 响应参数
    表24 CreateCoreGatewayResponse

    字段

    类型

    说明

    gateway_id

    String

    网关的唯一标识符

    name

    String

    网关名称

    description

    String

    网关的详细描述

    status

    String

    网关当前状态

    protocol_type

    String

    网关协议类型

    authorizer_type

    String

    授权器类型

    authorizer_configuration

    Object

    授权器配置

    endpoint_url

    String

    网关访问的URL端点

    log_delivery_configuration

    Object

    日志投递配置

    workload_identity

    Object

    工作负载身份标识符

    outbound_network_configuration

    Object

    网络配置

    agency_name

    String

    网关委托名称

    created_at

    String

    网关创建时间戳

    updated_at

    String

    网关最后更新时间戳
    表25 ListCoreGatewaysResponse

    字段

    类型

    说明

    gateways

    List[ShowCoreGatewayResponse]

    网关详情列表

    size

    Integer

    当前页返回的网关数量

    total

    Integer

    网关总数量
    表26 ShowCoreGatewayTargetResponse

    字段

    类型

    说明

    target_id

    String

    目标唯一标识符

    name

    String

    目标名称

    description

    String

    目标描述

    status

    String

    目标状态

    connection_status

    String

    连接状态

    target_configuration

    Object

    目标配置

    credential_provider_configuration

    Object

    凭证提供者配置

    created_at

    String

    创建时间戳

    updated_at

    String

    更新时间戳

示例代码

from typing import Optional, List
from agentarts.sdk.mcpgateway import MCPGatewayClient


# 初始化客户端
client = MCPGatewayClient()


# 创建MCP Gateway
gateway = client.create_mcp_gateway(
    name="production-echo-gateway",
    description="生产环境 Echo 服务网关",
    authorizer_type="IAM",
    )
print(f"创建的网关ID: {gateway.gateway_id}")
print(f"端点URL: {gateway.endpoint_url}")


# 更新网关描述
updated_target = client.update_mcp_gateway(
    gateway_id=gateway.gateway_id,
    description="更新后的网关描述"
)
print(f"更新后的描述: {updated_target.description}")




# 在网关下创建Target（MCP服务器类型）
target = client.create_mcp_gateway_target(
    gateway_id=gateway.gateway_id,
    name="echo-service-target",
    description="Echo服务目标",
    target_configuration={
        "mcp_server": {
            "endpoint": "https://echo.example.com",
            "server_type": "sse"
        }
    }
)


# 在网关下创建Target（OpenAPI内联文档类型）
target_openapi = client.create_mcp_gateway_target(
    gateway_id=gateway.gateway_id,
    name="petstore-api",
    description="PetStore API目标",
    target_configuration={
        "openapi": {
            "payload": """
openapi: 3.0.0
info:
  title: PetStore API
  version: 1.0.0
servers:
  - url: https://petstore.example.com
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A paged array of pets
"""
        }
    }
)


# 在网关下创建Target（OpenAPI OBS文档类型）
target_openapi_obs = client.create_mcp_gateway_target(
    gateway_id=gateway.gateway_id,
    name="petstore-api-obs",
    description="PetStore API目标（OBS）",
    target_configuration={
        "openapi": {
            "obs": {
                "bucket_name": "api-specs-bucket",
                "object_key": "specs/petstore.yaml"
            }
        }
    }
)
print(f"创建的目标ID: {target.target_id}")


# 查询网关信息
gateway_info = client.get_mcp_gateway(gateway.gateway_id)
print(f"网关状态: {gateway_info.status}")


# 查询目标信息
target_info = client.get_mcp_gateway_target(gateway.gateway_id, target.target_id)
print(f"目标状态: {target_info.status}")


# 列出网关下的所有目标
targets = client.list_mcp_gateway_targets(gateway.gateway_id)
print(f"网关下有 {targets.total} 个目标")


# 更新Target描述
updated_target = client.update_mcp_gateway_target(
    gateway_id=gateway.gateway_id,
    target_id=target.target_id,
    description="更新后的Echo服务目标描述"
)
print(f"更新后的描述: {updated_target.description}")


# 删除Target
client.delete_mcp_gateway_target(gateway.gateway_id, target.target_id)
print("目标已删除")


# 删除Gateway
client.delete_mcp_gateway(gateway.gateway_id)
print("网关已删除")
父主题： AgentRuntime SDK参考

相关文档