MCP server

If you are an agent host that speaks MCP, this page gets you connected to a canvas-drop instance once and then creating, deploying, sharing, and editing canvases as the signed-in account, with no per-canvas key to paste. MCP is the identity-scoped companion to the keyed Deploy API: the Deploy API acts on one canvas with its secret key; MCP acts across every canvas you own or edit, as you.

Connect

Add the instance's endpoint to your MCP client:

{base}/mcp

The transport is Streamable HTTP and stateless: every request is authenticated on its own, and there is no session to keep alive. The server identifies itself as canvas-drop, version 1.

A first session, as tool calls:

whoami           {}
                 -> { id, email, name, orgs, teams, isGuest }
create_canvas    { "title": "Retro board" }
                 -> { id, slug, url, apiKey, deploy, ... }        apiKey is returned once
deploy_canvas    { "id": "<id>", "files": [{ "path": "index.html", "content": "<h1>Hi</h1>" }] }
                 -> { url, version: 1, fileCount: 1, totalBytes, warnings: [] }
get_canvas_file  { "id": "<id>", "path": "index.html" }
                 -> { version, path, size, mime, hash, encoding: "utf8", content }

The canvas is live after the third call. A new canvas starts Restricted (the private API value), so its URL serves content only to you until you widen access with update_canvas.

Sign-in (OAuth 2.1)

canvas-drop is its own OAuth 2.1 authorization server; it does not proxy your identity provider. A compliant client needs nothing but the URL:

1. Discovery. {base}/.well-known/oauth-authorization-server and {base}/.well-known/oauth-protected-resource (RFC 8414 and RFC 9728). The issuer is {base}; the only scope is canvas-drop.
2. Registration. POST {base}/register (Dynamic Client Registration).
3. Authorization. {base}/authorize resolves identity server-side with the same auth strategy the dashboard uses, then checks the email allowlist and the blocked flag. In oidc mode a signed-out browser goes through the normal login and back; in proxy and dev mode identity is already present, and a request without it is denied. PKCE S256 is required.
4. Tokens. POST {base}/token exchanges the single-use code (60 s lifetime; client id and redirect URI must match) for an access token (token_type: "bearer", expires_in: 3600) and a refresh token. Refresh tokens rotate on every use. POST {base}/revoke revokes.

Every tool call carries Authorization: Bearer <access_token>. Tokens are stored hashed. On each call the server looks the token up and re-checks that the account is still active, so blocking a user or removing their email domain from the allowlist ends a live token on the next request. A missing or rejected token answers 401 { "error": "unauthorized" } with a WWW-Authenticate: Bearer header whose resource_metadata points at {base}/.well-known/oauth-protected-resource. Nothing the client asserts about identity reaches the tools; org membership is resolved server-side on every request. Sign-in and token events are audited (mcp_authorize_ok, mcp_authorize_denied, mcp_token_issue, mcp_token_revoke).

How every tool behaves

• Results. Success returns the JSON result as text content. Failure returns CODE: message as text with isError: true. Codes are stable; messages are for humans.
• Ids, not slugs. A canvas tool's id is the canvas id. A team tool's id is the team id.
• Scope. Canvas tools see the canvases you own or edit. A canvas you hold no role on, including one you can only view, reads as canvas not found: no existence leak, no cross-account management. Admins get no extra reach on this surface.
• Roles. An editor can do everything the owner can except delete_canvas, transfer_canvas, and the guest-AI fields of update_canvas (guestAiEnabled, guestAiCap). Those answer OWNER_ONLY: Only the canvas owner can do this. for an editor. Roles are resolved on every call; a demotion or removal applies to your next request.
• Disabled canvases. When an admin has disabled a canvas, read tools keep working and every mutation answers DISABLED: This canvas has been disabled by an administrator. (followed by Reason: … when one was given), the same contract as the management API's 409 { "code": "DISABLED" }. Only an admin can re-enable it.
• Archived canvases. Deploy, publish, and rollback refuse with NOT_ACTIVE: …; call unarchive_canvas first.
• Limits. Calls are rate-limited per account from the canvas-API bucket (CANVAS_DROP_RATELIMIT_CANVAS_API_PER_MIN, default 120 per minute); over the limit answers 429 { "error": "rate_limited" } with Retry-After. A request body over 110 MiB answers 413 { "error": "payload_too_large" }.
• Audit. Every mutation writes the same audit event as its dashboard equivalent.

