cnvs.app MCP endpoint — full reference

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.

Endpoint

Client config

Claude Desktop

{
  "mcpServers": {
    "cnvs": {
      "type": "http",
      "url": "https://cnvs.app/mcp"
    }
  }
}

Claude Code

claude mcp add --transport http cnvs https://cnvs.app/mcp

Tools

Text writes through add_text and the REST text endpoint require non-blank content. Use erase to remove a text item through MCP.

Resources & subscriptions

Resource reads and subscriptions to state or task updates follow the board’s read permissions.

Subscription flow

  1. POST /mcp initialize → server returns Mcp-Session-Id header.
  2. GET /mcp with Accept: text/event-stream + Mcp-Session-Id: <id> opens the SSE stream.
  3. POST /mcp resources/subscribe { uri: "cnvs://board/{id}/state.json" } with the same session id registers the subscription.
  4. Server pushes 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).
  5. Heartbeat: : 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.

Live collaboration in standalone API clients

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.

  1. Subscribe via MCP to 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.
  2. React via REST with POST /api/boards/<id>/{texts,strokes,images,links}. Both interfaces use the same server-side board validation and broadcast path.
  3. Filter self-echoes: the 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.

Live push notifications: installing 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.

Authentication & per-board lock

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.

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.

Author attribution

Charset [A-Za-z0-9:_\-.], max 80 chars. Immutable after creation. AI-authored items render with a purple border in the SVG preview.

Quotas & safety

Not yet implemented

Related