执行工厂 · MCP API (0.1.3)

Download OpenAPI specification:

MCP（Model Context Protocol）Server 的注册、管理与代理调用。这里的 MCP 有两个方向，别混：

接入外部 MCP：把别人的 MCP Server 登记进平台，然后通过 /mcp/proxy/{mcp_id}/... 代为列工具、调工具。
对外提供 MCP：把平台里的工具打包成一个 MCP Server 暴露出去，端点在 /mcp/app/{mcp_id}/...，MCP 客户端（Cursor / Claude Desktop 等）直接连它。

creation_type 区分这两类：custom 是登记的外部服务，tool_imported 是由平台工具箱里的工具组装出来的。

运行模式 mode 在新增与更新时可选范围不同（服务端 validate 标签不一致）：

接口	可选值
`POST /mcp/` 新增	`sse`、`stream`
`PUT /mcp/{mcp_id}` 更新	`sse`、`stream`、`stdio_uv`、`stdio_npx`

也就是说 stdio 类模式没法直接新建，只能建完再改过去。这不像有意设计，接入时留意。

时间戳一律是纳秒：所有 *_time 字段用 time.Now().UnixNano() 生成，形如 1784880971306127803。按毫秒解析会得到 1970 年附近的日期。

认证：Authorization: Bearer <token>（OAuth access token 或 bak_ 前缀的 AppKey）。

MCP

探测外部 MCP Server

在登记之前先连一次目标 MCP Server，把它的工具列表与初始化信息取回来，用于前端预览「这个服务里有什么」。不落库，纯探测。

接口名叫 parse/sse 是历史原因，mode 传 stream 同样可用。

Authorizations:

OAuth2AppKey

Request Body schema: application/json
required

mode required	string (MCPMode) Enum: "sse" "stream" "stdio_uv" "stdio_npx" 运行模式。新增接口只接受 `sse` / `stream`，`stdio_*` 只能通过更新接口设置。
url required	string <uri> 目标 MCP Server 地址。
	object 连接时携带的请求头。

Responses

Request samples

Payload

Content type

application/json

{"mode": "stream",
"url": "https://example.com/mcp",
"headers": {"Authorization": "Bearer xxx"
}
}

Response samples

200
400
401
500

Content type

application/json

{"tools": [{"name": "string",
"description": "string",
"inputSchema": { }
}
],
"init_info": { }
}

新增 MCP Server

登记一个 MCP Server。

路径带尾斜杠——路由注册的就是 /mcp/，不是 /mcp。Gin 默认会把 /mcp 重定向到 /mcp/，但重定向会丢 POST body 的客户端不在少数，直接写全路径最稳。

mode 此处只接受 sse / stream（见文件头说明）。creation_type 为 tool_imported 时用 tool_configs 指定要打包哪些工具。

Authorizations:

OAuth2AppKey

Request Body schema: application/json
required

mode	string (MCPMode) Enum: "sse" "stream" "stdio_uv" "stdio_npx" 运行模式。新增接口只接受 `sse` / `stream`，`stdio_*` 只能通过更新接口设置。
url	string <uri> 目标服务地址。`sse` / `stream` 模式用。
	object 连接时携带的请求头，如上游的鉴权凭据。
command	string 启动命令。`stdio_*` 模式用。
args	Array of strings 启动参数。`stdio_*` 模式用。
	object 环境变量。`stdio_*` 模式用。
name required	string MCP Server 名称。
description	string
creation_type required	string (MCPCreationType) Enum: "custom" "tool_imported" 创建类型：`custom` 登记的外部 MCP Server；`tool_imported` 由平台工具箱里的工具组装而成。
source	string Default: "custom" 来源。
category	string Default: "other_category" 分类。
is_internal	boolean Default: false 是否内置。
	Array of objects (MCPToolConfig) `creation_type=tool_imported` 时指定要打包的工具。

Responses

Request samples

Payload

Content type

