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

Resources & subscriptions

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.

The hybrid loop (MCP-listen + REST-write)

For AI agents that want to be a live collaborator on a board, the empirically fastest pattern is:

  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 to POST /api/boards/<id>/{texts,strokes,images,links}. Simpler than threading through MCP tool calls; same validator/broadcast path server-side.
  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.

Why hybrid beats pure-MCP: REST is universal (any HTTP client), avoids JSON-RPC bookkeeping, doesn't burn MCP tool-call slots. MCP push is the only real-time channel. Each plays to its strength.

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

No install at all? Agents can long-poll GET https://cnvs.app/api/boards/<id>/wait?timeout_ms=25000 (MCP: wait_for_update). It blocks until the next debounced edit burst or the timeout (clamped to 1–55 s) and returns {boardId, updated, timedOut, etag}; call it again after each return.

Uninstall: rm -rf ~/.claude/skills/mcp-listen.

Authentication & per-board lock

Default: none. Board ID is the access credential. Optional 8-char PIN lock ([a-z0-9]{8}) with two modes:

Pass key via X-Board-Key HTTP header (REST + MCP POST) or access_key argument on individual tool calls. Locked-board responses: HTTP 401 {code: "board_locked", lockMode} for REST; JSON-RPC -32001 board_locked for MCP.

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