Tokens & permissions

The assistant has exactly the permissions of the API token you give it — no more, no less. Choosing the token is choosing what the assistant may do.

Scope: read or read + write

Token scope	The assistant can…	Plan
Read	List projects, document types, taxonomies, settings and design tokens; read and search published content	Any plan with AI assistants (Team+)
Read + write	Everything above, plus read the working (draft) view, create and edit documents and terms, publish, unpublish, trash, upload images	Team+ (API writes are a Team feature)

A read token still lists every tool. Each write it attempts is refused with TOKEN_SCOPE_READ_ONLY and a hint naming the fix — it never partially succeeds.

Start with read

For a first connection, or for an assistant that answers questions about the site, a read token is enough and removes every risk of an unintended change.

Project: narrow it

An organization-wide token reaches every live project. A project-narrowed token reaches one, and the assistant never has to be told which project a call is about.

With an organization-wide token every project-scoped tool needs a project argument. The assistant learns the choices from list_projects; if it forgets, the call answers PROJECT_REQUIRED with the list, and the assistant retries. It works, but it is a round trip you can avoid.

One token per person or agent

Create a separate token for each person's assistant and for each automated agent, named for its use ("Tim — Claude Desktop", "Newsletter drafting bot"). Then:

• Activity shows which assistant made a change, not just that a token did.
• Revoking one cuts off one assistant, not everyone.
• Rate limits are per token, so one busy agent cannot starve another.

Expiry and rotation

Set an expiry on every token. Studio emails the organization's owners and admins as it approaches — not the person who created it, who may have left. To rotate without downtime, regenerate the token from the API tokens page before it expires — it keeps its name, scope and project and gets a new secret; the old secret stops working immediately. An already expired token cannot be regenerated: create a replacement and swap it into the client.

What the token cannot reach

The MCP server forwards only to the public content API under /v1/orgs/<org>/…. The admin API — members, roles, billing, API tokens, settings management, structure editing — is not reachable through the server with any token, because the server does not compose those paths at all.

Plan gating

The server checks the organization's plan on every call (cached for 30 seconds per token). If AI assistants are not on the plan, every tool answers FEATURE_DISABLED with requiredPlan: "team"; downgrading an organization stops its assistants within that window.

Seeing what the assistant did

Every write goes into the organization's activity log attributed to the token, with the token's name and prefix — never a member, because a token is an organization credential, not a person. In Studio → Activity, filter Actor to API token to see only assistant changes, or search the token's name.

The public API's response to each write is also the response the assistant shows you, so "what did it just do?" is usually answered in the chat.

Cutting an assistant off

Revoke the token in Settings → API tokens. The server holds no session, so the next tool call fails with INVALID_API_TOKEN; a call already in flight completes. There is nothing to clear on the client — remove the server from its config at leisure.

Rate limits

The API throttles each token separately for reads and writes, so a busy assistant never slows a site build and vice versa:

Bucket	Limit
Reads	120 per minute
Writes	60 per minute, and 2,000 per day

The daily write cap exists to stop a runaway agent loop. The server also caps requests to itself per token as a backstop. A throttled call answers RATE_LIMITED with retryAfterSeconds; the assistant is told to wait rather than retry in a loop. Details in Errors & limits.