Skip to main content

🛡 Safety and Permissions

Safety for MCP means an agent can only do what its token allows, and every change can be checked before it happens and reviewed afterwards. This page will guide you through dry runs, scopes, revoking a token, publishing, images, rate limits and the audit log, drawn from how the current tools behave and from testing by the team.

Summary
  • Dry run by default: every tool that changes something reports what it would do and changes nothing, unless told dry_run: false.
  • Scopes: a token can only use the tools its scopes allow, and it always acts as the owner who created it.
  • Revoke: revoking a token in "API & MCP" cuts off access immediately.

Dry run first​

Every tool that changes something takes dry_run, and it defaults to true. The tool does its whole job, reports exactly what would happen, and rolls it back. A dry run also catches rules you would otherwise trip over, reported as blocked.

  • Run it as a dry run and read summary, warnings and impact.
  • Run it again with dry_run: false to apply.
  • Then call publish_story when you want it live. Drafting and publishing are separate steps and separate scopes.

A dry run that creates something returns it with an empty id, because the real run assigns the id. Use the ref or slug to recognise it, and take the id from the real run.

Scopes​

Each token carries scopes chosen when it is created: read, write:content, publish, settings and admin:pages. See Access tokens for what each allows.

  • Start with read and write:content. That is enough for a drafting assistant.
  • Add publish only for tools you trust to change the live site. It also covers deleting.
  • Add settings and admin:pages rarely. admin:pages can take pages such as About offline.
  • Use short expiries and revoke a token the moment it is not needed or might have leaked.

A missing scope is reported as an error that names the scope you need.

Revoking a token​

In "API & MCP", press "Revoke" on an active token and confirm. Tools using the token lose access straight away, and this cannot be undone. Revoke a token when:

  • A client is no longer used, or you remove the server from it.
  • The token might have leaked, for example in a screenshot or a shared file.
  • An agent did something you did not expect. Revoke first, then check the audit log.

A token also stops working if the owner who created it stops being an owner.

Publishing​

  • A story needs a topic. Publishing or scheduling a story with no topic is refused, with the code topic_required.
  • Ideas and planned stories cannot be published. Make them a draft first.
  • Wait for the rebuild. The site updates one wait after the last public change, 5 minutes by default. Call rebuild_status to see the next rebuild time, then check the live page afterwards. Use trigger_rebuild, which needs settings, only when it is urgent.
  • Unpublishing and deleting show their impact. The dry run lists which published stories would go offline and which crossroads would break.

Dated entries​

Before creating a dated entry in a series, call list_stories for that topic and check the covers date of the existing entries, so you do not create a duplicate for the same day. A story created with only a topic in a series becomes a dated entry without a choice.

Choices​

A story can have at most three choices. For a thread, set_choices applies changes in one step or not at all, and warns when a choice joins real and demo content.

Images​

  • Use import_image with a search_images result or a web address, then pass the result on to the story: url as featured_image, alt as featured_image_alt and credit as featured_image_credit.
  • Always set alt text and a credit. A credit is an object with name, url, source_url, provider and license. Do not pass it as a plain string, and use source_url with an underscore, in both inputs and results.
  • Unsplash photos are hotlinked with the photographer credited. Other providers' images are copied into the site's uploads. The result tells you which by the hotlinked flag; a hotlinked photo also gets a backup copy (backupUrl), which is only a fallback: keep the Unsplash url in the story.
  • There is no image upload tool. To use your own file, upload it in the Studio and pass the web address to import_image, or use a web address that the site can reach.

Copied images must be JPEG, PNG, GIF or WebP and up to 10 MB. Addresses on private networks are refused.

Test content​

If you are trying things out, label the content clearly in its title, and write as a dedicated persona so you can find and remove it later. A persona marked AI is labelled "AI-generated" on the public site.

Rate limits​

By default each token is limited to 120 requests per minute, with bursts of up to 30, shared between the API and MCP. Over the limit the server answers 429 with a Retry-After header. Back off for that many seconds and keep batches small.

The audit log​

Every change made with a token is recorded and shown in "API & MCP" under "Recent activity", for 90 days. MCP write calls are logged by tool name, dry runs included, along with calls that were refused. Reads are not logged. Checking this log after an assistant has been at work is a quick way to see what changed.

Best Practices​

  • One agent, one token: it is easier to see who did what, and to revoke.
  • Read before you write: call get_story or get_map first, so edits build on the current text.
  • Review drafts in the Studio before you ask for them to be published.