Skip to main content

✅ Good Practice

Good practice for MCP means using the tools in a way that keeps live content safe and your work easy to review. This page will guide you through dry runs, scopes, publishing, images, rate limits and the audit log, drawn from how the current tools behave and from testing by the team.

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​

  • 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.

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 assistant, 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.