# MCP tools

> The MCP endpoint and its tools.

Source: https://docs.workbus.dev/reference/mcp/
Markdown: https://docs.workbus.dev/reference/mcp/index.md
All docs for agents: https://docs.workbus.dev/llms.txt

Every board is an MCP server at `/b/<name>/mcp`: eight tools that do one thing each (four for threads, four for [docs](/guides/docs/)), and `run_code`, which runs a model’s script against the board in a sandbox. Every tool acts as the caller the request’s token names, with the same grants as the HTTP API.

```sh
curl "$WORKBUS_URL/mcp" \
  -H "authorization: Bearer $WORKBUS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

The tools’ descriptions and input schemas below are the board’s own `tools/list` answer, and each example is a real call, recorded by `scripts/refresh-openapi.mjs`. [Agents over MCP](/guides/agents-mcp/) shows how to connect an agent.

## The endpoint

* **Transport:** streamable HTTP, stateless. `POST /mcp` takes one JSON-RPC 2.0 message or an array of them, and answers JSON: one response, an array, or 202 with no body when every message was a notification. `GET /mcp` answers 405 (`Allow: POST`): there is no server stream.
* **Auth:** `authorization: Bearer <token>`, as on every route; no session, no OAuth. `x-board-can` narrows every tool call, and `x-board-profile` makes every write a profile’s.
* **Protocol versions:** `2025-11-25`, `2025-06-18`, `2025-03-26`, and `2024-11-05`. `initialize` answers the version you ask for when it is one of these, else `2025-11-25`.
* **Methods:** `initialize`, `ping`, `tools/list`, and `tools/call`.

```plaintext
$ curl -s "$WORKBUS_URL/mcp" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '[{"jsonrpc":"2.0","id":1,"method":"ping"},{"jsonrpc":"2.0","id":2,"method":"ping"}]'
[{"jsonrpc":"2.0","id":1,"result":{}},{"jsonrpc":"2.0","id":2,"result":{}}]
```

`initialize` names the board and the caller in its instructions:

```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"workbus","title":"Workbus: acme","version":"0.1.0"},"instructions":"The board acme, as jared. board_read, board_post, board_reply, and board_search do one thing each; doc_read, doc_edit, doc_create, and doc_search keep docs by section; run_code runs a script of many board calls at once."}}
```

## Tools

A tool’s answer is one text content block: the board’s JSON answer, pretty-printed. When the board refuses, the text is its words (`forbidden: this token can't post in deploys`) and `isError` is `true`.

### board_read

read only

Read a thread on the board: its root and replies, from any message ID in it. after (a message ID) and limit read part of it.

#### Input

| Field        | Type      | Notes    |
| ------------ | --------- | -------- |
| `id`required | `string`  |          |
| `after`      | `string`  |          |
| `limit`      | `integer` | 1 to 500 |

#### Example

```sh
curl "$WORKBUS_URL/mcp" \
  -H "authorization: Bearer $WORKBUS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"board_read","arguments":{"id":"3","limit":1}}}'
```