application/json

Example

登记外部服务

{"creation_type": "custom",
"name": "天气服务",
"description": "提供天气查询",
"mode": "stream",
"url": "https://example.com/mcp"
}

Response samples

200
400
401
500

Content type

application/json

{"mcp_id": "string",
"status": "string"
}

分页查询 MCP Server

分页列出当前主体获授权访问的 MCP Server，支持按名称、来源、分类、状态、运行模式过滤。

Authorizations:

OAuth2AppKey

query Parameters

page	integer >= 1 Default: 1 页码，从 1 开始。
page_size	integer [ 1 .. 100 ] Default: 10 每页数量，1–100。
sort_by	string Default: "update_time" Enum: "update_time" "create_time" "name" 排序字段。
sort_order	string Default: "desc" Enum: "asc" "desc" 排序方向。
name	string 按名称过滤。
source	string 按来源过滤。
category	string 按分类过滤。
status	string 按状态过滤。
create_user	string 按创建人过滤。
is_internal	boolean 只看内置。
mode	string (MCPMode) Enum: "sse" "stream" "stdio_uv" "stdio_npx" 按运行模式过滤。
all	boolean 忽略分页返回全部。

Responses

Response samples

200
400
401
500

Content type

application/json

{"total": 2,
"page": 1,
"page_size": 2,
"total_pages": 1,
"has_next": false,
"has_prev": false,
"data": [{"mcp_id": "5a09efa5-d315-4450-adb3-5b2799d50b7f",
"name": "aaa",
"description": "aaa",
"mode": "stream",
"url": "http://agent-operator-integration:9000/api/agent-operator-integration/internal-v1/mcp/app/5a09efa5-d315-4450-adb3-5b2799d50b7f/1/stream",
"version": 1,
"creation_type": "tool_imported",
"status": "published",
"source": "custom",
"is_internal": false,
"category": "other_category",
"create_user": "Administrator",
"create_time": 1784880971306128000,
"update_user": "Administrator",
"update_time": 1784881048211594500
}
]
}

查询 MCP Server 详情

取详情。响应分两块：base_info 是配置本身，connection_info 是平台为它生成的对外连接地址（sse_url / stream_url）——MCP 客户端要连的是这两个地址，不是 base_info.url（那是上游服务的地址）。

stream_url 为空表示该服务不支持流式。

Authorizations:

OAuth2AppKey

path Parameters

mcp_id

required

string

MCP Server ID。

Responses

Response samples

200
401
404
500

Content type

application/json

{"base_info": {"mode": "sse",
"url": "http://example.com",
"headers": {"property1": "string",
"property2": "string"
},
"command": "string",
"args": ["string"
],
"env": {"property1": "string",
"property2": "string"
},
"operations": ["view"
],
"mcp_id": "string",
"version": 0,
"name": "string",
"description": "string",
"creation_type": "custom",
"status": "string",
"source": "string",
"is_internal": true,
"category": "string",
"create_user": "string",
"create_time": 0,
"update_user": "string",
"update_time": 0,
"release_user": "string",
"release_time": 0,
"tool_configs": [{"box_id": "string",
"tool_id": "string",
"box_name": "string",
"tool_name": "string",
"description": "string",
"use_rule": "string"
}
]
},
"connection_info": {"sse_url": "string",
"stream_url": "string"
}
}

更新 MCP Server

整体更新配置。这里的 mode 接受四个值（含 stdio_uv / stdio_npx），比新增时宽——stdio 类模式只能通过更新设置。

Authorizations:

OAuth2AppKey

path Parameters

mcp_id

required

string

MCP Server ID。

Request Body schema: application/json
required

mcp_id	string MCP Server ID。与路径参数一致即可。
name	string
description	string
creation_type required	string (MCPCreationType) Enum: "custom" "tool_imported" 创建类型：`custom` 登记的外部 MCP Server；`tool_imported` 由平台工具箱里的工具组装而成。
mode	string (MCPMode) Enum: "sse" "stream" "stdio_uv" "stdio_npx" 运行模式。新增接口只接受 `sse` / `stream`，`stdio_*` 只能通过更新接口设置。
url	string <uri>
	object
