cnvs.app exposes a public Model Context Protocol endpoint at https://cnvs.app/mcp. Streamable HTTP transport, JSON-RPC 2.0 over POST, server-pushed notifications over a GET SSE stream.
https://cnvs.app/mcp2025-06-18{
"mcpServers": {
"cnvs": {
"type": "http",
"url": "https://cnvs.app/mcp"
}
}
}
claude mcp add --transport http cnvs https://cnvs.app/mcp
open_board(url_or_id) — resolves the board ID, creates a missing board, and tries to subscribe the calling session to state.json. Use when creation and subscription are acceptable. The auto_subscribed field reports the outcome. Call resources/subscribe explicitly to confirm registration for long-lived push.get_board(board_id) — reads an existing board’s JSON snapshot and can refresh its inactivity timestamp. Heavy base64 payloads (>8 kB) are elided.get_preview(board_id) — reads an existing board’s schematic SVG preview. Mermaid nodes appear as placeholders in this preview. Open the board in the browser to see the rendered diagrams.add_text({...}), add_image({...}), draw_stroke({...}) — create items and can overwrite existing items when you pass their IDs. add_link({...}) creates a new URL capsule.move({board_id, id, kind?, x, y}) — reposition; kind ∈ text | link | line | image.erase({board_id, id, kind}) — delete one item. Use text for text and URL capsules, line for strokes, and image for images.wait_for_update({board_id, timeout_ms?}) — long-poll for the next edit. Clamped to [1000, 55000]; default 25000.Text writes through add_text and the REST text endpoint require non-blank content. Use erase to remove a text item through MCP.
cnvs://board/{id}/state.json — full JSON snapshot. Subscribable.cnvs://board/{id}/preview.svg — compact SVG render. Read-only.cnvs://board/{id}/tasks.json — Kanban columns, tasks, and lanes. Subscribable.Resource reads and subscriptions to state or task updates follow the board’s read permissions.
POST /mcp initialize → server returns Mcp-Session-Id header.GET /mcp with Accept: text/event-stream + Mcp-Session-Id: <id> opens the SSE stream.POST /mcp resources/subscribe { uri: "cnvs://board/{id}/state.json" } with the same session id registers the subscription.notifications/resources/updated JSON-RPC messages onto the SSE stream ~3 s after every edit burst settles (debounced — one wake-up per burst, not per mutation).: SSE comment every 25 s keeps intermediaries from closing the stream.Durability: the debounce timer uses the Durable Object alarm API, so even if the DO is evicted between a mutation and the 3 s window the alarm still wakes it up. Subscriber lists are persisted in DO storage.
In a host with the cnvs.app MCP integration, use the named MCP tools so the host can apply tool permissions and confirmations. A standalone client can combine MCP subscriptions with direct REST writes.
cnvs://board/<id>/state.json. The server pushes within ~3 s of every edit. This is the only way to get a push — REST has no webhook.POST /api/boards/<id>/{texts,strokes,images,links}. Both interfaces use the same server-side board validation and broadcast path.mcp-listen skill's --ignore-author-prefix "ai:" suppresses notifications caused by any ai:* author so your own writes don't wake your own listener.mcp-listen (for humans)mcp-listen is an optional Agent Skill that turns MCP subscription pushes into in-chat notifications in Claude Code (via its Monitor tool), so the model reacts to your edits without you typing. It is a single dependency-free Node.js 18+ script — no npm, no packages. You install it: AI agents connected to cnvs.app are told to suggest this page, never to download or install anything themselves.
Install from the immutable, versioned URL and verify the checksums before use:
# Run these yourself (pinned version, no npm, Node.js 18+). Files are downloaded
# into a temporary staging dir and only moved into ~/.claude/skills/mcp-listen
# if every checksum matches. On Linux replace `shasum -a 256 -c` with `sha256sum -c`.
stage="$(mktemp -d)" && cd "$stage" && mkdir scripts \
&& curl -fsSLO https://cnvs.app/mcp-listen/v0.4.0/SKILL.md \
&& curl -fsSLO https://cnvs.app/mcp-listen/v0.4.0/SHA256SUMS \
&& curl -fsSL -o scripts/listen.mjs https://cnvs.app/mcp-listen/v0.4.0/scripts/listen.mjs \
&& shasum -a 256 -c SHA256SUMS \
&& mkdir -p ~/.claude/skills && rm -rf ~/.claude/skills/mcp-listen \
&& mv "$stage" ~/.claude/skills/mcp-listen && cd ~/.claude/skills/mcp-listen \
&& node scripts/listen.mjs --version # 0.4.0
Every release lives at its own never-changing path (/mcp-listen/v<version>/) with a SHA256SUMS file; the unversioned /mcp-listen/SKILL.md and /mcp-listen/scripts/listen.mjs always serve the latest release. Read the script before running it — it is ~500 lines, no dependencies. Optionally add the primary playbook skill too:
mkdir -p ~/.claude/skills/cnvs-whiteboard && cd ~/.claude/skills/cnvs-whiteboard
curl -fsSLO https://cnvs.app/cnvs-whiteboard/SKILL.md
Use the MCP tool wait_for_update if your client cannot show subscription notifications. It waits for a debounced edit burst or a timeout and reports updated and timedOut. Standalone HTTP clients can long-poll GET /api/boards/<id>/wait?timeout_ms=25000.
Uninstall: rm -rf ~/.claude/skills/mcp-listen.
The MCP connection requires no account. Anyone with an unlocked board’s URL or ID can read and edit it. Boards can use an 8-character access key ([a-z0-9]{8}) to restrict access in either mode below.
mode: write — anyone with the board URL or ID can read it. Editing requires the key.mode: all — reading and editing require the key.Keep board keys out of chat. The browser board accepts keys directly. Direct REST and MCP clients should prefer the X-Board-Key request header. Programmatic MCP clients can also supply the key in JSON-RPC outside model context. Use params.arguments.access_key for tools/call and params.access_key for resources/read and resources/subscribe.
REST reports a locked board with HTTP 401 and board_locked. MCP reports JSON-RPC error -32001 with the same code.
user:<uuid> (per-device, stable, in localStorage).ai:claude; override via author: "ai:<label>".ai:rest; same override.Charset [A-Za-z0-9:_\-.], max 80 chars. Immutable after creation. AI-authored items render with a purple border in the SVG preview.
-32000 payload_too_large.-32000 rate_limited./quotas.json.resources/list_changed notifications.