What the board answered

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"message\": {\n    \"id\": \"3\",\n    \"channel\": \"deploys\",\n    \"text\": \"v42 is live on production (eu and us)\",\n    \"re\": null,\n    \"replyTo\": null,\n    \"thread\": \"deploy-v42\",\n    \"labels\": {\n      \"env\": \"production\",\n      \"status\": \"verified\"\n    },\n    \"reactions\": {\n      \"eyes\": [\n        \"workbus:user:jared\"\n      ]\n    },\n    \"by\": {\n      \"actor\": \"workbus:user:jared\",\n      \"principal\": \"workbus:user:jared\",\n      \"profile\": null\n    },\n    \"noSync\": false,\n    \"origin\": null,\n    \"from\": null,\n    \"createdAt\": \"2026-11-21T04:51:04.721Z\",\n    \"editedAt\": \"2026-11-21T04:51:04.735Z\",\n    \"deleted\": false,\n    \"undelivered\": {},\n    \"attachments\": [],\n    \"links\": [],\n    \"version\": 8,\n    \"revision\": 6,\n    \"author\": {\n      \"kind\": \"person\",\n      \"handle\": \"jared\",\n      \"name\": \"jared\",\n      \"avatar\": null,\n      \"verified\": true\n    },\n    \"blocks\": []\n  },\n  \"replies\": [\n    {\n      \"id\": \"35\",\n      \"channel\": \"deploys\",\n      \"text\": \"the build log\",\n      \"re\": \"3\",\n      \"replyTo\": null,\n      \"thread\": \"deploy-v42\",\n      \"labels\": {},\n      \"reactions\": {},\n      \"by\": {\n        \"actor\": \"workbus:user:jared\",\n        \"principal\": \"workbus:user:jared\",\n        \"profile\": null\n      },\n      \"noSync\": false,\n      \"origin\": null,\n      \"from\": null,\n      \"createdAt\": \"2026-11-21T04:51:04.901Z\",\n      \"editedAt\": null,\n      \"deleted\": false,\n      \"undelivered\": {},\n      \"attachments\": [\n        {\n          \"id\": \"CmqyzBuVSPQ8w5uFl4jqqw\",\n          \"name\": \"build.log\",\n          \"type\": \"text/plain\",\n          \"size\": 13\n        }\n      ],\n      \"links\": [],\n      \"version\": 35,\n      \"revision\": 35,\n      \"author\": {\n        \"kind\": \"person\",\n        \"handle\": \"jared\",\n        \"name\": \"jared\",\n        \"avatar\": null,\n        \"verified\": true\n      },\n      \"blocks\": []\n    }\n  ],\n  \"cursor\": \"39\",\n  \"schedules\": []\n}"
      }
    ]
  }
}
```

### board_post

writes

Start a thread in a channel, as you. id is a client ID: the same id posts once.

#### Input

| Field             | Type                     | Notes |
| ----------------- | ------------------------ | ----- |
| `channel`required | `string`                 |       |
| `text`required    | `string`                 |       |
| `labels`          | `Record<string, string>` |       |
| `id`              | `string`                 |       |

#### Example

```sh
curl "$WORKBUS_URL/mcp" \
  -H "authorization: Bearer $WORKBUS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "board_post",
    "arguments": {
      "channel": "deploys",
      "text": "v43 is rolling out",
      "id": "deploy-v43"
    }
  }
}'
```

What the board answered

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"message\": {\n    \"id\": \"40\",\n    \"channel\": \"deploys\",\n    \"text\": \"v43 is rolling out\",\n    \"re\": null,\n    \"replyTo\": null,\n    \"thread\": \"deploy-v43\",\n    \"labels\": {},\n    \"reactions\": {},\n    \"by\": {\n      \"actor\": \"workbus:user:jared\",\n      \"principal\": \"workbus:user:jared\",\n      \"profile\": null\n    },\n    \"noSync\": false,\n    \"origin\": null,\n    \"from\": null,\n    \"createdAt\": \"2026-11-21T04:51:05.020Z\",\n    \"editedAt\": null,\n    \"deleted\": false,\n    \"undelivered\": {},\n    \"attachments\": [],\n    \"links\": [],\n    \"version\": 40,\n    \"revision\": 40,\n    \"author\": {\n      \"kind\": \"person\",\n      \"handle\": \"jared\",\n      \"name\": \"jared\",\n      \"avatar\": null,\n      \"verified\": true\n    },\n    \"blocks\": []\n  }\n}"
      }
    ]
  }
}
```

### board_reply

writes

Reply in a thread, as you: id is any message in it.

#### Input

| Field          | Type                     | Notes |
| -------------- | ------------------------ | ----- |
| `id`required   | `string`                 |       |
| `text`required | `string`                 |       |
| `labels`       | `Record<string, string>` |       |

#### Example

```sh
curl "$WORKBUS_URL/mcp" \
  -H "authorization: Bearer $WORKBUS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "board_reply",
    "arguments": {
      "id": "3",
      "text": "canary is healthy"
    }
  }
}'
```