command	string
args	Array of strings
	object
source	string
category	string
	Array of objects (MCPToolConfig)

Responses

Request samples

Payload

Content type

application/json

{"mcp_id": "string",
"name": "string",
"description": "string",
"creation_type": "custom",
"mode": "sse",
"url": "http://example.com",
"headers": {"property1": "string",
"property2": "string"
},
"command": "string",
"args": ["string"
],
"env": {"property1": "string",
"property2": "string"
},
"source": "string",
"category": "string",
"tool_configs": [{"box_id": "string",
"tool_id": "string",
"box_name": "string",
"tool_name": "string",
"description": "string",
"use_rule": "string"
}
]
}

Response samples

200
400
401
404
500

Content type

application/json

{"mcp_id": "string",
"status": "unpublish"
}

删除 MCP Server

删除登记的 MCP Server。已被 Agent 挂载的服务删除后调用方会拿到 404。

Authorizations:

OAuth2AppKey

path Parameters

mcp_id

required

string

MCP Server ID。

Responses

Response samples

401
404
500

Content type

application/json

{"error_code": "string",
"description": "string",
"error_details": null,
"metadata": { }
}

更新 MCP Server 状态

发布 / 下架。改成 published 后该服务出现在 MCP 市场，offline 则下架。

Authorizations:

OAuth2AppKey

path Parameters

mcp_id

required

string

MCP Server ID。

Request Body schema: application/json
required

status

required

string (BizStatus)

Enum: "unpublish" "published" "offline" "editing"

生命周期状态。

Responses

Request samples

Payload

Content type

application/json

{"status": "unpublish"
}

Response samples

200
400
401
404
500

Content type

application/json

{"mcp_id": "string",
"status": "unpublish"
}

调试 MCP 工具

用给定参数真实调用一次该 MCP Server 上的某个工具，看返回什么。

当前主体必须对具体 mcp:{mcp_id} 持有 execute。拒绝或 bkn-safe 判定失败时不会调用目标 MCP Server。

失败不体现在 HTTP 状态码上：工具报错时接口仍是 200，is_error 为 true，错误内容在 content 里。

Authorizations:

OAuth2AppKey

path Parameters

mcp_id required	string MCP Server ID。
tool_name required	string 工具名。

Request Body schema: application/json
required

object

工具入参，结构由该工具自己的 input schema 决定。

Responses

Request samples

Payload

Content type

application/json

{"parameters": { }
}

Response samples

Content type

application/json

{"content": [{ }
],
"is_error": true
}

MCP 市场列表

已发布的 MCP Server 列表。比 /mcp/list 多一个 release_user 过滤条件，其余参数一致。

Authorizations:

OAuth2AppKey

query Parameters

page	integer >= 1 Default: 1 页码，从 1 开始。
page_size	integer [ 1 .. 100 ] Default: 10 每页数量，1–100。
sort_by	string Default: "update_time" Enum: "update_time" "create_time" "name" 排序字段。
sort_order	string Default: "desc" Enum: "asc" "desc" 排序方向。
name	string 按名称过滤。
release_user	string 按发布人过滤。
category	string 按分类过滤。
all	boolean 忽略分页返回全部。

Responses

Response samples

200
400
401
500

Content type

application/json

