canvas · 29 tools · Mounted by default
Read a Canvas, build it up node by node, capture it as an image, and publish it.
Every call also carries an exit code and timing in _meta, and errors come back as results rather than transport failures. See Results.
canvas_archive
Hints — destructive Move a canvas to the trash. Archives a canvas (soft delete), cascading to the chats and files that live on it. Everything is restorable with canvas_restore — nothing is destroyed.
Returns — JSON, as text content and as structured content.
canvas_capture
Hints — read-only, idempotent Render a canvas to a webp image. It lets an agent see the canvas as drawn: check layout, overlaps, or how an edit came out. To show a canvas to a person, use canvas_view. The whole canvas is fit to the frame by default. To see a region as a person would, pass bounds (a rectangle in canvas coordinates, “x,y,width,height”) or node_ids; both take the coordinates and ids that canvas_view returns. The image carries the canvas ground and grid. background solid drops the grid; background transparent drops the ground too, for compositing. The render runs server-side and takes tens of seconds. At most one of: bounds, node_ids. The rendered webp is returned as an image block.
Returns — The rendered image inline as
image/webp, up to 3 MiB. Above that the result points you at cohesive_file_get and its signed download_url instead.
canvas_comment_get
Hints — read-only, idempotent Read one comment thread in full. Returns a thread’s summary line and its full transcript: every comment in order with its time, author, and comment id. An edited comment is marked, and a deleted one is shown as a tombstone rather than its text. Thread ids come from canvas_comment_list, or from canvas_view where a commentMarker node’s id is its thread id. A thread that is not on this canvas fails as not found. data carries the thread structured — comments[] with ids, authors, timestamps, and bodies — beside the prose in content.
Returns — JSON, as text content and as structured content.
canvas_comment_list
Hints — read-only, idempotent List a canvas’s comment threads. Lists the comment threads on a canvas, one block per thread: thread id, resolved state, comment count, placement (anchored to a node id, or free-floating at a coordinate), participants, who commented last and when, and a truncated preview of that newest comment. Read a thread in full with canvas_comment_get. mentions_me is matched after the fetch over a bounded number of pages, so the result says when more threads exist than it scanned. data carries the threads structured — ids, flags, placement, participants, timestamps, and the preview — beside the prose in content.
Returns — JSON, as text content and as structured content.
canvas_create
Hints — writes (no read-only or destructive hint) Create an empty canvas in a workspace. Creates a canvas. The workspace is the canvas’s home; folder files it into a folder of the workspace tree, the same tree file_mkdir and Library files use. Pass a folder path (“Onboarding”, “Clients/FAI/”) or the file-record id of a folder. The folder need not exist beforehand, though only file_mkdir keeps an empty one around. Without folder the canvas lands at the workspace root. Rename with canvas_rename, relocate with canvas_move, trash with canvas_archive. Put content on it with the canvas_node_add_* tools and canvas_edge_add.
Returns — JSON, as text content and as structured content.
canvas_edge_add
Hints — writes (no read-only or destructive hint) Add an edge between two nodes. Connects two nodes. source and target are NODE ids from canvas_view — never a file or entity id; for placed files and media the node id differs from the file id, and an edge to a non-node id is skipped. label puts short text at the midpoint (“depends on”). Handles (top, right, bottom, left) pin which side the edge leaves and enters; omit them to auto-route, set them for feedback loops and multi-edge pairs.
Returns — JSON, as text content and as structured content.
canvas_edge_delete
Hints — destructive Delete edges.
Returns — JSON, as text content and as structured content.
canvas_edge_update
Hints — destructive, idempotent Update an edge’s label or style.
Returns — JSON, as text content and as structured content.
canvas_edit
Hints — destructive Apply a batch canvas edit (the raw canvas-edit payload). Applies one canvas-edit call from raw JSON — the escape hatch for building a whole diagram, or several changes, in a single atomic round-trip. The payload is the canvas-edit action’s input, verbatim:{"nodes": [...], "delete_node_ids": [...], "edges": [...], "delete_edge_ids": [...]}
Each nodes[] entry is {entity | entity_id | id, position, width, height}; entity is one of canvas_text_note, canvas_text_label, canvas_shape, canvas_connector, or a generic remote record. payload is the canvas-edit object: {nodes, delete_node_ids, edges, delete_edge_ids}.
Returns — JSON, as text content and as structured content.
canvas_get
Hints — read-only, idempotent Return one canvas’s details. Returns a canvas. parent_path is where it sits in its workspace tree ("" at the root, otherwise a folder path); absent when the server does not report it, including a canvas shared directly from a workspace the account cannot view. Re-file it with canvas_move. view_url is the public URL to show a person; dashboard_url opens the canvas in the app for a signed-in user.
Returns — JSON, as text content and as structured content.
canvas_list
Hints — read-only, idempotent List accessible canvases. Lists every canvas the signed-in account can access, most recently modified first. With workspace, lists only that workspace’s canvases (unpaginated — limit does not apply). parent_path is where a canvas sits in its workspace tree ("" at the root, otherwise a folder path); absent when the server does not report it, including a canvas shared directly from a workspace the account cannot view.
Returns — JSON, as text content and as structured content.
canvas_move
Hints — destructive, idempotent Move a canvas to another workspace or folder. Relocates a canvas: workspace re-homes it to another workspace, folder files it into a folder of the workspace tree, root moves it back to the workspace root. The tree is the one file_mkdir and Library files use; folder takes a folder path (“Onboarding”, “Clients/FAI/”) or the file-record id of a folder. The folder need not exist beforehand, though only file_mkdir keeps an empty one around. Workspace and folder moves go in one request; workspace alone lands the canvas at the new workspace’s root. Filing takes edit rights on the workspace. At most one of: folder, root.
Returns — JSON, as text content and as structured content.
canvas_node_add_connector
Hints — writes (no read-only or destructive hint) Add a free-floating connector line between two points. Adds a connector: a line or arrow between two absolute canvas coordinates, attached to nothing. To connect two NODES so the link follows them, use canvas_edge_add instead — connectors are for freehand arrows and diagram lines between positions. Connectors take no position or size; their geometry is start and end. arrow_mode none|end|both presets the arrowheads; curve smooth, straight, or step (default, right-angle).
Returns — JSON, as text content and as structured content.
canvas_node_add_file
Hints — writes (no read-only or destructive hint) Place a file that exists. Places a file the platform already holds — a card deleted earlier, or a file from any workspace of the organization — and prints the same result as file_upload: file id, node id, path, display. The node id is what edges, moves and deletes take. A file already on the canvas is moved, not placed twice, and its node id comes back.
Returns — JSON, as text content and as structured content.
canvas_node_add_label
Hints — writes (no read-only or destructive hint) Add a text label (a single line of free-standing text). Adds a text label: one line of text directly on the canvas — headings, captions, annotations. Font sizes are 16px (default), 20px, 32px, 48px; keep content to roughly 8 words at 16-20px, 5 at 32px, 3 at 48px; a label auto-sizes to its text. Omit color for the theme-adaptive default (this is usually right). Colors are the spectrum palette: orange, yellow, green, blue, violet, mulberry, brown, indigo, olive.
Returns — JSON, as text content and as structured content.
canvas_node_add_note
Hints — writes (no read-only or destructive hint) Add a text note (a sticky with a title and markdown body). Adds a text note: a titled sticky holding markdown content. Notes default to 288x288; use 192 height for short notes and 384 for long ones. The title should be 2-6 words. Colors are the sticky palette: apricot, butter (default), meadow, sea, orchid, rose, clay, mist, oat.
Returns — JSON, as text content and as structured content.
canvas_node_add_record
Hints — writes (no read-only or destructive hint) Add a card for a record in a connected tool. Adds a card for a record that lives in another tool (slack, notion, github, …), built from the fields passed. platform and id name the record; placing the same platform id again moves the card it already has instead of adding a second one. The result carries the node id, which is what edges, moves and deletes take.
Returns — JSON, as text content and as structured content.
canvas_node_add_shape
Hints — writes (no read-only or destructive hint) Add a shape (rectangle, circle, diamond, triangle, pentagon, cylinder). Adds a shape, optionally with centered label text (content). Shapes default to 144x144; 192x96 works well for sequence-diagram boxes. fill takes the sticky palette (apricot, butter, meadow, sea, orchid, rose, clay, mist, oat); stroke takes the spectrum palette and defaults to the stroke paired with the fill. no_fill draws a stroke-only outline.
Returns — JSON, as text content and as structured content.
canvas_node_delete
Hints — destructive Delete nodes from a canvas. Deletes nodes by node id. Deleting a file’s node removes the card from the canvas; whether the file itself survives follows the platform’s file rules (a reference’s deletion removes only the reference).
Returns — JSON, as text content and as structured content.
canvas_node_get
Hints — read-only, idempotent Read nodes in full. Fetches the complete stored content of specific nodes — the full text of notes that canvas_view truncates, complete entity data, exact geometry. If a node’s content shows it is a file record (entity base “file_record”), the node holds only file METADATA: the file’s content is a different id and a different tool — read it with file_read file_record_id (metadata with file_get file_record_id). Passing a file id here fails and says so.
Returns — JSON, as text content and as structured content.
canvas_node_move
Hints — destructive, idempotent Move a node to a new position. Repositions one node by its node id (top-left corner, canvas coordinates, 16px lattice). Works for every node type, including files and media. Content is untouched.
Returns — JSON, as text content and as structured content.
canvas_node_resize
Hints — destructive, idempotent Resize a node. Resizes one node by its node id (dimensions in canvas units, 16px lattice). position moves it in the same call.
Returns — JSON, as text content and as structured content.
canvas_node_update
Hints — destructive, idempotent Update a node’s content or style. Updates a canvas-native node in place: pass only the properties to change; the rest of the node is untouched (the platform merges partially). The node’s current type decides which properties apply — title/content/color for notes and labels, fill/stroke/shape/content for shapes, start/end and the stroke properties for connectors. Only canvas-native nodes (notes, labels, shapes, connectors) update this way. A file’s content is edited through the file itself, and an HTML block through the file_* tools on its file id — the canvas card re-renders on its own.
Returns — JSON, as text content and as structured content.
canvas_publish
Hints — destructive, idempotent Publish a canvas to a public URL. Publishes a canvas as a read-only public snapshot — anyone with the URL can view it, no Cohesive account needed. The URL comes back as view_url and is the one to give a person; dashboard_url opens the canvas in the app for a signed-in user. Revoke with canvas_unpublish. Publishing runs server-side and takes a while (it rebuilds the snapshot and the social card), so this waits for it to finish and reports the outcome. The snapshot is a point-in-time copy: later canvas edits are not published until the canvas is published again. view_url is the public URL to show a person; dashboard_url opens the canvas in the app for a signed-in user.
Returns — JSON, as text content and as structured content.
canvas_raw
Hints — read-only, idempotent Return a canvas’s full content document. Returns the canvas’s full content document as{nodes, edges}, each keyed by id. Node and edge shapes follow the canvas frontend’s document model and are not a stable contract.
Full documents can be very large — survey with canvas_view first, then use node_ids here to fetch specific nodes in full.
Returns — JSON, as text content and as structured content.
canvas_rename
Hints — destructive, idempotent Rename a canvas.
Returns — JSON, as text content and as structured content.
canvas_restore
Hints — idempotent Restore an archived canvas.
Returns — JSON, as text content and as structured content.
canvas_unpublish
Hints — destructive Revoke a canvas’s public URL. Takes a published canvas offline: the public URL stops serving, and a publish still in flight is cancelled. The canvas itself is untouched.
Returns — JSON, as text content and as structured content.
canvas_view
Hints — read-only, idempotent Show a canvas inline. Hosts that support MCP Apps render an interactive board in the conversation; the result is also the canvas’s compact projection — identity, geometry, and semantic content with styling stripped and free text truncated — as node and edge tables. Use canvas_raw node_ids to fetch specific nodes in full. state adds each HTML block’s state summary as block_state; read the data with file_state_get.
Returns — JSON, as text content and as structured content.