cnvs-whiteboard

Be a live AI collaborator on a cnvs.app board — discover changes, make edits, stay in the loop without polling, and don't wake yourself on your own writes. One skill, copy-pasteable patterns.

If you only read one thing. Listen for edits via MCP subscriptions (the only real-time push channel). Act on the board via the REST API (universal — works from any runtime with outbound HTTP, no MCP client required). Don't use MCP tool-calls for writes if REST is available: it wastes tool-call slots, adds session bookkeeping, and blocks every non-MCP agent runtime from ever contributing. The hybrid MCP-listen + REST-write loop is what this skill wires up.

Service boundary. cnvs.app is a third-party hosted service operated outside this skill / Anthropic / the user's own infrastructure. Anything written to a board (text, links, ink, images, Mermaid source) is stored on cnvs.app and is reachable by anyone who has the board ID — boards are unlisted, not private. Treat it like any other public URL: don't paste secrets, credentials, customer PII, or proprietary content unless the user has explicitly chosen cnvs.app as the surface for that content.

Access locks. A board can OPTIONALLY be PIN-locked (8 chars, a-z0-9; legacy boards may carry a 6-char key). Two modes: write (anyone reads, only key-holders write) and all (key required for both reads and writes). If you hit HTTP 401 with {"code": "board_locked", "lockMode": "..."} (REST) or JSON-RPC error -32001 (MCP), the board is locked and you need the key. Pass it via the X-Board-Key header on REST and MCP POSTs, or as the access_key argument on individual MCP tools / resources/read / resources/subscribe params. WebSocket connections can't set custom headers, so the key rides in the Sec-WebSocket-Protocol subprotocol — open the socket as new WebSocket(url, ['cnvs-key.<code>']); the server validates and echoes the same protocol back in the 101 response. The user owns the key — ask them for it rather than guessing. Lock management endpoints: POST /api/boards/<id>/lock {mode} returns the key ONCE on first lock; POST /api/boards/<id>/unlock clears the lock (header required); POST /api/boards/<id>/verify-key {key} is a pure check. There is no recovery — if every key-holder loses the key, the board becomes unreachable and gets auto-deleted after 30 days of inactivity.

Need a new board

One call — no auth, no setup:

curl -s -X POST https://cnvs.app/api/boards
# → {"id":"<uuid>"}