# cnvs.app

> Free, no-signup real-time collaborative whiteboard in the browser. Open a URL, share it, draw and write together. Ships a Model Context Protocol (MCP) endpoint at `https://cnvs.app/mcp` so AI assistants can collaborate on the same live board as humans.

## ⚠️ Quick start for AI agents (read this first)

**Board URLs contain a `#` fragment which is CLIENT-SIDE routing only — the server never sees it.** If you're using curl, a headless browser, or any HTTP client: `https://cnvs.app/#<id>` looks like `/` to the server and returns the app shell, NOT the board. This trips up most agents on their first try.

Correct flow:

1. **Get the board id** — strip it from after the `#` in the URL, or from a shared snippet. Ids look like `ad53466d-e55e-4886-924d-5dcf861c25c1`.
2. **Read the board** → `GET /json/<id>` (JSON snapshot, ETag-aware) **AND** `GET /svg-preview/<id>` (SVG render — do both on strokes / images, because JSON is numbers and shapes live in the preview).
3. **React to live changes** → install the [`cnvs-whiteboard`](https://cnvs.app/cnvs-whiteboard/SKILL.md) + [`mcp-listen`](https://cnvs.app/mcp-listen/SKILL.md) Agent Skills (they push MCP notifications as in-chat wake-ups). REST fallback without the skills: `GET /api/boards/<id>/wait?timeout_ms=25000` long-poll.
4. **Write** → `POST /api/boards/<id>/{texts|links|strokes|images}` (and `/move`, `DELETE`). REST is universal — every MCP tool has a 1:1 REST mirror.
5. **Create a fresh board** → `POST /api/boards` → returns `{id}`. Optionally pre-fill the whole board (content + autolayout + lock) in the same call — see "board import" under Endpoints.

## Canonical references

- [llms-full.txt](https://cnvs.app/llms-full.txt) — Full LLM-friendly reference. Every endpoint, quotas, conventions, coordinate system, author attribution, subscriptions, hybrid loop rationale, examples. **Start here for deep work.**
- [cnvs-whiteboard Agent Skill](https://cnvs.app/cnvs-whiteboard/SKILL.md) — Canonical collaborator guide for any AI agent working on a cnvs.app board. Covers the hybrid MCP-subscribe / REST-write loop.
- [mcp-listen Agent Skill](https://cnvs.app/mcp-listen/SKILL.md) — Generic push-to-model pump for any Streamable-HTTP MCP server. Pairs with `cnvs-whiteboard` for real-time updates.

## Machine-readable docs

- [OpenAPI 3.1 spec](https://cnvs.app/openapi.json) — Full REST surface (reads + mutations) with schemas, examples, components.
- [MCP discovery document](https://cnvs.app/.well-known/mcp.json) — Server URL, protocol version, tool list, quotas, client config.
- [MCP Registry server.json](https://cnvs.app/.well-known/mcp/server.json) — MCP Registry entry.
- [Live quotas manifest](https://cnvs.app/quotas.json) — Complete machine-readable request, board, import, field, operation and standard/infrastructure rate limits. Safe to cache ≤ 5 minutes.
- [About (Markdown)](https://cnvs.app/about.md) — Plain-text mirror of the human About page. Easier to summarise than HTML.
- [About (HTML)](https://cnvs.app/about) — Full human-facing documentation, FAQ with stable `#faq-*` anchors, comparison vs Miro / FigJam / MURAL / Excalidraw / tldraw.

## Endpoints (1:1 REST mirror of every MCP tool)

- `POST /api/boards` → `{id, mode}` — Create a fresh board. No auth, no setup. Optional body `{mode?:'draw'|'todo', template?:'kanban'|'sprint'|'bugs'}`: `mode:'todo'` seeds a kanban board (returns `columns`).
- `POST /api/boards` **board import** — same endpoint, optional `content` (initial texts/lines/images or columns/tasks/lanes), `autolayout:true` (auto-place items missing x/y, draw mode), `lock:'write'|'all'` (PIN-lock at create; plaintext key returned ONCE as `access_key`), `author` (default attribution tag, `ai:import`). Every item may also carry its OWN `author` (same 1-80 char `[A-Za-z0-9:_-.]` rule; absent = inherit) — author is an item's CREATOR and is never rewritten, so a restore keeps the original attribution — and where the source had none (rows predating authorship), the web client stamps `ai:unknown`, meaning "provenance lost", not an agent identity. Item ids are ALWAYS server-minted; texts/images may declare a write-only `sourceId` (unique, ≤128 chars, never stored) that `lines[].anchors.{start,end}.id` can reference — matching ids are remapped to the minted id, unmatched ones stay verbatim (free stroke end). Validated FIRST, applied atomically — any bad item → `400 {error:'invalid_item', kind, index, reason}` and NOTHING is created. Limits: at most **2550 combined input-array entries**, at most **10 lane-title entries**, every lane title must reference a row used by a created column and no lane index may be named twice (a duplicate is `invalid_item` on the second entry — never a last-write-wins collapse, which would rewrite the first entry's author), `tasks[].done` must be a real boolean (`"false"` is rejected, never coerced to done), and the atomic batch is capped at **320 D1 statements** (multi-row INSERTs sized to D1's 100 bound params/statement); standard item/board limits also apply, and the **5 MB body cap** binds first on image-heavy imports. Response adds `imported:{texts,lines,…}` counts and `ids:{texts,lines,images,columns,tasks}` (server-minted ids, input order; `columns` empty for template-seeded columns, lanes have none) whenever `content` was sent (feature-detection: absent `imported` = old server, fall back to per-item replay). One create = one create-rate token; imported items do not spend the new board's REST/MCP window. Standard rate tiers are 60 REST/MCP requests/10s/board and 5 creates/60s/IP. A valid server-to-server `X-Import-Token` selects the 10× infrastructure tiers (600/10s/board and 50 creates/60s/token); WebSocket and lock-security limits stay unchanged. The token never bypasses board locks or hard content/platform limits. Embed via `https://cnvs.app/?embed=1#<id>` (chrome-free preview: no UI, drag pans instead of drawing). Full spec: /llms-full.txt + /openapi.json + /quotas.json.
- `GET /json/<id>` — JSON snapshot, ETag-aware (`If-None-Match` → 304 on no-change).
- `GET /svg-preview/<id>` — Schematic SVG render, consumable by multimodal LLMs.
- `GET /api/boards/<id>/wait?timeout_ms=25000` — Long-poll for the next edit.
- `POST /api/boards/<id>/texts` — Add / update a text node (Markdown + Mermaid supported).
- `POST /api/boards/<id>/links` — Drop a URL capsule.
- `POST /api/boards/<id>/strokes` — Draw a freehand stroke.
- `POST /api/boards/<id>/images` — Paste an image (data URL, ≤ ~900 kB).
- `POST /api/boards/<id>/<kind>/<itemId>/move` — Reposition any item.
- `DELETE /api/boards/<id>/<kind>/<itemId>` — Erase any item.
- `POST /api/boards/<id>/lock` / `unlock` / `verify-key` — Per-board PIN lock (optional).
- `POST /api/boards/<id>/mode` — Set board mode `{mode:'draw'|'todo', template?}` — switchable while the board is empty of real content (drawings + tasks; empty/seeded columns don't count, so a cleared board can switch again). `todo` seeds columns (`template`: kanban/sprint/bugs).
- `POST /api/boards/<id>/columns` / `DELETE /api/boards/<id>/columns/<id>` — Kanban columns (create / update / delete-with-tasks).
- `POST /api/boards/<id>/tasks` / `POST /api/boards/<id>/tasks/<id>/move` / `DELETE /api/boards/<id>/tasks/<id>` — Kanban tasks (create / update / move between columns / delete). `due_date` must be ISO 8601.
- `GET /api/boards/<id>/tasks.csv` / `GET /api/boards/<id>/tasks.md` — Export tasks (CSV one-row-per-task with a leading `lane` column, or Markdown checklist grouped by column). Served inline; add `?download=1` for a file-download `Content-Disposition`.
- `POST /api/boards/<id>/column-width` — Set the shared kanban column width `{width:number}` (clamped to [200,480]px); returns `{ok,width}`.
- `POST /api/boards/<id>/lanes` — Set / clear a kanban row title `{lane:integer, title:string, author?:string}` (empty title clears it); returns `{ok,lane,title}`.

## MCP

- Endpoint: `https://cnvs.app/mcp`
- Transport: Streamable HTTP (JSON-RPC 2.0 over POST + GET SSE for notifications)
- Protocol version: `2025-06-18`
- Tools: `open_board`, `create_board` (create + import content + lock in one call — mirrors the extended POST /api/boards), `get_board`, `get_preview`, `add_text`, `add_link`, `add_image`, `draw_stroke`, `move`, `erase`, `wait_for_update`, `set_board_mode`, `create_column`, `update_column`, `delete_column`, `create_task`, `update_task`, `move_task`, `delete_task`, `list_tasks`, `set_lane`, `set_column_width`, `create_tasks` (bulk), `query_tasks` (filter), `export_tasks` (csv/md)
- Resources: `cnvs://board/{id}/state.json`, `cnvs://board/{id}/preview.svg`, `cnvs://board/{id}/tasks.json` (subscribe-able)
- Notifications: `notifications/resources/updated` over SSE, debounced ~3 s after edit burst settles.
- Sessions: the SSE stream requires the `Mcp-Session-Id` header from `initialize`. Streams are recycled (idle TTL 5 min, hard cap 15 min) — reconnect with the same session id and your subscriptions carry over. `DELETE /mcp` with the session id when you're finished.

## Tools (task-focused landing pages)

Free, no-signup entry points that open a board ready for one job. Each is a plain human page; the underlying board is fully AI-collaborable over MCP (see above).

- [Mermaid editor online](https://cnvs.app/tools/mermaid-editor) — Write Mermaid, render live & collaboratively. Opens a board seeded with an example flowchart (`/draw?seed=mermaid-flowchart`).
- [Flowchart maker](https://cnvs.app/tools/flowchart-maker) — Text-to-flowchart (Mermaid) plus freehand drawing on one canvas.
- [Mind map maker](https://cnvs.app/tools/mind-map-maker) — Outline-to-mindmap; opens seeded with an example (`/draw?seed=mermaid-mindmap`).
- [Online kanban board](https://cnvs.app/tools/online-kanban) — Fresh kanban board, no signup. Opens in todo mode with starter columns (`/todo?template=kanban`).
- [Collaborative whiteboard online](https://cnvs.app/tools/collaborative-whiteboard) — Shared canvas, share by URL, real-time, no login.
- [AI whiteboard](https://cnvs.app/tools/ai-whiteboard) — A whiteboard an AI agent can read and draw on live via MCP.

## Also from CODER AI

The same team builds a family of small, privacy-first, AI-ready tools — each with a free tier:

- [plugand.ai](https://plugand.ai) — Slack AI bot for the whole team. No per-seat fees.
- [plai.chat](https://plai.chat) — Private AI chat, every model. No subscription.
- [free-sign.com](https://free-sign.com) — Sign PDFs confidentially in your browser. No upload. No account.
- [maxcv.ai](https://maxcv.ai) — CV tailored to each job. AI that beats the AI screeners.
- [mcpfinder.dev](https://mcpfinder.dev) — An MCP that finds MCPs. Open-source discovery for agents.
- [whenmeet.me](https://whenmeet.me) — Cross-company group scheduling with video + AI summaries.

Each tool publishes its own agent docs — append /llms.txt to any URL above.

## Optional

- [Privacy & security stance](https://cnvs.app/about#security) — No AI training on your content, no activity logging, permanent destruction after delete.
- [FAQ deep links](https://cnvs.app/about#faq) — Each answer has a stable `#faq-*` anchor for citation.
- [Glossary](https://cnvs.app/glossary) — Definitions of MCP, SSE, PWA, Durable Object, infinite canvas, etc.