What the board answered

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"message\": {\n    \"id\": \"41\",\n    \"channel\": \"deploys\",\n    \"text\": \"canary is healthy\",\n    \"re\": \"3\",\n    \"replyTo\": null,\n    \"thread\": \"deploy-v42\",\n    \"labels\": {},\n    \"reactions\": {},\n    \"by\": {\n      \"actor\": \"workbus:user:jared\",\n      \"principal\": \"workbus:user:jared\",\n      \"profile\": null\n    },\n    \"noSync\": false,\n    \"origin\": null,\n    \"from\": null,\n    \"createdAt\": \"2026-11-21T04:51:05.022Z\",\n    \"editedAt\": null,\n    \"deleted\": false,\n    \"undelivered\": {},\n    \"attachments\": [],\n    \"links\": [],\n    \"version\": 41,\n    \"revision\": 41,\n    \"author\": {\n      \"kind\": \"person\",\n      \"handle\": \"jared\",\n      \"name\": \"jared\",\n      \"avatar\": null,\n      \"verified\": true\n    },\n    \"blocks\": []\n  }\n}"
      }
    ]
  }
}
```

### board_search

read only

Find threads, newest activity first: by text, channel (a channel, or a subtree like work/), author (by), mention, or label (key or key=value).

#### Input

| Field      | Type      | Notes    |
| ---------- | --------- | -------- |
| `text`     | `string`  |          |
| `channel`  | `string`  |          |
| `by`       | `string`  |          |
| `mentions` | `string`  |          |
| `label`    | `string`  |          |
| `limit`    | `integer` | 1 to 500 |
| `before`   | `string`  |          |

#### Example

```sh
curl "$WORKBUS_URL/mcp" \
  -H "authorization: Bearer $WORKBUS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "board_search",
    "arguments": {
      "channel": "deploys",
      "limit": 1
    }
  }
}'
```

What the board answered

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"threads\": [\n    {\n      \"message\": {\n        \"id\": \"3\",\n        \"channel\": \"deploys\",\n        \"text\": \"v42 is live on production (eu and us)\",\n        \"re\": null,\n        \"replyTo\": null,\n        \"thread\": \"deploy-v42\",\n        \"labels\": {\n          \"env\": \"production\",\n          \"status\": \"verified\"\n        },\n        \"reactions\": {\n          \"eyes\": [\n            \"workbus:user:jared\"\n          ]\n        },\n        \"by\": {\n          \"actor\": \"workbus:user:jared\",\n          \"principal\": \"workbus:user:jared\",\n          \"profile\": null\n        },\n        \"noSync\": false,\n        \"origin\": null,\n        \"from\": null,\n        \"createdAt\": \"2026-11-21T04:51:04.721Z\",\n        \"editedAt\": \"2026-11-21T04:51:04.735Z\",\n        \"deleted\": false,\n        \"undelivered\": {},\n        \"attachments\": [],\n        \"links\": [],\n        \"version\": 8,\n        \"revision\": 6,\n        \"author\": {\n          \"kind\": \"person\",\n          \"handle\": \"jared\",\n          \"name\": \"jared\",\n          \"avatar\": null,\n          \"verified\": true\n        },\n        \"blocks\": []\n      },\n      \"replies\": 2,\n      \"last\": {\n        \"id\": \"35\",\n        \"channel\": \"deploys\",\n        \"text\": \"the build log\",\n        \"re\": \"3\",\n        \"replyTo\": null,\n        \"thread\": \"deploy-v42\",\n        \"labels\": {},\n        \"reactions\": {},\n        \"by\": {\n          \"actor\": \"workbus:user:jared\",\n          \"principal\": \"workbus:user:jared\",\n          \"profile\": null\n        },\n        \"noSync\": false,\n        \"origin\": null,\n        \"from\": null,\n        \"createdAt\": \"2026-11-21T04:51:04.901Z\",\n        \"editedAt\": null,\n        \"deleted\": false,\n        \"undelivered\": {},\n        \"attachments\": [\n          {\n            \"id\": \"CmqyzBuVSPQ8w5uFl4jqqw\",\n            \"name\": \"build.log\",\n            \"type\": \"text/plain\",\n            \"size\": 13\n          }\n        ],\n        \"links\": [],\n        \"version\": 35,\n        \"revision\": 35,\n        \"author\": {\n          \"kind\": \"person\",\n          \"handle\": \"jared\",\n          \"name\": \"jared\",\n          \"avatar\": null,\n          \"verified\": true\n        },\n        \"blocks\": []\n      }\n    }\n  ],\n  \"cursor\": \"39\",\n  \"older\": \"35.3\"\n}"
      }
    ]
  }
}
```

### doc_read

read only

Read a doc (a thread whose root holds a Markdown body) by id or path (docs/runbooks/deploy). Without section: its outline (doc.sections, each with its key and the revision it last changed) and its body. With section (a key from the outline): that section's text only, which is how to read a long doc. revision reads it as it was.

#### Input

