导入MCP工具并绑定智能体¶
先导入工具,再更新目标智能体绑定。绑定失败时须回读工具及绑定。
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agents/{agent_id}/actions/import-workspace-mcp
调用前准备¶
按AI Studio取得当前环境的个人访问令牌和工作区ID。当前有效角色须获准执行相应操作。另准备目标智能体ID,预演也会先检查目标更新权限。
请求参数¶
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/actions/import-workspace-mcp" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
--data '{"dry_run":true,"tool_names":["qa_echo"]}'
参数 |
类型 |
是否必填 |
说明 |
|---|---|---|---|
|
string |
是 |
当前环境的目标工作区ID,与请求头一致。 |
|
string |
是 |
当前环境的工作区ID。 |
|
string |
是 |
当前环境的个人访问令牌。 |
|
boolean |
否 |
JSON请求体;true只预演,省略、null或false走正式导入。 |
|
string(字符串数组) |
否 |
JSON请求体;选择预演返回的确切名称。省略、null或[]选择所有候选。 |
|
object(对象数组) |
否 |
附加描述符;常规任务省略,子字段见共享合同。 |
|
string |
是 |
路径中可更新的目标智能体ID。 |
|
string |
否 |
查询参数;省略为当前工作区。system并不代表获准更新系统智能体。 |
先显式发送dry_run=true,再从返回值中选择可导入名称,正式调用时仍显式提供tool_names。预演可能包含不可导入的product_api;不应直接将整份预演结果写回。筛选、描述符及部分写入处理见导入合同。此响应没有bound标志,不能根据返回tools就推断整个绑定事务完成。
成功响应¶
{
"code": 0,
"data": {
"dry_run": true,
"tools": [
{
"name": "qa_echo",
"kind": "operator",
"origin": "api_service"
}
]
}
}
字段 |
类型 |
说明 |
|---|---|---|
|
integer |
成功为0。 |
|
boolean |
本次是否预演。 |
|
object(对象数组) |
本次选中的导入结果;无匹配时可为空。 |
|
string |
候选工具名称。 |
|
string |
非空时返回的说明。 |
|
string |
当前投影为operator。 |
|
string |
可选标识;当前新API服务按名称绑定,不承诺返回。 |
|
string |
可选标识;当前名称绑定分支不填。 |
|
string |
可选版本;当前API服务不固定节点版本。 |
|
string |
仅有相应来源值时返回,不是常规客户端导入输入。 |
|
string |
已存在或实际创建的工具ID;新候选预演时可省略。 |
|
string |
来源,例如api_service或product_api;Product API只可预演,不可正式导入为智能体工具。 |
|
boolean |
同名工具复用时为true;false可省略,不表示已核对全部配置相同。 |
错误响应¶
HTTP / code |
条件与处理 |
|---|---|
400 / 2 |
参数、候选或目标状态不合法;正式选择包含product_api时在创建前拒绝。 |
403 / 5 |
当前操作授权拒绝或工具只读。 |
409 / 4、9 |
工具名称或更新版本冲突;先回读已有工具。 |
503 / 15 |
工作区MCP导入或授权依赖不可用。 |
认证阶段还可返回字符串code/msg;具体说明见错误与环境。