{"total": 0,
"page": 0,
"page_size": 0,
"total_pages": 0,
"has_next": true,
"has_prev": true,
"data": [{"mode": "sse",
"url": "http://example.com",
"headers": {"property1": "string",
"property2": "string"
},
"command": "string",
"args": ["string"
],
"env": {"property1": "string",
"property2": "string"
},
"operations": ["view"
],
"mcp_id": "string",
"version": 0,
"name": "string",
"description": "string",
"creation_type": "custom",
"status": "string",
"source": "string",
"is_internal": true,
"category": "string",
"create_user": "string",
"create_time": 0,
"update_user": "string",
"update_time": 0,
"release_user": "string",
"release_time": 0,
"tool_configs": [{"box_id": "string",
"tool_id": "string",
"box_name": "string",
"tool_name": "string",
"description": "string",
"use_rule": "string"
}
]
}
]
}

MCP 市场详情

市场视角的 MCP Server 详情，结构与 GET /mcp/{mcp_id} 一致。

Authorizations:

OAuth2AppKey

path Parameters

mcp_id

required

string

MCP Server ID。

Responses

Response samples

200
401
404
500

Content type

application/json

{"base_info": {"mode": "sse",
"url": "http://example.com",
"headers": {"property1": "string",
"property2": "string"
},
"command": "string",
"args": ["string"
],
"env": {"property1": "string",
"property2": "string"
},
"operations": ["view"
],
"mcp_id": "string",
"version": 0,
"name": "string",
"description": "string",
"creation_type": "custom",
"status": "string",
"source": "string",
"is_internal": true,
"category": "string",
"create_user": "string",
"create_time": 0,
"update_user": "string",
"update_time": 0,
"release_user": "string",
"release_time": 0,
"tool_configs": [{"box_id": "string",
"tool_id": "string",
"box_name": "string",
"tool_name": "string",
"description": "string",
"use_rule": "string"
}
]
},
"connection_info": {"sse_url": "string",
"stream_url": "string"
}
}

批量取 MCP Server 的指定字段

一次取多个 MCP Server 的部分字段，两个参数都走路径且都是逗号分隔的列表——不是 query 参数，别写成 ?mcp_ids=a,b。

fields 只能从这份白名单里选：mcp_id、name、description、source、 category、mode、is_internal、create_user、create_time、 update_user、update_time、release_time、release_user。不在白名单里的字段名会被静默忽略，不报错。

响应是按请求字段投影后的裸 map 数组，字段随 fields 变化，因此这里不给固定 schema。

Authorizations:

OAuth2AppKey

path Parameters

mcp_ids required	string Example: 5a09efa5-d315-4450-adb3-5b2799d50b7f,7c9e6679-7425-40de-944b-e07fc1f90ae7 MCP Server ID 列表，逗号分隔。
fields required	string Example: mcp_id,name,category 要取的字段名，逗号分隔。只接受白名单内的字段。

Responses

Response samples

200
400
401
500

Content type

application/json

[{ }
]

代理：列出该 MCP Server 的工具

由平台代为连接目标 MCP Server 并取回工具列表。调用方不必自己实现 MCP 握手，也不需要能直连目标服务。工具 schema 是执行时构造参数所需的元数据，因此对已知 MCP Server 拥有 view、public_access 或 execute 任一权限即可读取； execute-only 的 MCP Server 仍不会出现在顶层目录中。

默认返回调用方实际会被服务的版本：editing 的 MCP Server 返回已发布版本的工具，草稿中的改动在重新发布前不可见，与 /mcp/proxy/{mcp_id}/tool/call 一致。编辑页需要列出草稿时传 draft=true，见该参数说明。

Authorizations:

OAuth2AppKey

path Parameters

mcp_id

required

string

MCP Server ID。

query Parameters

draft

boolean

Default: false

为 true 时返回配置当前版本（草稿）的工具，供编辑页调试使用；只在 editing 状态下与默认结果不同。草稿属于编辑内容，需要 view 权限，仅持有 execute 或 public_access 时返回 403。

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"tools": [{"name": "string",
"description": "string",
"inputSchema": { }
}
]
}

代理：调用该 MCP Server 的工具

由平台代为调用目标 MCP Server 上的工具。与 /mcp/{mcp_id}/tool/{tool_name}/debug 的差别只在定位方式：那边工具名走路径、语义是「调试」；这边工具名在请求体里、语义是「生产调用」。两者的返回结构一致，同样是**工具报错也返回 200，看 is_error**。