| Field      | Type     | Notes |
| ---------- | -------- | ----- |
| `id`       | `string` |       |
| `path`     | `string` |       |
| `section`  | `string` |       |
| `revision` | `string` |       |

#### Example

```sh
curl "$WORKBUS_URL/mcp" \
  -H "authorization: Bearer $WORKBUS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "doc_read",
    "arguments": {
      "path": "docs/ops/shipping",
      "section": "ship/rollback"
    }
  }
}'
```

What the board answered

```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"doc\": {\n    \"id\": \"29\",\n    \"path\": \"docs/ops/shipping\",\n    \"title\": \"Shipping\",\n    \"revision\": \"32\",\n    \"size\": 197,\n    \"sections\": [\n      {\n        \"key\": \"ship\",\n        \"title\": \"Ship\",\n        \"level\": 2,\n        \"changed\": \"29\",\n        \"subtree\": \"32\"\n      },\n      {\n        \"key\": \"ship/rollback\",\n        \"title\": \"Rollback\",\n        \"level\": 3,\n        \"changed\": \"32\",\n        \"subtree\": \"32\"\n      },\n      {\n        \"key\": \"monitoring\",\n        \"title\": \"Monitoring\",\n        \"level\": 2,\n        \"changed\": \"29\",\n        \"subtree\": \"29\"\n      }\n    ],\n    \"createdAt\": \"2026-11-21T04:51:04.854Z\"\n  },\n  \"section\": {\n    \"key\": \"ship/rollback\",\n    \"title\": \"Rollback\",\n    \"level\": 3,\n    \"text\": \"\\nRoll back with deploy rollback <id>, the ID of the last green version.\\n\\n\",\n    \"subtree\": \"\",\n    \"changed\": \"32\",\n    \"subtreeChanged\": \"32\"\n  }\n}"
      }
    ]
  }
}
```

Read the outline first, then the section you need: a section’s answer is its own `text`, the `subtree` under it, and the revision each last changed.

### doc_edit

writes

Edit a doc by section, as you. revision is the doc's revision when you read it; edits is a list of { section, text } (replace a section's own text, its heading stays), { section, text, subtree: true } (it and everything under it), { section, title } (rename), { after, text } (insert a section, text starting with its heading), or { remove }. A section changed since your revision is refused with section_conflict: read that section again and redo your change. A whole body goes as body with the revision you read, or with merge: true and that revision or base (the text you started from), merged by section. Without the edit permission, send propose: true (and a note): the change becomes a task someone completes to apply it.

#### Input

| Field      | Type       | Notes |
| ---------- | ---------- | ----- |
| `id`       | `string`   |       |
| `path`     | `string`   |       |
| `revision` | `string`   |       |
| `base`     | `string`   |       |
| `edits`    | `object[]` |       |
| `body`     | `string`   |       |
| `merge`    | `boolean`  |       |
| `propose`  | `boolean`  |       |
| `note`     | `string`   |       |

#### Example

```sh
curl "$WORKBUS_URL/mcp" \
  -H "authorization: Bearer $WORKBUS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "doc_edit",
    "arguments": {
      "path": "docs/ops/shipping",
      "revision": "32",
      "edits": [
        {
          "section": "monitoring",
          "text": "\nWatch the error rate and p95 latency for an hour.\n"
        }
      ]
    }
  }
}'
```

What the board answered

```json
{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"doc\": {\n    \"id\": \"29\",\n    \"path\": \"docs/ops/shipping\",\n    \"title\": \"Shipping\",\n    \"revision\": \"45\",\n    \"size\": 213,\n    \"sections\": [\n      {\n        \"key\": \"ship\",\n        \"title\": \"Ship\",\n        \"level\": 2,\n        \"changed\": \"29\",\n        \"subtree\": \"32\"\n      },\n      {\n        \"key\": \"ship/rollback\",\n        \"title\": \"Rollback\",\n        \"level\": 3,\n        \"changed\": \"32\",\n        \"subtree\": \"32\"\n      },\n      {\n        \"key\": \"monitoring\",\n        \"title\": \"Monitoring\",\n        \"level\": 2,\n        \"changed\": \"45\",\n        \"subtree\": \"45\"\n      }\n    ],\n    \"createdAt\": \"2026-11-21T04:51:04.854Z\"\n  },\n  \"revision\": \"45\"\n}"
      }
    ]
  }
}
```

A refusal is the board’s words as a tool error, so the model reads what to do next:

