# 导入工作区MCP工具

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

工具级入口只保存工具元数据。

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/tools/actions/import-workspace-mcp
```

## 调用前准备

按[AI Studio](../../../../../developer/api/ai-studio/index.md)取得当前环境的个人访问令牌和工作区ID。当前有效角色须获准执行相应操作。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/tools/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"]}'
```

:::::
:::::{tab-item} 参数说明

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `workspace_id` | string | 是 | 当前环境的目标工作区ID，与请求头一致。 |
| `X-Workspace-ID` | string | 是 | 当前环境的工作区ID。 |
| `X-API-Key` | string | 是 | 当前环境的个人访问令牌。 |
| `dry_run` | boolean | 否 | JSON请求体；true只预演，省略、null或false走正式导入。 |
| `tool_names` | string（字符串数组） | 否 | JSON请求体；选择预演返回的确切名称。省略、null或[]选择所有候选。 |
| `tools` | object（对象数组） | 否 | 附加描述符；常规任务省略，子字段见共享合同。 |

先显式发送dry_run=true，再从返回值中选择可导入名称，正式调用时仍显式提供tool_names。预演可能包含不可导入的product_api；不应直接将整份预演结果写回。筛选、描述符及部分写入处理见[导入合同](import-contract.md)。此入口不会自动绑定智能体。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 0,
  "data": {
    "dry_run": true,
    "tools": [
      {
        "name": "qa_echo",
        "kind": "operator",
        "origin": "api_service"
      }
    ]
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 成功为0。 |
| `data.dry_run` | boolean | 本次是否预演。 |
| `data.tools` | object（对象数组） | 本次选中的导入结果；无匹配时可为空。 |
| `data.tools[].name` | string | 候选工具名称。 |
| `data.tools[].description` | string | 非空时返回的说明。 |
| `data.tools[].kind` | string | 当前投影为operator。 |
| `data.tools[].operator_id` | string | 可选标识；当前新API服务按名称绑定，不承诺返回。 |
| `data.tools[].workflow_id` | string | 可选标识；当前名称绑定分支不填。 |
| `data.tools[].version` | string | 可选版本；当前API服务不固定节点版本。 |
| `data.tools[].node_id` | string | 仅有相应来源值时返回，不是常规客户端导入输入。 |
| `data.tools[].tool_id` | string | 已存在或实际创建的工具ID；新候选预演时可省略。 |
| `data.tools[].origin` | string | 来源，例如api_service或product_api；Product API只可预演，不可正式导入为智能体工具。 |
| `data.tools[].existing` | boolean | 同名工具复用时为true；false可省略，不表示已核对全部配置相同。 |

:::::
::::::
:::::::

## 错误响应

| HTTP / code | 条件与处理 |
| --- | --- |
| 400 / 2 | 参数、候选或目标状态不合法；正式选择包含product_api时在创建前拒绝。 |
| 403 / 5 | 当前操作授权拒绝或工具只读。 |
| 409 / 4、9 | 工具名称或更新版本冲突；先回读已有工具。 |
| 503 / 15 | 工作区MCP导入或授权依赖不可用。 |

认证阶段还可返回字符串code/msg；具体说明见[错误与环境](errors-environments.md)。
