Skip to content

Draw together on a whiteboard

When something is easier to draw than to describe (a layout, a flow, a rough diagram), your agent can show a whiteboard in the conversation. Members draw, write and place sticky notes on it together, live. Send to chat puts a PNG screenshot of the board in that member’s own message box, and Mark as done closes the board. Neither starts a turn for your agent: screenshots reach it only as ordinary messages, when a member sends them with a mention or in a thread it is part of. The tool is show_whiteboard, part of the Streams MCP server.

Members can also start a blank board themselves by typing /whiteboard [title] in the message box of a stream or a session. It posts the board as their own message and does not start a turn for your agent. A board a member started shows creationSource: "command" in its input; the agent tool never sets it.

show_whiteboard posts one board as a message from your agent.

  • One shared board. Everyone on the stream who can post there sees the same board and the same changes. People see each other’s cursors and who is on the board.
  • Mark as done closes it. The first person to press Mark as done closes the board for everyone. A later attempt by someone else is refused with 409 chat.ui_interaction_closed, and the response carries the view that won. Taking screenshots does not close the board.
  • Boards never expire. A board stays open until someone marks it as done, a stream admin dismisses it, or your agent cancels it. Deleting the board’s message closes it.
  • Same limit as forms. There is no limit on open boards. Boards and forms share a creation limit of 100 per agent per stream per minute; past it the call fails with chat.ui_interaction_rate_limited and the message says how long to wait.

The call returns immediately and nothing comes back by itself. Streams does not start a turn when the board is marked as done, so end your turn right after calling the tool and read the board with get_ui_interaction when you need it.

Field Type Notes
streamId UUID The stream to post in. Your agent must be a member.
replyToMessageId UUID, optional Put the board in the thread of that message. Without it the board is posted to the stream and opens its own thread.
threadSessionId UUID, optional Put the board in that thread, by its session id (the thread must be in streamId). With replyToMessageId too, it must be that thread’s first message.
title string 1 to 200 characters. Shown as the board’s heading.
intro string, optional Up to 2000 characters of plain text above the board. Keep it to one instruction line.
objects array, optional Up to 50 starter objects, so people begin from something instead of an empty board.

The canvas is 1200 by 720 pixels with the origin at the top left. Each object is one of:

  • { "type": "text", "x", "y", "text", "color" }
  • { "type": "sticky", "x", "y", "text", "fill" }, a 170 by 170 note
  • { "type": "line" | "arrow" | "rect" | "ellipse", "x1", "y1", "x2", "y2", "color", "width" }

Colors come from a fixed palette: #323338, #0073ea, #df2f4a, #00854d, #9d50dd, #e8710a. A sticky’s fill is the matching light tint: #fff1a8, #cce4ff, #ffd6dc, #c4f0dd, #e9d4fa, #ffe0b8. width is 2, 4 or 8. Text is at most 200 characters, and a sticky shows at most 5 lines. Pen strokes cannot be pre-placed.

{
"streamId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2e",
"title": "Sketch the onboarding flow",
"intro": "Draw the steps a new member goes through. Mark it as done when you are finished.",
"objects": [
{ "type": "text", "x": 60, "y": 40, "text": "Sign up", "color": "#323338" },
{
"type": "sticky",
"x": 60,
"y": 120,
"text": "Where do we ask for the team name?",
"fill": "#fff1a8"
},
{ "type": "arrow", "x1": 260, "y1": 200, "x2": 520, "y2": 200, "color": "#0073ea", "width": 4 }
]
}

The tool returns the interactionId, the messageId of the board’s message, status: "pending" and the input it stored. The board message also carries a one-line text caption (🎨 <title> (whiteboard)) for readers that cannot render it.

Pen, highlighter, eraser, line, arrow, rectangle, ellipse, sticky note and text, with six colors and three stroke widths. Anyone can move or delete any object, and Undo and Redo apply to each person’s own recent actions. Clear removes everything for everyone after a confirmation.

A board holds at most 500 objects at a time, and accepts at most 2,000 changes over its life (every stroke, move, delete and Clear counts). When either limit is reached people see “The board is full”, can no longer change it, and can still take a screenshot and mark the board as done.

Each member who presses Send to chat gets a 1200 by 720 PNG of the board attached to their own message box. They add text, send the message, and your agent sees it like any other message from that person. Several people can do this, any number of times, while the board stays open.

If a stream owner, or an organization owner or admin, dismisses the board, your agent gets a turn with status: "dismissed" and closedBy. If your agent cancels its own board, no turn is started. Marking the board as done starts no turn.

get_ui_interaction returns one board by the interactionId that show_whiteboard gave you: status (pending, submitted or cancelled), the input you asked, and once a member has marked it as done, respondedBy and response.whiteboard:

{
"revision": 42,
"epoch": 0,
"objectCount": 9,
"texts": [{ "kind": "sticky", "text": "Where do we ask for the team name?" }]
}

texts lists the text and sticky notes on the board in drawing order (at most 100 entries). The drawing itself is not stored as an image; ask members to send a screenshot if you need to see it.

manage_ui_interaction with action: "cancel" closes an open board you showed. It does not start a turn.

In Streams on web, desktop and mobile the board is native: everything above works live. Another MCP host that supports MCP Apps shows what you placed, read only, with a note saying to draw in the Streams conversation where it was shown. The view is ui://streams/whiteboard.