AI 助理
文档备案控制台
官方文档
首页 智能体构建和治理平台 AgentCore 开发参考 API参考 API目录 UpdateMcp - 更新 MCP 服务

UpdateMcp - 更新 MCP 服务

更新时间：
复制 MD 格式
我的收藏

更新指定 MCP 服务的地址、描述、认证或 Swagger 配置。MCP 类型和协议在创建后不可修改。更新为异步过程。

接口说明

请求说明

更新指定 MCP 服务的地址、描述、认证或 Swagger 配置。MCP 类型和协议在创建后不可修改。更新为异步过程。

调试

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

调试

授权信息

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

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

  • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。

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

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

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

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

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

操作

访问级别

资源类型

条件关键字

关联操作

agentcore:UpdateMcp

update

*Mcp

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

 无 无

请求语法

PUT /workspaces/{workspaceId}/mcp-servers/{mcpServerId} HTTP/1.1

路径参数

名称

类型

必填

描述

示例值
workspaceId

string

是

工作空间 ID。

ws-1234567890abcdef
mcpServerId

string

是

MCP 服务 ID

mcp-server-id

请求参数

名称

类型

必填

描述

示例值
body

object

否

请求体

addresses

array

否

MCP 服务地址列表。

string

否

MCP 服务地址列表中的元素。

https://example.com/mcp
auth

object

否

后端认证配置。enabled=true 时：DIRECT_PROXY 填写 directProxy（name/value），HTTP_TO_MCP 填写 httpToMcp 数组（每项 id/type/credential，apiKey 还需 position/name），支持多个认证对象，第一个为默认上游凭证；HTTP_TO_MCP 凭证会合并进 swagger 的 securitySchemes

codePackage

object

否

代码部署 MCP 的调用方 API Key 认证配置。

apiKey

string

否

用于校验 MCP 调用方的 API Key。

example-api-key
headerName

string

否

承载 API Key 的请求头名称。

X-API-Key
directProxy

object

否

直连代理认证配置。

name

string

否

名称。

mcp-example
value

string

否

认证参数取值。

example-credential
enabled

boolean

否

是否启用。

httpToMcp

array<object>

否

HTTP_TO_MCP 认证配置列表。

object

否

credential

string

否

认证凭证。

example-credential
id

string

否

认证方案 ID。

mcp-1234567890abcdef
name

string

否

名称。

mcp-example
position

string

否

凭证所在位置。

枚举值：

  • query :

    查询参数

  • header :

    请求头

header
type

string

否

类型。

枚举值：

  • apiKey :

    API Key 认证

  • bearer :

    Bearer 令牌认证

  • basic :

    Basic 认证

basic
customTags

array

否

自定义标签，支持多个；传空列表可清空

string

否

单个 MCP 自定义标签。

知识库
deploymentConfig

object

否

CODE_PACKAGE MCP 的部署配置补丁，对象字段按层级合并。不替换代码包时省略 CodeConfiguration.CodePackageToken，服务端复用当前已部署代码包；替换代码包时传入新的非空 Token。CodePackageUrl 仅支持 CreateMcp，更新时不支持。

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

否

描述。

用于说明资源用途的示例描述。
permissionMode

string

否

PUBLIC 表示公开访问；CONTROLLED 表示根据权限规则控制访问。

CONTROLLED
swaggerConfig

string

否

如果 Type=HTTP_TO_MCP，填写该字段

{"type":"object"}
clientToken

string

否

客户端幂等令牌。

123e4567-e89b-12d3-a456-426614174000

调用“更新 MCP 服务”接口时，请按参数定义传入：工作空间 ID、MCP 服务 ID、请求体、客户端幂等令牌。

返回参数

名称

类型

描述

示例值

object

查询成功

code

string

业务状态码。

Success
httpStatusCode

integer

HTTP 状态码。

200
message

string

响应消息。

请求处理成功
requestId

string

请求 ID。

A1B2C3D4-E5F6-47A8-90AB-CDEF12345678
success

boolean

请求是否成功。

“更新 MCP 服务”接口的响应包含：请求 ID、响应消息、HTTP 状态码、业务状态码、请求是否成功。

示例

正常返回示例

JSON格式

{
  "code": "Success",
  "httpStatusCode": 200,
  "message": "请求处理成功",
  "requestId": "A1B2C3D4-E5F6-47A8-90AB-CDEF12345678",
  "success": true
}

错误码

HTTP status code

错误码

错误信息

描述
400 InvalidParameter Parameter error: %s. 参数错误
400 IllegalRequest Illegal request: %s. 非法请求
400 InvalidParameter.ImportFileSize The import file size exceeds the allowed limit: %s. 导入文件大小超过限制
500 InternalError The MCP server data could not be processed.
403 NoPermission You are not authorized to perform this operation: %s. 无操作权限
404 Resource.NotFound Not found: %s.
404 NotFound Not found: %s. 指定的工作空间、资源 或 版本不存在
409 Resource.Conflict Resource conflict: %s.
409 ResourceAlreadyExist Resource already exists: %s. 指定的资源已存在

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

变更历史

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

上一篇：UpdateManagedAgent - 更新托管智能体下一篇：UpdateMcpTemplateConfig - 更新模板托管 MCP 的配置参数