当前主体必须对具体 mcp:{mcp_id} 持有 execute。用于知识网络 Action 时，ontology-query 还会在此前校验具体 Action Type 和数据依赖。请求体不能覆盖执行主体，平台身份头和 trace 控制头不会转发给第三方 MCP。

只有已发布的 MCP Server 能被调用：published 按当前配置调用；editing 按已发布版本调用，草稿中的改动在重新发布前不生效；unpublish / offline 一律返回 400 MCPServerNotPublished，在建连之前拒绝。没有发布记录的 editing （例如从别的环境导入的编辑中 MCP Server）没有可服务的版本，同样返回 400。调试接口不受此限，按草稿调用。

Authorizations:

OAuth2AppKey

path Parameters

mcp_id

required

string

MCP Server ID。

Request Body schema: application/json
required

tool_name required	string 工具名。
required	object 工具入参。

Responses

Request samples

Payload

Content type

application/json

{"tool_name": "string",
"parameters": { }
}

Response samples

Content type

application/json

{"content": [{ }
],
"is_error": true
}

对外 MCP 端点（Streamable HTTP）

这是给 MCP 客户端连的端点，不是给业务代码调的 REST 接口。平台把该 mcp_id 对应的服务以标准 MCP Streamable HTTP 暴露出来，Cursor / Claude Desktop 等直接填这个地址即可。

实际地址以 GET /mcp/{mcp_id} 返回的 connection_info.stream_url 为准。

该路由注册为 Any，GET / POST / DELETE 都由 MCP 协议语义决定，请求与响应结构见 MCP 规范，本文档不复述。

Authorizations:

OAuth2AppKey

path Parameters

mcp_id

required

string

MCP Server ID。

Responses

Response samples

200
401
404

Content type

application/json

{ }

对外 MCP 端点（SSE）

SSE 传输的 MCP 端点，给只支持 SSE 的客户端用。实际地址以 GET /mcp/{mcp_id} 返回的 connection_info.sse_url 为准。

SSE 是单向下行通道，客户端的请求要发到配套的 POST /mcp/app/{mcp_id}/message。

Authorizations:

OAuth2AppKey

path Parameters

mcp_id

required

string

MCP Server ID。

Responses

Response samples

401
404

Content type

application/json

{"error_code": "string",
"description": "string",
"error_details": null,
"metadata": { }
}

对外 MCP 端点（SSE 的上行消息）

与 /mcp/app/{mcp_id}/sse 配套：SSE 只负责下行，客户端的 JSON-RPC 请求走这里上行。单独调它没有意义，必须先建立 SSE 连接。

Authorizations:

OAuth2AppKey

path Parameters

mcp_id

required

string

MCP Server ID。

Request Body schema: application/json
required

property name*

additional property

any

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
401
404

Content type

application/json

{ }

执行工厂 · MCP API (0.1.3)

MCP

探测外部 MCP Server

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

新增 MCP Server

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

分页查询 MCP Server

Authorizations:

query Parameters

Responses

Response samples

查询 MCP Server 详情

Authorizations:

path Parameters

Responses

Response samples

更新 MCP Server

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

删除 MCP Server

Authorizations:

path Parameters

Responses

Response samples

更新 MCP Server 状态

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

调试 MCP 工具

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

MCP 市场列表

Authorizations:

query Parameters

Responses

Response samples

MCP 市场详情

Authorizations:

path Parameters

Responses

Response samples

批量取 MCP Server 的指定字段

Authorizations:

path Parameters

Responses

Response samples

代理：列出该 MCP Server 的工具

Authorizations:

path Parameters

query Parameters

Responses

Response samples

代理：调用该 MCP Server 的工具

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

对外 MCP 端点（Streamable HTTP）

Authorizations:

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required