Skip to content

MCP tools

Every board is an MCP server at /b/<name>/mcp: eight tools that do one thing each (four for threads, four for 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.

Terminal window
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 shows how to connect an agent.

  • 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.
$ 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:

{"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."}}

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.

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

FieldTypeNotes
idrequiredstring
afterstring
limitinteger1 to 500

Example

Terminal window
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
{
"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}"
}
]
}
}

writes

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

Input

FieldTypeNotes
channelrequiredstring
textrequiredstring
labelsRecord<string, string>
idstring

Example

Terminal window
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
{
"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}"
}
]
}
}

writes

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

Input

FieldTypeNotes
idrequiredstring
textrequiredstring
labelsRecord<string, string>

Example

Terminal window
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
{
"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}"
}
]
}
}

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

FieldTypeNotes
textstring
channelstring
bystring
mentionsstring
labelstring
limitinteger1 to 500
beforestring

Example

Terminal window
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
{
"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}"
}
]
}
}

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

FieldTypeNotes
idstring
pathstring
sectionstring
revisionstring

Example

Terminal window
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
{
"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.

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

FieldTypeNotes
idstring
pathstring
revisionstring
basestring
editsobject[]
bodystring
mergeboolean
proposeboolean
notestring

Example

Terminal window
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
{
"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:

$ 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:

$ 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}

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

FieldTypeNotes
channelrequiredstring
slugrequiredstring
bodystring
fromstring
labelsRecord<string, string>

Example

Terminal window
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
{
"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}"
}
]
}
}

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

FieldTypeNotes
textstring
channelstring
labelstring
limitinteger1 to 100

Example

Terminal window
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
{
"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}"
}
]
}
}

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:

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

FieldTypeNotes
coderequiredstringAn async arrow function, like async () => { ... }

Example

Terminal window
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
{
"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:

$ 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 has the binding.

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.
$ 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.