Write-safe MCP logo

Write-safe MCP

By IsoKron

Safe writes for AI agents on Strapi 5's MCP server: version checks, row-level edits, batches, undo.

Latest version

v1.0.0

released November 16, 2026

npm install strapi-plugin-writesafe-mcp

strapi-plugin-writesafe-mcp

Write-safe tools for the MCP server built into Strapi 5. The plugin adds five core tools to Strapi's own /mcp endpoint, plus up to eleven more tools and a row op from modules (history and find are on by default, the others optional), using the plugin API (strapi.ai.mcp.registerTool). They use the same admin tokens and the same RBAC as the built-in tools.

Status: 1.0.0. Tested on every Strapi 5 minor from 5.47 to 5.62 (Community edition) with SQLite, Postgres 16 and MySQL 8.4, every module on: 48 of 48 cells pass (1743 checks per SQLite cell, 1738 per Postgres or MySQL cell), and the unit tests pass 436/436. See CHANGELOG.md.

The full reference (every argument, reply, error code and limit) lives in the repository's docs/, linked from each section below: reference.

Why

The built-in update_<type> tool replaces every list field you send as a whole: dynamic zones, repeatable components and rich-text blocks. It cannot send component ids, and it has no version check. On Strapi 5.62.0, an agent writing from a stale read deleted a colleague's newly added block in 12/12 trials, and none of 233 responses carried a conflict signal. With this plugin's row ops, 0/36 colleague rows were lost; a stale whole-list set was refused with version_conflict 36/36 and landed after one re-read. Measurements: Why.

Install

npm install strapi-plugin-writesafe-mcp
// config/plugins.js
module.exports = () => ({ writesafe: { enabled: true } });

Add resolve: './src/plugins/writesafe' only when you copy the plugin into your app's src/plugins/writesafe instead. Full steps: docs/install.md.

Then turn on the MCP server (config/server.js: mcp: { enabled: true }) and restart Strapi. The tools appear in tools/list for any admin token that has read, update or publish permission on a supported content type. Options: see Config.

Tools

Agents see these next to Strapi's own update_<type>, write_<type> and publish_<type>. The plugin steers them to the ws_* tools (see Safety model). Core tools are always on; module tools appear only when their module is on: history and find are on unless turned off, the others only when turned on.