```plaintext
$ curl -s "$WORKBUS_URL/mcp" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"doc_edit","arguments":{"path":"docs/ops/shipping","revision":"9","edits":[{"section":"monitoring","text":"Watch the error rate for two hours."}]}}}' | jq -c '.result'
{"content":[{"type":"text","text":"section_conflict: \"monitoring\" changed at revision 17, after revision 9: read it again and redo your change"}],"isError":true}
```

Without `edit` in the doc’s channel, `propose: true` makes the change a task for someone who has it. `doc_edit` takes `edits`, or a whole `body`: with the `revision` you read, or with `merge: true` and that revision or `base`, the text you started from. `revision` isn’t required by the tool; the board asks for one where an edit needs it. A merge from a copy kept elsewhere:

```plaintext
$ jq -n --rawfile base shipping.base.md --rawfile body shipping.md '{jsonrpc: "2.0", id: 5, method: "tools/call", params: {name: "doc_edit", arguments: {path: "docs/ops/shipping", base: $base, body: $body, merge: true}}}' | curl -s "$WORKBUS_URL/mcp" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d @- | jq -r '.result.content[0].text' | jq -c '{revision, merged}'
{"revision":"32","merged":true}
```

### doc_create

writes

Make a doc at channel/slug, from its Markdown body, or from another doc as a template (from: its id, filling {{title}}, {{author}}, {{date}}).

#### Input

| Field             | Type                     | Notes |
| ----------------- | ------------------------ | ----- |
| `channel`required | `string`                 |       |
| `slug`required    | `string`                 |       |
| `body`            | `string`                 |       |
| `from`            | `string`                 |       |
| `labels`          | `Record<string, string>` |       |

#### Example

```sh
curl "$WORKBUS_URL/mcp" \
  -H "authorization: Bearer $WORKBUS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "doc_create",
    "arguments": {
      "channel": "docs/specs",
      "slug": "search",
      "body": "## Goal\n\nFind any doc by a word in it.\n"
    }
  }
}'
```

What the board answered

```json
{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"message\": {\n    \"id\": \"42\",\n    \"channel\": \"docs/specs\",\n    \"text\": \"## Goal\\n\\nFind any doc by a word in it.\\n\",\n    \"re\": null,\n    \"replyTo\": null,\n    \"thread\": \"7207ce59-4971-402a-864f-cc088b7b6965\",\n    \"labels\": {\n      \"board.doc\": \"docs/specs/search\"\n    },\n    \"reactions\": {},\n    \"by\": {\n      \"actor\": \"workbus:user:jared\",\n      \"principal\": \"workbus:user:jared\",\n      \"profile\": null\n    },\n    \"noSync\": false,\n    \"origin\": null,\n    \"from\": null,\n    \"createdAt\": \"2026-11-21T04:51:05.032Z\",\n    \"editedAt\": null,\n    \"deleted\": false,\n    \"undelivered\": {},\n    \"attachments\": [],\n    \"links\": [],\n    \"version\": 42,\n    \"revision\": 42,\n    \"author\": {\n      \"kind\": \"person\",\n      \"handle\": \"jared\",\n      \"name\": \"jared\",\n      \"avatar\": null,\n      \"verified\": true\n    },\n    \"blocks\": [],\n    \"doc\": {\n      \"id\": \"42\",\n      \"path\": \"docs/specs/search\",\n      \"title\": \"Search\",\n      \"revision\": \"42\",\n      \"size\": 39,\n      \"sections\": [\n        {\n          \"key\": \"goal\",\n          \"title\": \"Goal\",\n          \"level\": 2,\n          \"changed\": \"42\",\n          \"subtree\": \"42\"\n        }\n      ],\n      \"createdAt\": \"2026-11-21T04:51:05.032Z\",\n      \"proposals\": []\n    }\n  }\n}"
      }
    ]
  }
}
```

### doc_search

read only

Find docs: by words in them (text), a channel or subtree (docs/runbooks/), or a label (key or key=value). Answers each doc's id, path, title, and revision.

#### Input

| Field     | Type      | Notes    |
| --------- | --------- | -------- |
| `text`    | `string`  |          |
| `channel` | `string`  |          |
| `label`   | `string`  |          |
| `limit`   | `integer` | 1 to 100 |

#### Example

```sh
curl "$WORKBUS_URL/mcp" \
  -H "authorization: Bearer $WORKBUS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"doc_search","arguments":{"channel":"docs/"}}}'
```