Refusal codes you will meet across tools:

Tools

49 tools: 13 open to any signed-in account, 32 at minimum role editor, 2 owner-only. Optional inputs are marked ?. "View" is the canvas projection described under Return shapes below.

Account, lists, create

Available to any signed-in account.

Read a canvas

Minimum role: editor. These keep working on a disabled canvas.

Deploy

Minimum role: editor. deploy_canvas, begin_deploy, and finalize_deploy also require an active canvas (NOT_ACTIVE); add_files needs only the open handle. Every deploy goes live at once as a new immutable version. There is no draft step on this path; for a draft, use the editor tools below.

Limits: 100 MiB per canvas, 25 MiB per file, 2000 files. Read "Which deploy tool to use" below before sending bytes through a tool call.

Versions and lifecycle

Minimum role: editor unless marked owner-only.

Settings

Minimum role: editor.

Notes on update_canvas:

• The people-and-teams list (grant_access / revoke_access) applies at every access value; access only says who else may open the canvas. whole_org and public_link need a published canvas: active with a live version (SHARE_REQUIRES_PUBLISH). public_link also needs the instance switch on (PUBLIC_LINKS_DISABLED) and an owner whose account may publish public links (PUBLIC_NOT_ALLOWED to the owner, PUBLIC_LINK_OWNER_GATED to an editor). When an org boundary is configured, whole_org needs a canvas homed in an org (ORG_REQUIRED); pass orgId at create_canvas.
• To share with a team, grant_access it with teamId (and a role). The legacy teamIds field replaces the viewer-team grants on the list (at least one team you belong to; personal teams fit any canvas you own, org teams must match the canvas's org: TEAM_REQUIRED, TEAM_FORBIDDEN). Changing access never touches team grants.
• discoverability controls only whether a Whole-org canvas appears in Shared for the whole org; people and teams on the list always see it there. It never widens URL access. Off whole_org it is pinned to link_only on every write (a legacy team row that stored listed reads listed until its next settings write).
• Legacy shape: teamIds: [] sent by a client that sees the canvas on the legacy team value, together with an access change to another value, is a no-op (the grants stay on the list); teamIds: [] on its own, or with any other access value, is refused (TEAM_REQUIRED). Setting galleryListed: true on a Whole-org canvas also sets discoverability: "listed"; passing link_only in the same call is refused (DISCOVERY_CONFLICT).
• Gallery listing needs a shared, published, password-free canvas on public_link or a listed whole_org (NOT_SHARED, NOT_PUBLISHED, PASSWORD_PROTECTED, NOT_GALLERY_ELIGIBLE). galleryTemplatable: true needs the canvas listed first (NOT_LISTED).
• The people-and-teams list itself is managed with grant_access, set_access_role, and revoke_access.

Sharing and people

Minimum role: editor.

Draft editor loop

Minimum role: editor. These mirror the browser editor: a per-canvas draft that publish_draft snapshots into a live version. DraftView is {files: [{path, size, mime, hash, updatedBy, updatedByName, updatedAt}], stale, baseVersionId, updatedAt, dirty, changes: [{path, kind}], entry}, where changes compares saved files with live (added, modified, deleted), entry describes the home page (path, reason), dirty means the draft differs from live and stale means live moved on since the draft was based.

Teams

Available to any signed-in account; self-serve only, with no admin reach. Here id is a team id.

Team error codes: NOT_A_MEMBER, TEAM_NOT_FOUND, TEAM_NAME_TAKEN, FORBIDDEN, TARGET_NOT_FOUND, TARGET_NOT_MEMBER, TARGET_NOT_PERMITTED, TARGET_BLOCKED, AUTH_ADMISSION_REQUIRED, RATE_LIMITED.

Return shapes

Single-canvas management responses (get_canvas, update_canvas, and the dashboard HTTP view) include publicLinkEnabled: true only when Public link is selected, the instance allows public sharing, and the owner retains permission to publish publicly. Lifecycle, password, and expiry still apply separately. This field is resolved from the same policy as content access; it does not use the requesting editor's public-publishing permission.

View, the canvas projection every canvas tool echoes:

{ id, slug, url, ownerId, title, description, status, publicationState,
  currentVersionId, access, accessMode, discoverability, hasPassword, sharedExpiresAt,
  spaFallback, backendEnabled, disabledReason, galleryListed, galleryTemplatable,
  tags, guestAiEnabled, guestAiCap, previewMode, viewCount, lastViewedAt,
  hasPreview, previewUrl? }

publicationState is draft, published, archived, disabled, or deleted. accessMode is the audience — restricted (private or a legacy alias: only the people-and-teams list, which applies at every value), whole_org, or public_link — so an agent never has to know the three spellings of "restricted". previewUrl is present when a preview exists. Identity-bearing tools add owner: {id, name, email} | null and role: "owner" | "editor"; teamIds lists the granted teams at any access value. The password hash and the API key are never included. list_canvases also returns limit, offset, and the filter-independent summary counts shown on the dashboard; these describe the whole owned-or-edited inventory even when the returned page is filtered.

deploy, returned by create_canvas, get_canvas, set_canvas_slug, and regenerate_deploy_key: the exact keyed Deploy API endpoints for this canvas, so there is nothing to probe.

{
  "apiBase": "https://canvases.example.com/v1/canvases/{id}",
  "zipUpload": "PUT https://canvases.example.com/v1/canvases/{id}/deploy",
  "staged": {
    "begin": "POST https://canvases.example.com/v1/canvases/{id}/uploads",
    "stageBlob": "PUT https://canvases.example.com/v1/canvases/{id}/uploads/{uploadId}/blobs/{hash}",
    "finalize": "POST https://canvases.example.com/v1/canvases/{id}/uploads/{uploadId}/finalize"
  },
  "readback": "GET https://canvases.example.com/v1/canvases/{id}/files",
  "status": "GET https://canvases.example.com/v1/canvases/{id}",
  "curl": "curl -X PUT \"https://canvases.example.com/v1/canvases/{id}/deploy\" -H \"Authorization: Bearer $CANVAS_KEY\" --data-binary @site.zip"
}

status is the canvas readback: publication state, the current releaseId, and the publicationToken a coordinated deploy passes back.

create_canvas and regenerate_deploy_key embed the real key in curl (returned once); get_canvas and set_canvas_slug show the $CANVAS_KEY placeholder, so set it from your own copy. The host is CANVAS_DROP_API_BASE_URL, falling back to CANVAS_DROP_BASE_URL. In subdomain mode it differs from the canvas hosts, which is why you should use the advertised endpoints rather than guessing.

Which deploy tool to use

deploy_canvas sends the whole payload in one call: use it for the first publish of a small canvas. Use the staged flow (begin_deploy, add_files, finalize_deploy) when the canvas already has content or has many, large, or binary files. Fresh tiny canvas: deploy_canvas. Everything else: staged.

The staged flow:

1. begin_deploy with the full manifest (path, hash as sha256 of the bytes, size). The reply's missingHashes lists the blobs the server does not already hold. Storage is content-addressed, so an unchanged file is never re-sent; a re-deploy that changed one file sends one file.
2. add_files with the contents for those hashes, in as many calls as you like.
3. finalize_deploy to publish. The handle is single-use and short-lived; a finalize that is missing a blob fails cleanly and can be retried after staging it.

Over MCP, add_files content still travels in the tool call. The saving comes from not resending unchanged files and from chunking.

When several publishers may ship the same build (a local tool plus a CI fallback), pass an opaque releaseId and the publicationToken from get_canvas as expectedPublicationToken on deploy_canvas or begin_deploy. A release that is live already answers outcome: "already_current" and creates nothing; a token that went stale fails PUBLICATION_CHANGED with the current publication; a release that exists only in history fails RELEASE_NOT_CURRENT. Treat each as a reassess signal: read back and decide, never refresh the token and retry blindly. The full contract and a recipe live under Coordinate two publishers.

Prefer curl and the keyed Deploy API for the file transfer whenever you can run shell commands. Every MCP deploy tool inlines file contents into the tool call, so they pass through the model. If you lack command or network permission, request it rather than inlining bytes. The same staged flow runs over plain HTTP: POST {apiBase}/uploads with the manifest, PUT {apiBase}/uploads/{uploadId}/blobs/{hash} with each blob's raw bytes, then POST {apiBase}/uploads/{uploadId}/finalize. The bytes go from disk to the server without entering the model context, with no tool-call size ceiling. create_canvas returns the per-canvas key and the exact URLs in its deploy block. Reserve the MCP deploy tools for a small first publish when shell access is unavailable.

Verify a deploy

The live URL is access-controlled, so do not confirm a deploy by fetching it: an unauthenticated GET returns a login page, not your files. Verify through the server:

• The deploy or finalize result already returns {url, version, fileCount, totalBytes}.
• list_versions shows the new version as current.
• get_canvas_file reads back what is live: no path lists the live files (path, size, mime, hash); a path such as index.html returns that file's content (text as UTF-8, binary as base64; files over 256 KiB return their hash only, so compare it to what you deployed).
• Over curl, the same read-back is GET {apiBase}/files, with ?path= for raw bytes and no size cap. apiBase comes from the deploy block.

Each list_versions row carries a downloadUrl for a complete ZIP export of that immutable version. Fetch it with the same OAuth access token in the Authorization: Bearer … header; the route accepts no query-string token and no dashboard cookie, and applies the same role gate and rate limit as the tools. It answers application/zip on success, 404 { "error": "not_found" } for a canvas you hold no role on, 400 { "error": "invalid_version" } for a version that is not a positive integer, 404 { "code": "NOT_FOUND" } for a version that does not exist, and 503 { "code": "VERSION_INCOMPLETE" } rather than a partial archive when a referenced blob is missing.

Enabling and disabling

The MCP surface is on by default (CANVAS_DROP_MCP=on). CANVAS_DROP_MCP=off removes the /mcp endpoint, the version download route, and the OAuth routes (/authorize, /token, /register, /revoke, /.well-known/*) entirely: they are not mounted, so they answer like any unknown path. Behind a reverse proxy or identity-aware proxy, /mcp must reach the app with its Authorization header intact and bypass the proxy's own login; MCP carries its own auth. See Configuration and Deploy.

Which path should an agent use?

• MCP: your host speaks MCP and you want a connect-once, multi-canvas, identity-scoped surface with the draft editor, sharing, and teams.
• Deploy API (HTTP with a per-canvas key): a keyed, sessionless agent or a CI step that holds one canvas's key. Also the right transport for the bytes of any large deploy, even from an MCP session.
• The packaged Agent skill documents both for a coding agent, and /llms.txt is the single-file quick reference.

Version cleanup and runtime audiences

preview_version_prune(id, versions) accepts "previous" or an explicit numeric selection. Review its { versions, expectedVersionIds, skipped, estimatedReclaimableBytes } with the user. prune_versions(id, versions, expectedVersionIds) deletes only the explicit immutable selection and returns { deleted, skipped }. Both require owner/editor, as does single delete_version. The estimate excludes references retained by current/history/draft/active uploads; it does not promise recovered bytes. See version cleanup.

set_capabilities additionally accepts aiAudience and connectionsAudience, each "editors" (default) or "viewers". Canvas views expose both. Runtime canvas code reads its own role and permissions from me(). set_capabilities also accepts a full runtimePolicy document and expectedRuntimePolicy, copied exactly from get_canvas.runtimePolicyRevision (initially null). Preserve existing entries when adding resources. Stale/missing revisions fail with POLICY_CONFLICT; reload and reconcile. Policies support collection/file presets and overrides, channel rights, and per-Connection audiences and methods. Defaults initialize new resources; they do not change existing ones. See Permissions and defaults for the complete schema. Collections group authored records inside KV, file groups organize standalone uploads inside Files, and channels carry messages/presence inside Realtime. Each name identifies a resource with its own policy. Match configured names in canvas code; settings do not generate application features or migrate raw keys. The Data storage guide explains the storage choices and collection API.

Viewers use configured authored collections, private preferences or the submissions convenience API. Raw shared KV mutations retain owner/editor gates. Runtime code cannot configure resource policies.