InstallMcpMarketItem - 安装 MCP 市场模板

更新时间:
复制 MD 格式

安装 MCP 市场模板

接口说明

按指定模板版本校验输入,并在工作空间创建 MCP。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。

  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。

  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:

    • 对于必选的资源类型,用前面加 * 表示。

    • 对于不支持资源级授权的操作,用全部资源表示。

  • 条件关键字:是指云产品自身定义的条件关键字。

  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

agentcore:InstallMcpMarketItem

create

*Mcp

acs:agentcore:{#regionId}:{#accountId}:workspace/{#workspaceId}/mcp/*

无 无

请求语法

POST /workspaces/{workspaceId}/mcp-market/items/{marketItemId}/install HTTP/1.1

路径参数

名称

类型

必填

描述

示例值

workspaceId

string

是

AgentCore 工作空间 ID。

workspace-id

marketItemId

string

是

MCP 市场模板 ID。

market-1

请求参数

名称

类型

必填

描述

示例值

templateVersion

string

是

安装的模板版本,可通过 GetMcpMarketItem 查询。

1.0.0

body

object

否

安装模板时提交的 MCP 配置,需符合模板的输入 Schema。

addresses

array

否

远程 MCP 服务地址列表。

string

否

单个远程 MCP 服务地址。

https://example.com/mcp

auth

object

否

MCP 认证配置。

directProxy

object

否

直连代理的后端认证配置。

name

string

否

后端认证请求头名称。

Authorization

value

string

否

后端认证请求头的值。

example-api-key

enabled

boolean

否

是否启用该配置。

httpToMcp

array<object>

否

HTTP 转 MCP 的后端认证配置列表。

object

否

credential

string

否

后端认证凭据。

example-api-key

id

string

否

后端认证配置 ID。

api-key-auth

name

string

否

API Key 参数名称。

X-API-Key

position

string

否

API Key 的传递位置。

header

type

string

否

后端认证类型。

apiKey

customTags

array

否

自定义标签,支持多个;与模板固定标签合并去重。

string

否

单个 MCP 自定义标签。

知识库

deploymentConfig

object

否

代码部署 MCP 的部署配置。

accessControl

object

否

MCP 入口访问控制

credentialId

string

否

mode 为 CREDENTIAL 时引用 AgentCore Credential

credential-id

enabled

boolean

否

是否启用入口访问控制

mode

string

否

ANONYMOUS 表示匿名访问,CREDENTIAL 表示使用 AgentCore 访问凭证

CREDENTIAL

agentIdentityConfiguration

object

否

Agent Identity 配置

authorizationEnabled

boolean

否

是否启用授权

credentialProviderArn

string

否

凭证提供者 ARN

acs:agentidentity:cn-hangzhou:1234567890123456:provider/example

credentialProviderType

string

否

凭证提供者类型

oauth2

enabled

boolean

否

是否启用 Agent Identity

artifactType

string

否

Code 表示 ZIP 代码包,Container 表示自定义容器

Code

codeConfiguration

object

否

代码包配置

codePackageToken

string

否

GetMcpCodePackageUploadUrl 返回的临时代码包令牌;完成预签名上传后用于创建代码部署。与 CodePackageUrl 二选一

upload-token

codePackageUrl

string

否

创建代码部署时可直接传入的公网阿里云 OSS HTTP(S) 地址。与 CodePackageToken 二选一;仅 CreateMcp 支持,更新和查询不支持

https://example-bucket.oss-cn-hangzhou.aliyuncs.com/server.zip

command

array

否

完整启动命令,按参数边界依次传入。例如使用 supergateway 启动 stdio MCP 时传入 supergateway、--stdio、完整子命令和其余参数

string

否

启动命令或单个命令参数。

python

language

string

否

代码包运行时:python3.13、nodejs22 或 java17

python3.13

containerConfiguration

object

否

自定义容器配置

acrInstanceId

string

否

ACR 实例 ID

cri-example

command

array

否

启动命令

string

否

启动命令或单个命令参数。

python

entrypoint

array

否

容器入口参数

string

否

单个容器入口参数。

/bin/sh

image

string

否

容器镜像地址

registry.cn-hangzhou.aliyuncs.com/example/mcp:1.0.0

imageRegistryType

string

否

镜像仓库类型

ACR

mcpRuntimeMode

string

否

自定义容器当前需自行暴露标准 MCP,取值为 SELF_HOSTED

SELF_HOSTED

sourceType

string

否

当前固定为 CONTAINER_IMAGE

CONTAINER_IMAGE

hookConfiguration

object

否

Hook 配置

hooks

array<object>

否

按数组顺序执行 PRE_LIST_TOOLS、PRE_CALL_TOOL、POST_LIST_TOOLS 和 POST_CALL_TOOL Hook

array<object>

否

apiVersion

string

否

Hook API 版本

1.0

description

string

否

Hook 描述

记录 MCP 工具调用

enabled

boolean

否

是否启用 Hook

event

string

否

Hook 事件

PRE_CALL_TOOL

headers

object

否

Hook 请求头

string

否

HTTP 请求头的值。

application/json

timeout

integer

否

单位为毫秒

3000

url

string

否

Hook 回调地址

https://example.com/mcp-hook

logConfiguration

object

否

日志配置

enableInstanceMetrics

boolean

否

是否采集实例指标

enableRequestMetrics

boolean

否

是否采集请求指标

logBeginRule

string

否

FC 日志切分起始规则

DefaultRegex

logstore

string

否

日志库名称

mcp-logs

project

string

否

日志服务项目名称

agentcore-mcp-logs

mcpConfiguration

object

否

MCP 会话配置

endpointPath

string

否

例如 /mcp 或 /sse

/mcp

sessionConcurrencyPerInstance

integer

否

当前固定为 1

1

sessionIdleTimeoutSeconds

integer

否

单位为秒,默认 1800

1800

sessionMaxLifetimeSeconds

integer

否

单位为秒,默认 21600

21600

nasConfiguration

object

否

NAS 存储配置

groupId

integer

否

运行用户组 ID

1000

mountPoints

array<object>

否

NAS 挂载点列表

object

否

enableTls

boolean

否

是否启用 TLS

mountDir

string

否

本地挂载目录

/mnt/data

serverAddr

string

否

NAS 服务地址

example.cn-hangzhou.nas.aliyuncs.com

userId

integer

否

运行用户 ID

1000

networkConfiguration

object

否

网络配置

networkMode

string

否

网络模式

PUBLIC

securityGroupId

string

否

安全组 ID

sg-example

vSwitchIds

array

否

交换机 ID 列表

string

否

单个交换机 ID。

vsw-example

vpcId

string

否

专有网络 VPC ID

vpc-example

ossMountConfiguration

object

否

OSS 挂载配置

mountPoints

array<object>

否

OSS 挂载点列表

object

否

bucketName

string

否

OSS Bucket 名称

example-bucket

bucketPath

string

否

OSS Bucket 路径

/data

endpoint

string

否

OSS 服务访问端点

https://oss-cn-hangzhou.aliyuncs.com

mountDir

string

否

本地挂载目录

/mnt/data

readOnly

boolean

否

是否只读

parameterTransformConfiguration

object

否

参数转换和结果增强配置

enabled

boolean

否

是否启用参数转换和结果增强

ruleSetId

string

否

预留的参数转换和结果增强规则集引用

rules-1

version

string

否

转换规则版本

1.0

proxyConfiguration

object

否

MCP 代理配置

enabled

boolean

否

是否启用 MCP 代理

runtimeConfiguration

object

否

运行时和资源配置

cpu

number

否

单位为核,默认 0.25

0.25

diskSize

integer

否

单位为 MB,支持 512 或 10240

512

environmentVariables

object

否

环境变量

string

否

环境变量的值。

production

executionRoleArn

string

否

用户代码访问下游阿里云资源时使用的 RAM 角色 ARN

acs:ram::1234567890123456:role/agentcore-mcp-execution

instanceConcurrency

integer

否

默认 200

200

memory

integer

否

单位为 MB,默认 512

512

port

integer

否

默认 9000

9000

timeout

integer

否

单位为秒,默认 300

300

description

string

否

MCP 服务描述。

用于查询知识库的 MCP 服务

name

string

否

MCP 服务名称。

my-mcp-server

protocol

string

否

MCP 协议。

StreamableHTTP

swaggerConfig

string

否

HTTP 转 MCP 使用的 OpenAPI 配置,采用 JSON 字符串表示。

{"openapi":"3.0.3","info":{"title":"Knowledge API","version":"1.0.0"},"paths":{}}

type

string

否

MCP 类型:DIRECT_PROXY(直连代理)、HTTP_TO_MCP(HTTP 转 MCP)或 CODE_PACKAGE(代码部署)。

CODE_PACKAGE

clientToken

string

否

保证请求幂等性的客户端令牌。

123e4567-e89b-12d3-a456-426655440000

返回参数

名称

类型

描述

示例值

object

code

string

业务状态码。

SUCCESS

data

object

返回结果。

addresses

array

远程 MCP 服务地址列表。

string

单个远程 MCP 服务地址。

https://example.com/mcp

customTags

array

自定义标签,支持多个

string

单个 MCP 自定义标签。

知识库

deploymentConfig

object

代码部署 MCP 的部署配置。

accessControl

object

MCP 入口访问控制

credentialId

string

mode 为 CREDENTIAL 时引用 AgentCore Credential

credential-id

enabled

boolean

是否启用入口访问控制

mode

string

ANONYMOUS 表示匿名访问,CREDENTIAL 表示使用 AgentCore 访问凭证

CREDENTIAL

agentIdentityConfiguration

object

Agent Identity 配置

authorizationEnabled

boolean

是否启用授权

credentialProviderArn

string

凭证提供者 ARN

acs:agentidentity:cn-hangzhou:1234567890123456:provider/example

credentialProviderType

string

凭证提供者类型

oauth2

enabled

boolean

是否启用 Agent Identity

artifactType

string

Code 表示 ZIP 代码包,Container 表示自定义容器

Code

codeConfiguration

object

代码包配置

codePackageToken

string

GetMcpCodePackageUploadUrl 返回的临时代码包令牌;完成预签名上传后用于创建或更新代码部署

upload-token

command

array

完整启动命令,按参数边界依次传入。例如使用 supergateway 启动 stdio MCP 时传入 supergateway、--stdio、完整子命令和其余参数

string

启动命令或单个命令参数。

python

language

string

代码包运行时:python3.13、nodejs22 或 java17

python3.13

containerConfiguration

object

自定义容器配置

acrInstanceId

string

ACR 实例 ID

cri-example

command

array

启动命令

string

启动命令或单个命令参数。

python

entrypoint

array

容器入口参数

string

单个容器入口参数。

/bin/sh

image

string

容器镜像地址

registry.cn-hangzhou.aliyuncs.com/example/mcp:1.0.0

imageRegistryType

string

镜像仓库类型

ACR

mcpRuntimeMode

string

自定义容器当前需自行暴露标准 MCP,取值为 SELF_HOSTED

SELF_HOSTED

sourceType

string

当前固定为 CONTAINER_IMAGE

CONTAINER_IMAGE

hookConfiguration

object

Hook 配置

hooks

array<object>

按数组顺序执行 PRE_LIST_TOOLS、PRE_CALL_TOOL、POST_LIST_TOOLS 和 POST_CALL_TOOL Hook

array<object>

apiVersion

string

Hook API 版本

1.0

description

string

Hook 描述

记录 MCP 工具调用

enabled

boolean

是否启用 Hook

event

string

Hook 事件

PRE_CALL_TOOL

headers

object

Hook 请求头

string

HTTP 请求头的值。

application/json

timeout

integer

单位为毫秒

3000

url

string

Hook 回调地址

https://example.com/mcp-hook

logConfiguration

object

日志配置

enableInstanceMetrics

boolean

是否采集实例指标

enableRequestMetrics

boolean

是否采集请求指标

logBeginRule

string

FC 日志切分起始规则

DefaultRegex

logstore

string

日志库名称

mcp-logs

project

string

日志服务项目名称

agentcore-mcp-logs

mcpConfiguration

object

MCP 会话配置

endpointPath

string

例如 /mcp 或 /sse

/mcp

sessionConcurrencyPerInstance

integer

当前固定为 1

1

sessionIdleTimeoutSeconds

integer

单位为秒,默认 1800

1800

sessionMaxLifetimeSeconds

integer

单位为秒,默认 21600

21600

nasConfiguration

object

NAS 存储配置

groupId

integer

运行用户组 ID

1000

mountPoints

array<object>

NAS 挂载点列表

object

enableTls

boolean

是否启用 TLS

mountDir

string

本地挂载目录

/mnt/data

serverAddr

string

NAS 服务地址

example.cn-hangzhou.nas.aliyuncs.com

userId

integer

运行用户 ID

1000

networkConfiguration

object

网络配置

networkMode

string

网络模式

PUBLIC

securityGroupId

string

安全组 ID

sg-example

vSwitchIds

array

交换机 ID 列表

string

单个交换机 ID。

vsw-example

vpcId

string

专有网络 VPC ID

vpc-example

ossMountConfiguration

object

OSS 挂载配置

mountPoints

array<object>

OSS 挂载点列表

object

bucketName

string

OSS Bucket 名称

example-bucket

bucketPath

string

OSS Bucket 路径

/data

endpoint

string

OSS 服务访问端点

https://oss-cn-hangzhou.aliyuncs.com

mountDir

string

本地挂载目录

/mnt/data

readOnly

boolean

是否只读

parameterTransformConfiguration

object

参数转换和结果增强配置

enabled

boolean

是否启用参数转换和结果增强

ruleSetId

string

预留的参数转换和结果增强规则集引用

rules-1

version

string

转换规则版本

1.0

proxyConfiguration

object

MCP 代理配置

enabled

boolean

是否启用 MCP 代理

runtimeConfiguration

object

运行时和资源配置

cpu

number

单位为核,默认 0.25

0.25

diskSize

integer

单位为 MB,支持 512 或 10240

512

environmentVariables

object

环境变量

string

环境变量的值。

production

executionRoleArn

string

用户代码访问下游阿里云资源时使用的 RAM 角色 ARN

acs:ram::1234567890123456:role/agentcore-mcp-execution

instanceConcurrency

integer

默认 200

200

memory

integer

单位为 MB,默认 512

512

port

integer

默认 9000

9000

timeout

integer

单位为秒,默认 300

300

description

string

MCP 服务描述。

用于查询知识库的 MCP 服务

endpoint

string

MCP 服务访问端点。

https://example.com/mcp

functionName

string

代码部署 MCP 对应的函数计算函数名称。

agentcore-mcp-example

marketSource

object

MCP 来源市场模板。

marketItemId

string

MCP 市场模板 ID。

market-1

mcpServerId

string

MCP 服务 ID。

mcp-server-id

name

string

MCP 服务名称。

my-mcp-server

officialTag

string

官方用途标签,由服务端管理

KNOWLEDGE_BASE

protocol

string

MCP 协议。

StreamableHTTP

status

string

MCP 服务状态。

READY

statusReason

string

MCP 服务处于当前状态的原因。

代码包部署失败

template

object

MCP 绑定的模板版本及输入 Schema。

appliedTemplateVersion

string

当前 MCP 已应用的模板版本。

1.0.0

latestTemplateVersion

string

最新模板版本。

1.1.0

schemaVersion

string

模板 Schema 版本。

1.0

templateInputSchema

string

模板输入 Schema,采用 JSON Schema 字符串表示。

{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"string"}}}}

