MCP API 用于管理百炼上的 MCP 服务,支持查询、创建、更新、开通、启停、删除、工具调用与推荐。
MCP API 用于管理阿里云百炼上的 MCP 服务,覆盖官方 MCP 与自定义 MCP 的查询、创建、更新、开通、启停和删除,并提供工具列表、工具调用与工具推荐能力。
成功和业务错误统一返回以下结构,响应头包含
type(归属类型)
server_type(服务类型)
server_status(服务状态)
详情、列表项、开通、停用、启用和删除接口返回的服务信息。
自定义 MCP 的
创建和更新接口返回的服务信息,未赋值的字段不输出。
分页参数使用
调用前请先配置认证;错误处理见MCP API 错误码。
前提条件
- 已开通阿里云百炼,并创建 API Key。
- 已获取工作空间 ID。登录百炼控制台,在右上角工作空间菜单中复制工作空间 ID。
Endpoint
workspace_id:工作空间 ID。
响应结构
成功和业务错误统一返回以下结构,响应头包含 x-request-id:
| 字段 | 类型 | 说明 |
|---|---|---|
| success | boolean | 请求是否成功。工具是否执行成功还需查看 data.isError |
| error_code | string / null | 错误码,成功时为 null |
| error_msg | string / null | 错误信息,成功时为 null |
| data | object / array / null | 业务数据,失败时为 null |
| request_id | string | 请求 ID |
枚举
type(归属类型)
| 值 | 说明 |
|---|---|
| OFFICIAL | 官方 MCP |
| CUSTOMER | 自定义 MCP |
| 值 | 说明 |
|---|---|
| STDIO | 通过 npx/uvx 启动,部署在函数计算 FC |
| HTTP | 远程 Streamable HTTP 服务 |
| SSE | 远程 SSE 服务 |
| OPENAPI | 将已有 HTTP API 转换为 MCP |
| 值 | 自定义 MCP 文案 | 官方 MCP 文案 |
|---|---|---|
| INACTIVE | 未启用 | 未开通 |
| ACTIVATING | 部署中 | 开通中 |
| ACTIVATED | 已启用 | 已启用 |
| ACTIVATE_FAILED | 部署失败 | 开通失败 |
| DELETED | 已删除 | - |
数据结构
DetailResponse
详情、列表项、开通、停用、启用和删除接口返回的服务信息。
| 字段 | 类型 | 说明 |
|---|---|---|
| mcp_code | string / null | MCP 唯一编码 |
| server_name | string / null | MCP 名称 |
| description | string / null | MCP 描述 |
| type | string / null | OFFICIAL / CUSTOMER |
| server_type | string / null | STDIO / HTTP / SSE / OPENAPI |
| server_status | string / null | 服务状态 |
| server_status_text | string / null | 状态文案 |
| dashscope_endpoint | string / null | MCP 接入地址,仅已启用或开通中时返回 |
| meta_info | object / null | 服务元信息 |
| mcp_config | object / null | 自定义 MCP 的已保存配置;官方 MCP 为 null |
meta_info
| 字段 | 类型 | 说明 |
|---|---|---|
| icon | string / null | 图标地址,仅官方 MCP |
| provider | string / null | 提供方,仅官方 MCP |
| is_onekey | boolean | 是否为 One Key MCP,仅官方 MCP |
| console_detail_url | string | 控制台详情地址 |
| classification | string / null | 分类中文名称,未配置时为 null |
| activate_user_count | long / null | 累计开通账号数 |
| call_total_count | long / null | 累计调用次数 |
| average_call_time | long / null | 当日成功调用平均耗时,单位毫秒 |
| call_success_rate | double / null | 成功率,取值 0 到 1 |
meta_info 不包含 icon、provider、is_onekey。
CreateResponse
创建和更新接口返回的服务信息,未赋值的字段不输出。
| 字段 | 类型 | 说明 |
|---|---|---|
| mcp_code | string | MCP 编码 |
| server_name | string | MCP 名称 |
| server_status | string | 服务状态 |
| server_status_text | string | 状态文案 |
| activate_fail_reason | string | 部署失败原因,仅部署失败时返回 |
请求命名
分页参数使用 pageNo、pageSize,推荐条数使用 topN,路径参数使用 mcpCode。请求体和响应字段使用 snake_case,工具调用结果除外:工具 schema 沿用 MCP 协议字段 inputSchema、additionalProperties,工具调用结果使用 isError。
接口列表
| 接口 | 方法 | 说明 |
|---|---|---|
| 查询 MCP 列表 | GET /list | 分页查询官方和自定义 MCP |
| 创建自定义 MCP | POST / | 创建并部署自定义 MCP |
| 查询 MCP 详情 | GET /{mcpCode} | 查询 MCP 详情 |
| 更新自定义 MCP | POST /{mcpCode} | 更新名称、描述或配置 |
| 删除自定义 MCP | DELETE /{mcpCode} | 删除自定义 MCP |
| 查询工具列表 | GET /{mcpCode}/tools | 查询 MCP 提供的工具 |
| 调用工具 | POST /{mcpCode}/tools/call | 调用指定工具 |
| 推荐工具 | GET /tools/recommend | 按自然语言需求推荐工具 |
| 开通官方 MCP | POST /{mcpCode}/activate | 开通官方 MCP |
| 关闭官方 MCP | POST /{mcpCode}/deactivate | 关闭官方 MCP |
| 停用自定义 MCP | POST /{mcpCode}/disable | 停用自定义 MCP |
| 启用自定义 MCP | POST /{mcpCode}/enable | 启用自定义 MCP |