# CanvasView

> CanvasView is a hosted service where your AI agent builds a canvas of components that people open by link and work on together. The agent reads back their answers and shared state.

Agents connect over MCP and create canvases from building blocks (notes, tables, charts, decisions, forms, checklists, approvals, calculators) or their own sandboxed React components. People open the link, work on the canvas together, and submit structured answers.

## Connect

- MCP endpoint (Streamable HTTP): https://app.canvasview.dev/mcp. Clients that support MCP OAuth, such as Claude Code and Codex, sign in through the browser.
- Scripts and headless agents can send a CanvasView API key (`cvk_...`) as `Authorization: Bearer`. Create keys at https://app.canvasview.dev/settings/keys.
- Claude Code plugin 0.9.0: https://canvasview.dev/canvasview-plugin.zip. Codex plugin: https://canvasview.dev/canvasview-codex-plugin.zip.
- Pricing: creating a canvas costs $0.50. Each canvas includes 10 updates; later updates cost $0.05; a patch that only changes data is free. Validating, reading, arranging, examples, shared state and the component library are free. The default daily spending cap is $25.00.

## Get it right the first time

- Start from a working input: `list_examples` and `get_example` return the complete `create_canvas` inputs listed under Examples.
- Check before you pay: `validate_canvas` takes a `create_canvas`, `update_canvas` or `patch_canvas` input, runs every check the real call runs, and returns `{ valid, checked, issues: [{ path, message, code }] }` with `priceMicroUsd` when valid. It creates, holds and charges nothing.
- Errors say what is wrong, where, and what to change. Errors about an option or an import list the allowed values.

## Tools

- create_canvas: Create a shared canvas from catalog widgets or sandboxed React TSX components.
- update_canvas: Replace the canvas spec using the current base version.
- patch_canvas: Change part of a canvas without resending it: use it for small changes and data refreshes, and update_canvas to replace the whole canvas.
- validate_canvas: Check a create_canvas, update_canvas or patch_canvas input without creating or changing anything.
- arrange_canvas: Arrange nodes on a canvas without resending it.
- get_canvas: Read an account canvas, its current version, its access (mode, invite list, visibility and linkRole) with who: a summary of who can do what (link, members, each invited address, owner and Admins), the layout (position and size) of each node, the components view arrangement (panes) the default view, and role: this key's role on the canvas (editor, or admin for the owner's or an Admin's key).
- list_canvas_viewers: List who opened a canvas, most recent first: name, email (signed-in people, verified), verified (false for anonymous link viewers, listed by the name they typed, one entry per browser), access (owner, admin, organization, invited or viewer), firstAt and lastAt.
- set_canvas_access: Change who may open a canvas, who in the organization sees it, or both.
- find_canvas_by_key: Recover the result of a create call using its original idempotency key.
- list_canvases: List recent canvases you can see with status, expiry, access, visibility, owner (email, null with ownerFormer: true when the owner left the organization) and owned (yours), access (how you have access: owner, admin or organization), answers (how many were submitted), agent (the key or connection that created it), viewers ({ count, latestAt } on canvases you own, or all for an Admin), pinned (kept permanently), plus how many canvases the account keeps.
- get_answers: Read structured answers already submitted.
- wait_for_answer: Wait up to 60 seconds (default 15) for a structured answer, and return { status, answers } as soon as there is one or the canvas is no longer active.
- list_events: List this account's canvas events after a cursor, oldest first: answer.submitted, state.changed (at most one per canvas every 5 seconds), change.requested (a person asked you for a change in a comment), comment.added (people commented; at most one per canvas every 5 seconds), canvas.closed, canvas.expired, canvas.deleted and canvas.removed.
- wait_for_event: Wait up to 60 seconds (default 15) for the next canvas event in this account, across the canvases this key can see or one canvasId, and return as soon as one exists, in the shape of list_events ({ events, next }; empty events at the timeout; limit 1 to 200, default 50).
- close_canvas: Close a canvas to new answers and updates.
- extend_canvas: Set a canvas's expiry to expiresInHours from now (1 to 2160, 90 days).
- pin_canvas: Keep a canvas permanently (pinned: true) or let it expire again (pinned: false).
- delete_canvas: Delete a canvas permanently, at once: its content, answers and shared state are erased, open viewers are disconnected and the link stops working.
- get_canvas_state: Read the canvas's shared state: every key with its JSON value, version, who last changed it, and when.
- set_canvas_state: Set up to 20 shared state keys on an active canvas.
- list_comments: Read the comments on a canvas, oldest first, yours included.
- add_comment: Add a comment to an active canvas: on the whole canvas, pinned to nodeId, or a reply to a thread with replyTo (replies are one level deep; a reply to a reply joins the same thread, on its node).
- list_canvas_changes: Read a canvas's change log, newest first: each line is { id, at, kind, by: who made it (a person, an agent's key or CanvasView), version, summary, detail? }.
- get_canvas_lock: Read who holds a canvas's editing lock: { held, by, expiresAt }.
- acquire_canvas_lock: Take a canvas's editing lock for this key, or keep it for another minute if this key already holds it.
- release_canvas_lock: Let go of a canvas's editing lock so the next editor need not wait for it to run out.
- get_repository: Read a canvas's repository: every canvas has one Git repository holding its spec, components and tools, where each version of the canvas is a commit.
- get_repository_token: Get a short-lived token to clone a canvas's repository and push to it: { name, remote, branch, username, token, scope, expiresAt }.
- pull_repository: After pushing to a canvas's repository, have the canvas read its newest commit, run every tool in it through the gate, and make that commit live if all pass.
- list_tools: List a canvas's live tools: { tools: [{ name, purpose, kind (call, poll or stream), input, output, intervalSeconds?, available, commit }] }.
- call_tool: Run one of a canvas's live tools and return { output }.
- test_tool: Dry-run one tool through the gate without making anything live.
- publish_tools: Commit tools to a canvas's repository and make that commit live, if every tool in it passes the gate.
- get_tool_log: Read a canvas's newest tool calls: { kept, calls: [{ id, tool, commit, triggeredBy, by, sources, outcome, durationMs, requestBytes, responseBytes, at }], tools: [{ name, commit, status, reason, calls, failures }] }.
- get_action_log: Read who acted in the organization's systems through a canvas, newest first: each tool call a person made, and each data source write (POST, PUT, PATCH, DELETE) sent for one, from a component or by a tool during their call, as { actions: [{ id, kind: call or write, at, by: { userId, email, name, standing: invited, organization, owner or admin }, tool, call, source, method, path, status, outcome }], next, refused: { count, latestAt }, kept }.
- list_widgets: List available versioned widgets.
- get_kit_reference: Read widget props, TSX requirements, and answer hooks for sandboxed components, and this organization's design for its canvases and its rules for agents when it has set them.
- get_skill: Read CanvasView's how-to guides: creating a canvas, building a component or an app, arranging a canvas, working with people on one, and recovering from errors.
- list_examples: List complete, working create_canvas inputs to start from, each with a one-line description: a decision with evidence, a data review, an approval, a group poll, a workspace with a board, a custom component with shared state and more.
- get_example: Read one example by name: its description and complete create_canvas input.
- save_component: Save a reusable TSX component to this account's private library, checked as create_canvas checks components.
- search_components: Search this account's saved components by name and description, most used first.
- get_component: Read a saved component with its full source, to reuse or fork it.
- delete_component: Delete a saved component.
- save_template: Save a canvas as a reusable template in this account's private library: its spec with the data replaced by parameters.
- search_templates: Search this account's saved canvas templates by name and description, most used first.
- get_template: Read a saved template with its spec, placeholders included, and its parameters.
- delete_template: Delete a saved template.
- list_data_sources: List the data sources the account owner approved, which a component may call through CanvasView with useData or fetchData from @canvasview/kit: each name, host, allowed methods (GET only unless the owner enabled writes), path prefix and the names of the secret headers CanvasView adds (never their values).
- request_data_source: Ask the account owner to approve a data source a component needs: name (what dataSources and useData will call it), baseUrl (HTTPS, a public host) and reason (shown to the owner).
- list_notifications: Read the account owner's CanvasView notifications, actions first, then newest first: each has kind (data_source.removed, data_source.requested, webhook.disabled, canvas.sign_in, canvas.removed, canvas.tool_failing or operator.message), severity (info, warning or action: something the owner must do), title, body, link (a CanvasView path), canvasId, createdAt and readAt.
- get_balance: Read the account balance in integer micro-USD.
- send_feedback: Send feedback about a missing CanvasView capability.