updateAvailable

boolean

是否有可更新的模板版本。

type

string

MCP 类型:DIRECT_PROXY(直连代理)、HTTP_TO_MCP(HTTP 转 MCP)或 CODE_PACKAGE(代码部署)。

CODE_PACKAGE

usageActive

boolean

MCP 是否仍受官方模板的用途约束。

httpStatusCode

integer

HTTP 状态码。

200

message

string

响应消息。

success

requestId

string

请求 ID,用于定位和排查请求。

request-123456

success

boolean

请求是否成功。

示例

正常返回示例

JSON格式

{
  "code": "SUCCESS",
  "data": {
    "addresses": [
      "https://example.com/mcp"
    ],
    "customTags": [
      "知识库"
    ],
    "deploymentConfig": {
      "accessControl": {
        "credentialId": "credential-id",
        "enabled": true,
        "mode": "CREDENTIAL"
      },
      "agentIdentityConfiguration": {
        "authorizationEnabled": true,
        "credentialProviderArn": "acs:agentidentity:cn-hangzhou:1234567890123456:provider/example",
        "credentialProviderType": "oauth2",
        "enabled": true
      },
      "artifactType": "Code",
      "codeConfiguration": {
        "codePackageToken": "upload-token",
        "command": [
          "python"
        ],
        "language": "python3.13"
      },
      "containerConfiguration": {
        "acrInstanceId": "cri-example",
        "command": [
          "python"
        ],
        "entrypoint": [
          "/bin/sh"
        ],
        "image": "registry.cn-hangzhou.aliyuncs.com/example/mcp:1.0.0",
        "imageRegistryType": "ACR",
        "mcpRuntimeMode": "SELF_HOSTED",
        "sourceType": "CONTAINER_IMAGE"
      },
      "hookConfiguration": {
        "hooks": [
          {
            "apiVersion": "1.0",
            "description": "记录 MCP 工具调用",
            "enabled": true,
            "event": "PRE_CALL_TOOL",
            "headers": {
              "key": "application/json"
            },
            "timeout": 3000,
            "url": "https://example.com/mcp-hook"
          }
        ]
      },
      "logConfiguration": {
        "enableInstanceMetrics": true,
        "enableRequestMetrics": true,
        "logBeginRule": "DefaultRegex",
        "logstore": "mcp-logs",
        "project": "agentcore-mcp-logs"
      },
      "mcpConfiguration": {
        "endpointPath": "/mcp",
        "sessionConcurrencyPerInstance": 1,
        "sessionIdleTimeoutSeconds": 1800,
        "sessionMaxLifetimeSeconds": 21600
      },
      "nasConfiguration": {
        "groupId": 1000,
        "mountPoints": [
          {
            "enableTls": true,
            "mountDir": "/mnt/data",
            "serverAddr": "example.cn-hangzhou.nas.aliyuncs.com"
          }
        ],
        "userId": 1000
      },
      "networkConfiguration": {
        "networkMode": "PUBLIC",
        "securityGroupId": "sg-example",
        "vSwitchIds": [
          "vsw-example"
        ],
        "vpcId": "vpc-example"
      },
      "ossMountConfiguration": {
        "mountPoints": [
          {
            "bucketName": "example-bucket",
            "bucketPath": "/data",
            "endpoint": "https://oss-cn-hangzhou.aliyuncs.com",
            "mountDir": "/mnt/data",
            "readOnly": true
          }
        ]
      },
      "parameterTransformConfiguration": {
        "enabled": true,
        "ruleSetId": "rules-1",
        "version": "1.0"
      },
      "proxyConfiguration": {
        "enabled": true
      },
      "runtimeConfiguration": {
        "cpu": 0.25,
        "diskSize": 512,
        "environmentVariables": {
          "key": "production"
        },
        "executionRoleArn": "acs:ram::1234567890123456:role/agentcore-mcp-execution",
        "instanceConcurrency": 200,
        "memory": 512,
        "port": 9000,
        "timeout": 300
      }
    },
    "description": "用于查询知识库的 MCP 服务",
    "endpoint": "https://example.com/mcp",
    "functionName": "agentcore-mcp-example",
    "marketSource": {
      "marketItemId": "market-1"
    },
    "mcpServerId": "mcp-server-id",
    "name": "my-mcp-server",
    "officialTag": "KNOWLEDGE_BASE",
    "protocol": "StreamableHTTP",
    "status": "READY",
    "statusReason": "代码包部署失败",
    "template": {
      "appliedTemplateVersion": "1.0.0",
      "latestTemplateVersion": "1.1.0",
      "schemaVersion": "1.0",
      "templateInputSchema": "{\"type\":\"object\",\"properties\":{\"addresses\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}}}",
      "updateAvailable": true
    },
    "type": "CODE_PACKAGE",
    "usageActive": true
  },
  "httpStatusCode": 200,
  "message": "success",
  "requestId": "request-123456",
  "success": true
}

错误码

HTTP status code

错误码

错误信息

描述

400 InvalidParameter An MCP template parameter is invalid.
500 InternalError The official MCP artifact reference is invalid.
404 Resource.NotFound The specified MCP market item or template version does not exist.
409 TemplateVersion.NotCurrent The specified MCP template version is no longer current.
409 McpServer.Name.AlreadyExists An MCP server name already exists.

访问错误中心查看更多错误码。

变更历史

更多信息,参考变更详情。