# 管理自定义算子 MCP

将已启用的自定义算子发布为工作区 MCP 工具，供支持 MCP 的客户端发现和调用。发布、取消发布和查询状态使用自定义算子 API。客户端调用已发布工具时使用工作区的 MCP 入口。

## 调用前准备

先[查询自定义算子详情](get-custom-operator.md#成功响应)，取得算子 ID 并确认算子已启用。准备具有目标工作区访问权限的[个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)和[目标工作区 ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。

- **发布或取消发布**：需要算子的更新权限。
- **查询状态**：需要算子的读取权限。
- **从 MCP 客户端调用**：目录按读取权限过滤，调用还需要运行权限。

产品 API 桥接工具使用不同的目录可见性规则，调用时仍需通过产品接口的权限校验。
目录中可见的工具不一定允许当前身份调用。

## 发布、取消发布和查询状态

同一 `identifier` 只能发布一个活动版本。发布另一版本时，会替换当前版本。取消发布只移除当前算子对应的发布。

停用算子后，工具会被隐藏，但发布记录可能保留。`published` 和 `live_published` 结合启用状态表示工具是否可见，不能用于判断发布记录是否存在。

发布、取消发布和状态查询都返回 `code`、`msg`、`data`。数据含 `operator_id`、`identifier`、`version`、`published`、`live_published`。存在当前活跃版本时还返回 `live_operator_id`、`live_version`。业务错误只返回 `code` 和 `msg`。当前对停用算子执行发布会返回 `500` / `ErrServer`。

将 `$OPERATOR_ID` 替换为自定义算子 ID。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 发布

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/custom-operators/$OPERATOR_ID/mcp-publish" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

:::::
:::::{tab-item} 取消发布

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/custom-operators/$OPERATOR_ID/mcp-unpublish" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

:::::
:::::{tab-item} 查询状态

```bash
curl "https://api.moi.matrixorigin.cn/v5/workflow/v2/custom-operators/$OPERATOR_ID/mcp-status" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

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

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `operator_id` | integer | 是 | 自定义算子 ID，位于请求路径中。 |

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

发布或取消发布会同步完成写入并查询状态后返回。错误可能发生在写入之后。先查询发布状态，再决定是否重新提交。

## 从 MCP 客户端调用已发布算子

调用 `tools/list` 和 `tools/call` 时必须同时提交 `X-Workspace-ID`，且与路径工作区完全一致。初始化、通知和 `ping` 不使用相同的工具调用检查。

已发布工具的工作区入口如下。该入口使用无会话 Streamable HTTP 和 JSON-RPC。使用 `X-API-Key` 传递个人访问令牌，不要同时传递 `Authorization` 请求头。

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/published-mcp
```

先初始化，再调用 `tools/list` 取得当前调用者可用的工具。初始化完成后，发送 `notifications/initialized` 通知。该通知返回 HTTP `202` 且没有响应体。

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/published-mcp" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "init-01",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "example-client",
        "version": "1.0.0"
      }
    }
  }'
```

`GET` 和 `DELETE` 不支持该入口，返回 HTTP `405`。