<span id="管理自定义算子-mcp"></span>

# Manage MCP publication for custom operators

Publish an enabled custom operator as a workspace MCP tool for discovery and invocation by MCP clients. Use custom operator APIs to publish, unpublish, and read publication status. Clients invoke published tools through the workspace MCP endpoint.

<span id="调用前准备"></span>

## Before you call this API

First [Get custom operator details](get-custom-operator.md#successful-response) to obtain the operator ID and confirm it is enabled. Prepare a [Personal access token](../../../../../guides/genesis/api-keys.md#creating-and-managing-personal-access-tokens) with access to the target workspace and the [Target workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id).

- **Publish or unpublish**: requires update privileges on the operator.
- **Read status**: requires read privileges on the operator.
- **Invoke from an MCP client**: the catalog is filtered by read privileges, while invocation additionally requires run privileges.

Product API bridge tools use different catalog visibility rules. Invocation still requires authorization by the product API.
Catalog visibility does not necessarily grant the current identity permission to invoke a tool.

<span id="发布取消发布和查询状态"></span>

## Publish, unpublish, and read status

Only one active version may be published for each `identifier`. Publishing another version replaces the current version. Unpublishing removes only the publication associated with the current operator.

Disabling an operator hides its tool but may retain the publication record. `published` and `live_published`, together with enabled state, indicate tool visibility rather than whether a publication record exists.

Publishing, unpublishing, and status queries all return `code`, `msg`, and `data`. Data includes `operator_id`, `identifier`, `version`, `published`, and `live_published`. When an active version exists, it also includes `live_operator_id` and `live_version`. Business errors return only `code` and `msg`. Publishing a disabled operator currently returns `500` / `ErrServer`.

Replace `$OPERATOR_ID` with the custom operator ID.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Publish

```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} Unpublish

```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} Read status

```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} Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `operator_id` | integer | Yes | Custom operator ID in the request path. |

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

Publishing or unpublishing synchronously writes and reads status before returning. Errors may occur after a write. Query publication status before deciding whether to resubmit.

<span id="从-mcp-客户端调用已发布算子"></span>

## Invoke published operators from an MCP client

Calls to `tools/list` and `tools/call` must also include `X-Workspace-ID` exactly matching the path workspace. Initialization, notifications, and `ping` do not use the same tool-call checks.

The workspace endpoint for published tools is shown below. It uses stateless Streamable HTTP and JSON-RPC. Pass the personal access token through `X-API-Key` without also sending an `Authorization` header.

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

Initialize first, then call `tools/list` to retrieve tools available to the current caller. After initialization, send `notifications/initialized`. This notification returns HTTP `202` without a response body.

```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"
      }
    }
  }'
```

This endpoint does not support `GET` or `DELETE` and returns HTTP `405`.