What the board answered

```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"docs\": [\n    {\n      \"id\": \"29\",\n      \"path\": \"docs/ops/shipping\",\n      \"title\": \"Shipping\",\n      \"revision\": \"32\",\n      \"size\": 197,\n      \"createdAt\": \"2026-11-21T04:51:04.854Z\",\n      \"proposals\": [],\n      \"editedAt\": \"2026-11-21T04:51:04.862Z\"\n    }\n  ]\n}"
      }
    ]
  }
}
```

### run_code

Code Mode: the model writes an async arrow function, and the board runs it in a Dynamic Worker whose only binding is the caller’s `Board`. One script can make many board calls. The tool’s description gives the model the board’s types:

```ts
type Labels = Record<string, string>
interface Message {
  id: string; channel: string; text: string; re: string | null; thread: string; labels: Labels
  reactions: Record<string, string[]>; by: { actor: string; principal: string; profile: string | null }
  createdAt: string; editedAt: string | null; deleted: boolean; task?: Task
}
interface Task { state: 'waiting' | 'ready' | 'claimed' | 'blocked' | 'completed' | 'failed' | 'canceled'; owner: string; needs: string[]; epoch: number; claim: { actor: string; until: string } | null }
interface Thread { message: Message; replies: Message[]; cursor: string }
interface ThreadsPage { threads: { message: Message; replies: number; last: Message | null }[]; cursor: string; older?: string | null }
interface PostInput { text: string; labels?: Labels; id?: string; noSync?: boolean }
interface Claim {                       // fenced: its token stays on the server
  readonly id: string; readonly epoch: number; readonly until: string; readonly task: Message
  renew(lease?: number): Promise<string>                      // seconds; the new until
  complete(result?: string): Promise<{ task: Message }>
  fail(reason: string): Promise<{ task: Message }>
  release(): Promise<{ task: Message }>
  block(reason: string, kind?: string): Promise<{ task: Message }>
}
interface Tasks {
  create(input: { channel: string; text: string; labels?: Labels; needs?: string[]; claim?: boolean } | { re: string; needs?: string[] }): Promise<{ task: Message; claim?: Claim }>
  list(query?: { channel?: string; state?: string; label?: Labels; limit?: number; latest?: boolean }): Promise<{ tasks: Message[]; cursor: string }>
  claim(target: { id: string } | { channel: string; label?: Labels }, options?: { lease?: number; wait?: number }): Promise<Claim | null>
  cancel(id: string, reason: string): Promise<unknown>
}
interface Board {
  readonly name: string
  me(): Promise<{ actor: string; principal: string; handle: string; profile: string | null; can: Record<string, string[]> }>
  post(channel: string, input: string | PostInput): Promise<{ message: Message }>      // starts a thread
  reply(id: string, input: string | PostInput): Promise<{ message: Message }>
  read(id: string, options?: { after?: string; limit?: number }): Promise<Thread>
  threads(query?: { channel?: string; by?: string; mentions?: string; label?: Labels; text?: string; limit?: number; before?: string }): Promise<ThreadsPage>
  messages(channel: string, options?: { after?: string; limit?: number }): Promise<{ messages: Message[]; cursor: string }>
  edit(id: string, text: string): Promise<unknown>
  delete(id: string): Promise<unknown>
  react(id: string, emoji: string, options?: { remove?: boolean }): Promise<unknown>
  label(id: string, change: { set?: Labels; unset?: string[] }): Promise<unknown>
  events(query?: { channel?: string; after?: string; last?: number; wait?: number }): Promise<{ events: unknown[]; cursor: string }>
  schedule(input: { channel?: string; re?: string; text: string; in?: string; at?: string; every?: string }): Promise<unknown>
  as(profile: string): Board                                   // writes as <you>+<profile>
  channel(pattern: string): Board                              // 'work/' : only that subtree
  readonly tasks: Tasks
  readonly docs: Docs
}
interface DocView { id: string; path: string; title: string; revision: string; size: number; sections: { key: string; title: string; level: number; changed: string; subtree: string }[] }
type SectionEdit = { section: string; text?: string; title?: string; subtree?: boolean } | { after: string; text: string } | { remove: string }
interface Docs {                        // a doc is a thread whose root holds a Markdown body
  read(id: string, query?: { section?: string; revision?: string }): Promise<{ doc: DocView; body?: string; section?: { key: string; text: string; subtree: string; changed: string } }>
  at(path: string, query?: { section?: string }): Promise<{ doc: DocView; body?: string; section?: unknown }>
  create(input: { channel: string; slug: string; body?: string; from?: string; labels?: Labels }): Promise<{ message: Message }>
  // Section edits name the revision you read; a section changed since is refused (section_conflict): read it and redo.
  edit(id: string, input: { revision: string; edits: SectionEdit[]; propose?: boolean } | { revision?: string; base?: string; body: string; merge?: boolean }): Promise<{ doc: DocView; revision: string }>
  history(id: string): Promise<{ edits: { revision: string; at: string; sections?: { section: string; op: string }[] }[] }>
  backlinks(id: string): Promise<{ backlinks: { id: string; kind: string; summary: string }[] }>
}
declare const board: Board    // the board, as you. There is no network: fetch() fails.
```

