Skip to main content

MCP API 概览

MCP API 用于管理百炼上的 MCP 服务,支持查询、创建、更新、开通、启停、删除、工具调用与推荐。

MCP API 用于管理阿里云百炼上的 MCP 服务,覆盖官方 MCP 与自定义 MCP 的查询、创建、更新、开通、启停和删除,并提供工具列表、工具调用与工具推荐能力。
调用前请先配置认证;错误处理见MCP API 错误码。

前提条件

  1. 已开通阿里云百炼,并创建 API Key。
  2. 已获取工作空间 ID。登录百炼控制台,在右上角工作空间菜单中复制工作空间 ID。

Endpoint

https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/mcp/servers
  • workspace_id:工作空间 ID。

响应结构

成功和业务错误统一返回以下结构,响应头包含 x-request-id:
字段类型说明
successboolean请求是否成功。工具是否执行成功还需查看 data.isError
error_codestring / null错误码,成功时为 null
error_msgstring / null错误信息,成功时为 null
dataobject / array / null业务数据,失败时为 null
request_idstring请求 ID
{
  "success": true,
  "error_code": null,
  "error_msg": null,
  "data": {},
  "request_id": "6f1c2a8e-3b0d-4c55-9a0e-2f7d1c9b8a11"
}

枚举

type(归属类型)
值说明
OFFICIAL官方 MCP
CUSTOMER自定义 MCP
server_type(服务类型)
值说明
STDIO通过 npx/uvx 启动,部署在函数计算 FC
HTTP远程 Streamable HTTP 服务
SSE远程 SSE 服务
OPENAPI将已有 HTTP API 转换为 MCP
server_status(服务状态)
值自定义 MCP 文案官方 MCP 文案
INACTIVE未启用未开通
ACTIVATING部署中开通中
ACTIVATED已启用已启用
ACTIVATE_FAILED部署失败开通失败
DELETED已删除-

数据结构

DetailResponse

详情、列表项、开通、停用、启用和删除接口返回的服务信息。
字段类型说明
mcp_codestring / nullMCP 唯一编码
server_namestring / nullMCP 名称
descriptionstring / nullMCP 描述
typestring / nullOFFICIAL / CUSTOMER
server_typestring / nullSTDIO / HTTP / SSE / OPENAPI
server_statusstring / null服务状态
server_status_textstring / null状态文案
dashscope_endpointstring / nullMCP 接入地址,仅已启用或开通中时返回
meta_infoobject / null服务元信息
mcp_configobject / null自定义 MCP 的已保存配置;官方 MCP 为 null

meta_info

字段类型说明
iconstring / null图标地址,仅官方 MCP
providerstring / null提供方,仅官方 MCP
is_onekeyboolean是否为 One Key MCP,仅官方 MCP
console_detail_urlstring控制台详情地址
classificationstring / null分类中文名称,未配置时为 null
activate_user_countlong / null累计开通账号数
call_total_countlong / null累计调用次数
average_call_timelong / null当日成功调用平均耗时,单位毫秒
call_success_ratedouble / null成功率,取值 0 到 1
自定义 MCP 的 meta_info 不包含 icon、provider、is_onekey。

CreateResponse

创建和更新接口返回的服务信息,未赋值的字段不输出。
字段类型说明
mcp_codestringMCP 编码
server_namestringMCP 名称
server_statusstring服务状态
server_status_textstring状态文案
activate_fail_reasonstring部署失败原因,仅部署失败时返回

请求命名

分页参数使用 pageNo、pageSize,推荐条数使用 topN,路径参数使用 mcpCode。请求体和响应字段使用 snake_case,工具调用结果除外:工具 schema 沿用 MCP 协议字段 inputSchema、additionalProperties,工具调用结果使用 isError。

接口列表

接口方法说明
查询 MCP 列表GET /list分页查询官方和自定义 MCP
创建自定义 MCPPOST /创建并部署自定义 MCP
查询 MCP 详情GET /{mcpCode}查询 MCP 详情
更新自定义 MCPPOST /{mcpCode}更新名称、描述或配置
删除自定义 MCPDELETE /{mcpCode}删除自定义 MCP
查询工具列表GET /{mcpCode}/tools查询 MCP 提供的工具
调用工具POST /{mcpCode}/tools/call调用指定工具
推荐工具GET /tools/recommend按自然语言需求推荐工具
开通官方 MCPPOST /{mcpCode}/activate开通官方 MCP
关闭官方 MCPPOST /{mcpCode}/deactivate关闭官方 MCP
停用自定义 MCPPOST /{mcpCode}/disable停用自定义 MCP
启用自定义 MCPPOST /{mcpCode}/enable启用自定义 MCP
mcp_config 中的 headers 等配置会按保存值返回,可能包含敏感信息。请仅在可信环境调用,并妥善保护响应内容。