## Reference

- [Tool reference](https://app.canvasview.dev/agents/tools.md): every tool with its input fields
- [Kit reference](https://app.canvasview.dev/agents/kit.md): building blocks, props, hooks and layout
- [Error codes](https://app.canvasview.dev/agents/errors.md): what each error means
- [Documentation](https://docs.canvasview.dev/): guides for people and agents

## Examples

Complete `create_canvas` inputs, also returned by `get_example`. Use a fresh `idempotencyKey` for each canvas you create.

- [approval](https://app.canvasview.dev/agents/examples/approval.json): An approval of a document, with the clauses that need attention highlighted. Only invited people can open it.
- [calculator-decision](https://app.canvasview.dev/agents/examples/calculator-decision.json): A shared calculator to explore the numbers, then a decision on the plan.
- [checklist-review](https://app.canvasview.dev/agents/examples/checklist-review.json): A team works through a shared checklist live, then the lead records go or no-go.
- [contract-app](https://app.canvasview.dev/agents/examples/contract-app.json): An app of three components sharing state under a contract: loan inputs, a calculation that writes the results, and a balance chart. The canvas refuses writes outside each role.
- [custom-component-shared-state](https://app.canvasview.dev/agents/examples/custom-component-shared-state.json): One custom component that keeps an idea list in shared state, so everyone sees the same list, and drafts the top idea as the answer.
- [data-review](https://app.canvasview.dev/agents/examples/data-review.json): A data review: headline numbers, a table and a chart, with a short form for the verdict.
- [decision-with-evidence](https://app.canvasview.dev/agents/examples/decision-with-evidence.json): One choice between vendors, with the evidence beside it and a required reason.
- [group-poll](https://app.canvasview.dev/agents/examples/group-poll.json): A team votes live on one question, one vote each; the organiser closes voting and submits the result.
- [workspace](https://app.canvasview.dev/agents/examples/workspace.json): A launch workspace with no answer: a shared board people keep working on and a status table the agent refreshes with patch_canvas.