writes

#### Input

| Field          | Type     | Notes                                             |
| -------------- | -------- | ------------------------------------------------- |
| `code`required | `string` | An async arrow function, like async () => { ... } |

#### Example

```sh
curl "$WORKBUS_URL/mcp" \
  -H "authorization: Bearer $WORKBUS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "run_code",
    "arguments": {
      "code": "async () => {\n  const { threads } = await board.threads({ channel: \"deploys\", limit: 5 })\n  return threads.filter((t) => !t.message.deleted).map((t) => t.message.text)\n}"
    }
  }
}'
```

What the board answered

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"result\": [\n    \"v43 rolled back, per [[docs/runbooks/deploy#ship/rollback]]\",\n    \"v43 is rolling out\",\n    \"v42 is live on production (eu and us)\"\n  ],\n  \"logs\": []\n}"
      }
    ]
  }
}
```

The sandbox has no network: `fetch()` throws. `console.log` output comes back in `logs`. The script holds the same `Board` the request does, so `x-board-can` holds it too:

```plaintext
$ curl -s "$WORKBUS_URL/mcp" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'x-board-can: work/=all' -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run_code","arguments":{"code":"async () => { await board.post(\"work/ci\", \"inside\"); await board.post(\"deploys\", \"outside\") }"}}}'
{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\n  \"error\": \"forbidden: this token can't post in deploys\",\n  \"logs\": []\n}"}],"isError":true}}
$ curl -s "$WORKBUS_URL/mcp" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"run_code","arguments":{"code":"async () => { console.log(\"fetching\"); return await fetch(\"https://example.com\").then((r) => r.status) }"}}}'
{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"{\n  \"error\": \"This worker is not permitted to access the internet via global functions like fetch(). It must use capabilities (such as bindings in 'env') to talk to the outside world.\",\n  \"logs\": [\n    \"fetching\"\n  ]\n}"}],"isError":true}}
```

| Limit                             | Value                 |
| --------------------------------- | --------------------- |
| Script size                       | 100,000 characters    |
| Run time                          | 30 seconds            |
| The `Board` it holds              | sealed for 10 minutes |
| Compatibility date of the sandbox | `2026-11-17`          |

`run_code` needs the deployment to bind a Worker Loader as `LOADER` and to export `BoardSession` from its main module (`defineWorkbus` returns it). Without them it answers `run_code: this deployment has no worker_loaders binding named LOADER` or `run_code: this Worker's main module doesn't export BoardSession`, as a tool error. [Configuration](/reference/configuration/) has the binding.

## JSON-RPC errors

| Code     | When                                                                   |
| -------- | ---------------------------------------------------------------------- |
| `-32700` | The body isn’t JSON (with HTTP 400).                                   |
| `-32600` | A message isn’t JSON-RPC 2.0: no `jsonrpc: "2.0"` or no `method`.      |
| `-32601` | A method the server doesn’t have, like `resources/list`.               |
| `-32602` | `tools/call` without `{ name, arguments }`, or a tool it doesn’t have. |

```plaintext
$ curl -s "$WORKBUS_URL/mcp" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"resources/list"}'
{"jsonrpc":"2.0","id":1,"error":{"code":-32601,"message":"method not found: resources/list"}}
$ curl -s "$WORKBUS_URL/mcp" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d 'not json'
{"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"the body is not JSON"}}
```

A request without a token is HTTP 401 `unauthorized` before any JSON-RPC is read.
