Read-only tokens: let Claude look without touching

Two scopes

A token’s scope is one of two strings: read, or read write. Write implies read — there is no write-only token — and unknown scope words are dropped for personal tokens and refused for OAuth clients (“Supported scopes: read, write.”). Read is always granted, so the 403 for a token without it cannot occur in practice. Five tools are gated by write: write_document, create_document, rename_document, restore_version and share_document. Every other tool — list_documents, read_document, search_documents, get_syntax_guide, lint_text, audit_document, render_document, workspace_graph, references, diff_versions, list_versions, export_markdown, export_build_package — all six prompts, every resource and the GET change stream work with read alone.

What a refusal looks like

Calling a write tool with a read-only token is not an HTTP error and not a crash: it is a tool result marked as an error with the exact text “This token is read-only (scope: read). Create a token with write access under Settings → Claude & MCP.” The model sees it, tells you, and can carry on reading. A write scope that reaches a document you cannot write — a team document where you are a viewer — is a different sentence: “Write failed — the document may be read-only for this account.”

Creating one

Settings → Claude & MCP has a “Create a token” button with a checkbox beside it: “Read-only — Claude can read, search, lint and render, but not change anything”. Tick it and the token is named “Claude (read-only)”; leave it and the token is “Claude” with read and write. The raw token is shown once with the one-line Claude Code command; the list below shows every row with an amber “read-only” or a green “read · write” pill. Over the API, POST /api/tokens takes a scopes array of read and write — absent means both — and answers with the id, the token and the scopes it granted; 10 creations an hour, five personal tokens at most (“Token limit reached (5). Revoke one first.”). OAuth clients request their scope in the authorization URL; absent or empty means both, and the consent card lists exactly what was asked.

When to use which

Read-only fits a reviewer’s Claude, a dashboard script that renders diagrams into a wiki, a CI job that lints and audits, or a first session where you want to watch what Claude does before letting it write. Read and write fits your own Claude Code session that drafts, lints and writes, or a connector you use to edit from claude.ai. Because a write snapshots the document first (“Before Claude edit (MCP)”), write scope is reversible; read-only is for when you would rather it never came to that. Revoking either kind takes one click and is immediate.

How to use it

1. 1
   Open Settings → Claude & MCP

   Avatar → Settings → “Claude & MCP” in the left nav.
2. 2
   Tick Read-only

   The checkbox next to “Create a token” reads “Read-only — Claude can read, search, lint and render, but not change anything”.
3. 3
   Create and copy

   The token appears once, named “Claude (read-only)”, with the claude mcp add command filled in.
4. 4
   Check the pill

   In “Active tokens” the row shows an amber “read-only” pill; a full token shows a green “read · write”.
5. 5
   Upgrade when needed

   There is no way to widen a token: create a new one without the tick, and revoke the old one.

Commands & shortcuts

Tips

• Start read-only. Watching Claude list, audit and render for a session tells you whether you want it writing.
• One read-only token per integration that only reads keeps the blast radius of a leak to reading — and the token still counts toward the five.
• flows-to-tests and build-spec work fully on a read-only token; gap-analysis and review-before-merge only write when you agree to the proposed edit, and draft-process and code-to-sequence end by calling create_document — on a read-only token the model reports the refusal and leaves the result in the conversation.
• The read-only sentence is a tool result, so a model in a loop will stop and tell you rather than fail silently.

Questions