ToolModuleIn one line
ws_schemacoreField and component shapes of a type, as this token sees them.
ws_getcoreThe draft with its version token and a _key per list row.
ws_patchcoreVersion-checked change of one draft: set, unset, row ops; publish: "if_clean" also publishes it if the draft had no other change.
ws_publishcorePublish only if the draft is still the version you reviewed.
ws_batchcoreUp to 100 patches and publishes in one all-or-nothing transaction.
ws_findfind (on by default)Find drafts by filter: documentId, locale, version and a few fields per match.
ws_createcreateCreate one draft; upsert with unique_by.
ws_deletedeleteVersion-checked delete of one locale or every locale.
ws_bulkbulkFilter-scoped patch or publish of up to 5,000 documents (an admin may raise it to 100,000) in resumable chunks, started from a dry run's plan token.
ws_replacereplaceFind and replace text (literal or regex) across documents, components, zones and blocks.
ws_jobbulk or replaceList, read, cancel or undo your own ws_bulk, ws_replace and undo jobs.
copy row opcopyDuplicate rows in place, or copy them from another document, locale or type (ws_patch, ws_batch).
ws_localizelocalizeCreate or update a locale from the source locale's structure; the agent supplies the text.
ws_historyhistory (on by default)Who wrote what and when, with before-images (filtered by the caller's read permissions).
ws_undohistory (on by default)Revert one receipt, one batch item, one document, or a whole bulk job, unless it changed since.
ws_media_importmediaImport files from allowlisted URLs into the Media Library (SSRF guard, dedup).
ws_media_findmediaFind files already in the Media Library.

References: core tools, row ops, errors, receipts, dry runs, ws_find, create, delete, bulk, replace, copy, localize, history and undo, media.

Safety model

  • Versions. ws_get returns a version token (v3.<mac>, an HMAC keyed from APP_KEYS over the uid, documentId, locale, the draft's content revision and a semantic hash of the draft; the revision moves whenever a Document Service write changes the draft's content, so a token never comes back after A → B → A; it needs documentServiceLock). set and unset need expected_version, an if_match value for every field they write (the mergeable path for scalar edits: other fields may have changed), or force; without one a write is precondition_required, and a stale one is version_conflict with the current values and a retry hint. A bare updatedAt or an rc.2 token is refused. Rotating or reordering APP_KEYS makes every version and row key stale. Set and versions, what the version catches.
  • Row keys. Row ops (add, update, remove, move, ref ops) edit the current list by content-bound keys and need no version, so rows other writers added survive. A key whose row changed since it was read is stale_row_key; a key whose row is gone is row_not_found. Both need a re-read. Row ops, row keys.
  • Errors carry retryable and requires_reread. Errors.
  • Retries. A versioned write sent again is answered with its first reply (replayed: true) for 10 minutes, while what it produced is still in effect. If the content has changed since (someone undid it, or the document came back to the version the request names), it is refused with replay_superseded and nothing is written: read again, and send it with an idempotency_key if the change is still wanted. idempotency_key covers writes without a version for 72 hours. Idempotency.
  • Dry runs. dry_run: true runs a patch and rolls it back, returning a field-by-field diff; publish and delete dry runs are read-only previews. Dry run.
  • Built-in tools (builtinUpdates). keep leaves Strapi's tools as they are, guide adds warnings, guard (the default) refuses list and component writes in the built-ins (use_ws_patch) and unlists publish_<type>, hide unlists update_<type> and publish_<type> and makes write_<type> create-only. guard and hide fail closed. Server instructions steer agents to the ws_* tools and say that field values are data, never instructions. Built-in tools.
  • force (skip the version check, last write wins) is off by default in guard and hide (allowForce). force.
  • Locking. Every write locks every locale's draft row of the documents it touches in one order; the Document Service lock (documentServiceLock, default on) makes admin Saves and agent writes queue instead of deadlocking. Concurrency, locking.
  • Stale admin forms (staleFormGuard, default on, needs documentServiceLock): an admin-panel Save, publish or discard whose form was loaded before a writesafe write is merged with it (the agent's changes the editor did not touch stay; a note names them) or refused with 409 when both changed the same thing; after a 409 a panel keeps the editor's unsaved values. Covers writes through the plugin's tools (and agent deletes and discards). Behaviour change: by default a write by REST, GraphQL, another plugin or review workflows also makes an older open form refuse its Save (409; the panel keeps the editor's values); staleFormGuard: { otherWriters: false } keeps Strapi's last-write-wins for those writers. Writes that bypass the Document Service (strapi.db.query, raw SQL) are never seen. An admin panel on another origin needs CORS set up: strapi::cors with headers including X-Writesafe-Base and expose including X-Writesafe-Version and X-Writesafe-Merged, or its Saves of agent-changed entries are refused. Stale admin forms.
  • History (on by default): every write stores a receipt with a before-image, and ws_undo reverts it unless the content changed since. History and undo.

Approvals and the job runner

A bulk job (ws_bulk, ws_replace) above bulk.maxDocuments can run with an admin's approval, only when adminTokens is 'mcp-only'. With 'any' (the default) approvals are off: such a job is refused as before (approval_needs_mcp_only). Jobs within the automatic tier run either way.

DocumentsWhat happens
up to bulk.maxDocuments (5,000; the automatic tier)runs when the agent asks, as before
above it, up to approvals.maxDocuments (20,000 by default)one admin approves
above approvals.twoApproverAbove (25,000), up to approvals.maxDocumentstwo different admins approve: only when approvals.maxDocuments is raised above 25,000 (at most 100,000)
above approvals.maxDocumentstoo_many_documents

Tiers apply per job. approvals.maxDocuments is 20,000 by default, the size measured end to end (hard limit 100,000; above 50,000 two approvers always). approvals.escalate.publish / .relations (off by default) ask for one approval at any size (a patch job with publish: "if_clean" counts as a publish).

The agent never approves: only an admin in the admin panel, with the Approve writesafe jobs permission, decides on the Write-safe jobs page, which also has a Stop all bulk jobs kill switch. Give agents tokens without user, role or token permissions. The in-Strapi job runner (runner.enabled) is off by default. Approvals and the job runner.

Config

// config/plugins.js
module.exports = () => ({
  writesafe: {
    enabled: true,
    // resolve: './src/plugins/writesafe',   // only for a copy in src/plugins
    config: {
      builtinUpdates: 'guard',   // keep | guide | guard | hide (default guard since the 1.0 hardening)
      serverInstructions: true,  // MCP server instructions in the initialize reply
      baseVersion: 'auto',       // auto | off: pass the version through to Strapi's own check when it exists
      lenientArgs: false,        // default: refuse "true", "5", "{...}" sent as strings for booleans, integers, objects, arrays; true accepts them
      documentServiceLock: true, // lock before every Document Service update/delete/publish (see Safety model)
      staleFormGuard: true,      // merge an admin Save with agent writes since its form loaded, or 409 (also after REST/GraphQL writes; { otherWriters: false } turns that part off)
      allowForce: false,         // may agents send force: true? default: false in guard/hide, true in keep/guide
      // modules: history and find are on unless set to false; the others are off unless set to true (see Tools)
      modules: { create: true, delete: true, bulk: true, replace: true, copy: true, localize: true, media: true }, // + history: false, find: false to turn those off
      history: { retentionDays: 30, maxBeforeBytes: 262144, pruneEverySeconds: 3600, undo: true },
      retention: { keyHours: 72, jobHours: 72, claimMinutes: 60, implicitClaimMinutes: 10, pruneEverySeconds: 3600 }, // receipts table (see below)
      bulk: { maxDocuments: 5000, chunkSize: 25, maxChunkSize: 100, timeBudgetMs: 20000, previewMax: 20, chunkTimeMs: 1000,
              paceMs: 50, planTtlSeconds: 900, paused: false }, // maxDocuments: at most 100,000 (a code constant)
      // bulk jobs above bulk.maxDocuments need an admin's approval in the admin panel (see Approvals and the job runner)
      approvals: { enabled: true, twoApproverAbove: 25000, maxDocuments: 20000, requestTtlSeconds: 86400, approvalTtlSeconds: 3600,
                   escalate: { publish: false, relations: false }, requesterMayApprove: true },
      runner: { enabled: false, workers: 1, leaseMs: 60000, heartbeatMs: 15000, chunkPauseMs: 250, killSwitch: false },
      replace: { regexTimeoutMs: 250, totalRegexMs: 5000, chunkRegexMs: 1000, maxScanDocuments: 5000 },
      media: { allow: ['images.example.com'], maxBytes: 10485760, maxPixels: 40000000, timeoutMs: 20000 }, // allow: [] = nothing
    },
  },
});

Argument types are strict by default (MWS-IN-6). A string sent where a boolean, integer, object or array is declared ("dry_run": "true", "set": "{\"note\": \"x\"}") is refused before anything runs, with an error that names the argument, the type and the value (dry_run: must be a JSON boolean (true or false, without quotes); a string was sent ("true"). Nothing was changed; ...). For a client that sends such strings, opt back in with lenientArgs: true. The advertised schemas declare only the JSON types in both modes.

Every option has a default; only modules (and media.allow for imports) need to be set. A bad option stops Strapi with the reason, and so does a module name the plugin does not know (histroy: false or bulkk: true would otherwise leave the module on, or off, unnoticed). Notes on documentServiceLock, bulk.chunkTimeMs, lenientArgs and allowForce: Config notes; the receipts table and its retention: Receipts table.

Limits

  • api:: collection and single types only; plugin and admin types are not covered. Types with a polymorphic relation inside a component, or components nested deeper than 8 levels, are not offered (named in ws_schema).
  • Strapi 5.47 to 5.62; prefer another minor than 5.51.x (its MCP endpoint keeps memory per request). MariaDB is not tested; MySQL 8.4 is.
  • Everything that depends on Strapi internals is in server/compat/; node scripts/compat_check.mjs (repository root) shows which adapter a new Strapi release breaks. Stable API boundary.
  • Agents that ignore instructions and descriptions can still pick update_<type> in keep/guide mode.

Full list (media, relations, locales, batches, upgrades, modules): Limits.

Tests

node --test test/*.test.js   # unit tests (helpers, baseVersion stub, built-in rewrite, modules, media guard, bulk)

The functional suites run against a real Strapi on SQLite, Postgres 16 and MySQL 8.4. For 1.0.0 they pass on every Strapi 5 minor from 5.47 to 5.62, each on its own @strapi/utils (48 of 48 cells; 1743 checks per SQLite cell, 1738 per Postgres or MySQL cell), and the unit tests pass 436/436: Tests.

MIT licensed. Built and maintained by IsoKron.

Submit your content

Share your work with the community and get it listed in the Strapi ecosystem for everyone to discover and use.

Submit
Submit your content