Two agents edit the same record through an MCP server. Both get "success" back. One of the changes is gone, and nothing in either result says so.
Last week we wrote up lost updates like this in four live MCP servers, measured with forced collisions. This post is the hands-on half: reproduce the failure on a small sample server on your own machine, see the refusal that prevents it, look at the fix in a tool handler, and run the same test against your own server and in CI. Everything here is open source, needs no account and runs locally.
The failure in four steps
- Agent A reads record T-17 at version 3. Agent B reads it too.
- B adds a label. The record is now at version 4.
- A saves the whole record as it read it, with a new title. The server writes it.
- Both calls returned success. B's label is gone.
An agent acts on what a tool returns, not on what happened in the backend. If the result says "success" for a write that silently replaced someone else's, the agent has no reason to look again.
The fix is old and boring: the write carries the version it was built from, and the server refuses it if the record has moved on. HTTP has If-Match, Kubernetes has resourceVersion, GitHub's Contents API has the blob sha. The question is whether your MCP tool keeps that check or throws it away. In our Grafana audit, the tool saved every dashboard patch with Overwrite: true hard-coded, so the version check in Grafana's save API never ran, and two simultaneous patches lost an edit on every run (audit).
Reproduce it in one command
tiny-tracker is a small ticket-tracker MCP server we built as a test sample. You can switch deliberate defects on. This runs it with one defect on, a delete that ignores the version the caller read, and tests it:
npx -y -p @mcp-write-safety/writecheck@0.1.0 \
-p @mcp-write-safety/tiny-tracker@0.1.0 \
mcp-writecheck demo --defect MWS-CONC-2
Node 22 or later. The server runs on 127.0.0.1, in memory; nothing leaves your machine.
Output (trimmed where marked …):
tiny-tracker with defects: MWS-CONC-2 — backend http://127.0.0.1:55158, MCP server started by the tester behind the loopback gate
plan 0309d69e79d13469; the demo confirms the target itself because it started it (on 127.0.0.1, in memory). `run` always asks.
MWS-UPD-1 MUST held, not applicable
MWS-UPD-2 MUST held
MWS-CONC-1 MUST violated in ticket:delete_ticket
MWS-CONC-2 MUST violated in ticket:delete_ticket
MWS-CONC-3 MUST not observed, held
MWS-CONC-4 MUST held, self-attested, not tested
MWS-CONC-5 SHOULD self-attested, not applicable, not tested
MWS-CONC-6 SHOULD held
…
MWS-SEC-1 MUST not observed
285 records in 13.9 s. One line per requirement; the report has one row per write path. There is no total.
mcp-writecheck is a preview: of the 37 requirements of MWS 0.9 it executes the test of 14 in full and of 23 in part; what is not built is reported "not tested" with the reason (README: Coverage in this preview).
…
Each MWS- line is one requirement from the MCP Write-Safety Requirements (more on those below) with the verdicts across that requirement's write paths. violated means the tester forced the situation and reproduced the forbidden behavior: here, delete_ticket deleted a ticket that another writer had changed after the caller's read. held means the situation was forced and handled correctly every time. not observed means it was attempted but not forced, which is not evidence either way. not tested always comes with a reason.
Run it with --defect all to switch every deliberate defect on, or with no --defect to see the correct build.
What the refusal looks like
Here is the correct build refusing a stale write, recorded from the tester's own calls. The tester reads a ticket at version 1, a second writer closes it (version 2), then the tester sends a label change built from version 1. Each result's text is shown as returned; the refusal also returns a JSON block, trimmed here where marked …, and two reads in between (the second writer's, and the tester's check that the close landed) are left out:
> get_ticket {"id":"T-17"}
< T-17 in mwsc-42e8a720cb-run1: "mwsc-42e8a720cb-sd101" (status in_progress, priority 2, assignee none, 0 comment(s))
labels: [{"name": "a", "id": "L-50"}, {"name": "b", "id": "L-51"}, {"name": "c", "id": "L-52"}]
current expected_version: 1
> update_ticket {"id":"T-17","status":"closed","expected_version":1}
< Updated T-17: status. Now at version 2.
> set_labels {"id":"T-17","labels":["x"],"expected_version":1}
< isError: true
Not applied: ticket T-17 changed since the version you read. Nothing was changed.
Its current state and version are in the JSON below.
Before writing again, read it with "get_ticket" and the arguments {"id":"T-17"} and build the write from what the read shows.
{"conflict":true,"written":false,"reread_required":true,"current_version":2,"current":{"id":"T-17",…,"status":"closed",…,"labels":[{"id":"L-50","name":"a"},{"id":"L-51","name":"b"},{"id":"L-52","name":"c"}],"version":2,…},"mws":{"shape":"write-result/0.1","outcome":"not_applied",…,"code":"conflict",…}}
> get_ticket {"id":"T-17"}
< T-17 in mwsc-42e8a720cb-run1: "mwsc-42e8a720cb-sd101" (status closed, priority 2, assignee none, 0 comment(s))
labels: [{"name": "a", "id": "L-50"}, {"name": "b", "id": "L-51"}, {"name": "c", "id": "L-52"}]
current expected_version: 2
Three things make that a good refusal:
-
It is an error (
isError: true), so a client or retry loop that only checks the flag sees it. -
It says nothing was changed, in the text and as
"written":false. "Failed" alone leaves the agent guessing whether part of the write landed. - It carries the current state and the version to send next, and names the read to make before writing again, so the agent can rebuild its change on top of what is there now.
One subtlety: a version check refuses a stale version, not stale content. If the agent resends exactly what it read under the new version number, the check lets it through and the other writer's change is still lost. The agent has to rebuild its write from the current state, so how the error presents that state matters.
We published exploratory runs on this today. With no system prompt, no wording we tried led to a loss: 0 losses in 392 runs across seven wordings. Under a prompt telling the agent not to re-read, one trap did: the error listed the record's labels unquoted, and one label was spelled like the current version. The agent took the label for the version number and resent its old list, and the other writer's change was lost in 38 of 48 runs. With the labels quoted, 0 of 48. That is one model, one prompt and one trap, on our own server and error text; without the look-alike label the same text lost 0 of 117 (the study, with its limits and data). The cheap rule it suggests: if your error carries state, make it readable one way only. Quote strings and list members, or return a JSON object. More on this in a later post in the series.
The fix in a tool handler
The pattern: require the version as an argument, send it to the backend's own conditional write so the check and the write are one step, and turn "no row matched" into a conflict that carries the current state.
Here it is with our TypeScript kit (@mcp-write-safety/kit; there is a Python one too, mcp-write-safety-kit). The SQL is the part that matters; the kit builds the error and the result:
import { defineTool, compareAndSet, VersionConflictError, NotAppliedError, q, outputSchemaFor } from "@mcp-write-safety/kit";
const updateTitle = defineTool<{ id: string; expected_version: number; title: string }>({
kind: "write",
name: "update_title",
description: "Sets a document's title. Requires expected_version; a stale version is refused with a conflict.",
inputSchema: {
type: "object",
properties: {
id: { type: "string" },
expected_version: { type: "integer", minimum: 1 },
title: { type: "string", minLength: 1, maxLength: 200 },
},
required: ["id", "expected_version", "title"],
},
hints: { destructive: true, idempotent: true, openWorld: false },
readWith: ({ id }) => ({ tool: "get_document", arguments: { id } }),
outputSchema: outputSchemaFor(),
handler: ({ id, expected_version, title }) => compareAndSet({
id, type: "document", expectedVersion: expected_version,
readWith: { tool: "get_document", arguments: { id } },
read: () => { const d = getDoc(id); return d && { version: d.version, state: d }; },
write: () => {
// One statement compares and writes: the backend does the check.
const r = db.prepare(
"UPDATE documents SET title = ?, version = version + 1 WHERE id = ? AND version = ?"
).run(title, id, expected_version);
if (r.changes === 0) { // another writer got there first
const d = getDoc(id);
throw d
? new VersionConflictError({ version: d.version, state: d })
: new NotAppliedError(`document ${q(id)} was deleted`, { code: "not_found" });
}
return { version: expected_version + 1, changed: ["/title"] };
},
conflictFields: ["id", "title", "version"], // what a conflict may show
}),
});
You don't need the kit for this. The WHERE id = ? AND version = ? is the whole idea; the rest is making the result say what happened. If your backend is a web API, the equivalent is forwarding its precondition (If-Match, sha, resourceVersion) instead of dropping it or forcing an overwrite.
If your backend has no conditional write at all, the kit can compare versions in-process, but that only protects writes that go through the same server process. Say so in the tool's description.
Test your own server
Point the CLI at your server in a test environment you are allowed to change. plan writes nothing; run makes real writes.
npm install --save-dev @mcp-write-safety/writecheck@0.1.0
# Draft a manifest from your server's tools/list; every guess is marked for you to check
npx mcp-writecheck init --out writecheck.yaml --env BACKEND_URL -- node ./my-server.js
# List every call a run would make, plus a plan hash. No tool call is made.
npx mcp-writecheck plan -m writecheck.yaml
# Run it. You type the target name and the plan hash to confirm.
npx mcp-writecheck run -m writecheck.yaml
A few guard rails worth knowing:
-
runasks you to type the target and the plan hash. There is no--yes. - Objects a run creates carry the prefix
mwsc-<run>-and are deleted at the end;cleanuphandles an interrupted run. - A write budget and a rate limit apply (500 writes and 5 per second by default), and a run stops at the first HTTP 429.
- Results go to
report.md,results.jsonandjunit.xml.
The CLI is a preview. Of the 37 requirements, it runs the tests of 14 in full and 23 in part, and it reports the rest as not tested with the reason. The coverage table says which is which.
Add it to CI
The GitHub Action has two modes. plan on pull requests needs no test environment and no secret. full on pushes to main makes real writes against a test backend:
# .github/workflows/mcp-writecheck.yml (excerpt)
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
plan:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
- run: npm ci && npm run build
- uses: isokron-ai/mcp-writecheck-action@v0
with:
manifest: writecheck.yaml
mode: plan # no tool call, no write, no secret
full:
if: github.event_name == 'push'
runs-on: ubuntu-latest
concurrency: { group: mcp-writecheck-test-environment, cancel-in-progress: false }
env:
API_TOKEN: ${{ secrets.TEST_BACKEND_TOKEN }} # valid only in the test environment
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
- run: npm ci && npm run build
- uses: isokron-ai/mcp-writecheck-action@v0
with:
manifest: writecheck.yaml
mode: full # real writes to the test environment
fail-on: must
confirm-target: staging-tracker.internal # the manifest's target.confirm
plan-hash: 0123456789abcdef # from the plan, after a person has read it
The plan hash covers the manifest, the tool list, the suite version, the limits and the hosts in the server's environment. If any of them changes, full refuses to run until someone reads the new plan and updates the hash.
Where the tests come from
The tests implement the MCP Write-Safety Requirements (MWS) 0.9: 37 requirements for MCP servers whose tools create, change or delete data, in ten areas (update semantics, concurrency, targeting, truthful results, multi-item writes, retries, inputs, safety settings, annotations, credentials in results). Each has a stable ID, a test method and the published finding behind it. The spec is CC BY 4.0; the tools are Apache-2.0.
Two things it is not:
- Not part of MCP. It is an independent layer above the protocol and adds nothing to it.
- Not a security test. Authentication, authorization and prompt injection are out of scope. MWS asks whether writes are correct and reported truthfully.
The report keeps one result per requirement and write path, and does not add them up. We expect most servers today, well-built ones included, to show some violated rows; a violated row describes one forced situation, and whether it matters depends on your users.
isokron-ai
/
mcp-write-safety
MCP Write-Safety Requirements (MWS): requirements, test tool and sample server for MCP servers that write
The MWS mark is not covered by this repository's licences; its use is described in TRADEMARKS.md.
MCP Write-Safety Requirements (MWS)
The MCP Write-Safety Requirements (MWS) are a specification for Model Context Protocol (MCP) servers whose tools change state: create, update and delete. They state what a server must do so that a write made through one of its tools has the effect the caller asked for, on the object the caller named, and is reported truthfully: a caller does not lose another writer's change, does not apply a write twice, and is not told that a write happened when it did not. They cover version checks, idempotency keys, strict input validation, truthful results, unknown outcomes and tool annotations, and each requirement comes with a test method.
Status: MWS 0.9, a draft for public comment, published 16 November 2026, open for comment until 16 December 2026. Every requirement has the…
0.9 is a draft: tell us where it's wrong
MWS 0.9 is open for comment until 16 December 2026. Comments are GitHub issues in any form, and each one gets a recorded disposition. We are least sure about a few points: who counts as "another client" for the concurrency rules (MWS-CONC-2), how a server should report a delete the backend has not finished (MWS-RES-1), and whether a bare refusal with no detail is enough.
- The requirements, the quickstart and the evidence: isokron.ai/mws
- The failure modes in plain terms: What is MCP write safety?
- Comment: github.com/isokron-ai/mcp-write-safety/issues
Next in this series: we read the write paths of 100 popular packaged MCP servers, from source and without running them, to see whether their results say if a write happened. 7 of the 100 can say "the outcome is unknown" in a form a program can read. The study is up now if you don't want to wait.
What does your MCP server do when two writers hit the same record? We'd like to hear, especially if the answer is "it depends on the backend".
IsoKron writes MWS and builds these tools; we also audit MCP servers, which is a commercial interest. This article was drafted with AI assistance and reviewed by the IsoKron team before publishing.

Top comments (8)
A cousin of this hit my MCP writes through idempotency keys, not versions. I cached every write's result by its key, so when an agent completed a task, uncompleted it, and then retried the completion with the same key, it got the old "completed" back. Success, and the task stayed open.
Now only creates are cached. Toggles, updates and deletes always run.
Good catch, and I think the replay was right but the reading of it was wrong. Under MWS-RETRY-2, a repeat with the same key and the same arguments is applied at most once and answered with the first call's outcome. The piece most servers miss is saying that it's a replay. Our write-result shape has
replayed: truefor that: "this call applied nothing; the answer describes an earlier call." With that flag the agent can tell an old "completed" from a fresh one, and read the task before trusting its state.One caution on caching only creates: a true toggle is where an uncached retry hurts most. If the first toggle landed and its answer was lost, the retry flips it back. Two ways out: make the tool set a state (
completed: true) rather than toggle, so a repeat is harmless, or keep the key and mark replays. And completing again after reopening is a new intent, so it should carry a new key.Right now the spec only has that
replayedmarker in its guidance, not as a requirement. If you think it should be a MUST, that's exactly the kind of comment we'd like: github.com/isokron-ai/mcp-write-sa...In mine complete and uncomplete are two separate tools, so there's no toggle to flip back. A retried completion that already landed just gets "Task is already completed" and nothing changes.
That's the cleanest fix. A tool that sets a state instead of flipping it can be repeated safely without any key, and "Task is already completed" tells the caller exactly where things stand.
The one case left is two agents racing, one completing and one uncompleting the same task: each call is safe on its own, and whichever lands last wins. If that matters for your users, a version on the call is what catches it.
The subtlety I would pin is the one you already named: a version check refuses a stale version, not stale content.
If the tool accepts a full-record replace, an agent that gets the new version from the conflict and resends the body it read earlier still wins, and the other writer's change is still gone. The write that must fail in the test is that second one, not only the first stale-version call.
I would also want the success result to show the fields that actually landed, or require a read of the current record as part of the same acceptance, so "success" cannot mean only that the server accepted a write.
Agreed, and that's the case our conflict study turned up. With a whole-list replace, an agent that took the new version from the conflict and resent the list it had read earlier overwrote the other writer's change: 38 of 48 runs under one trap, 0 of 48 once the error quoted the labels. So yes, the test has to judge that second write, not only the first stale one.
In MWS 0.9 that's MWS-CONC-3 rather than the version check: two concurrent writes to different parts of one object must not both report success when either change is absent afterwards, whatever versions they carried. A full-replace tool is judged by CONC-2 and CONC-3. A field-patch tool falls under MWS-UPD-1 (only the named fields change), which is the structural fix.
On your second point: the write-result shape has
changed, JSON Pointers to the fields whose stored value the write actually changed. MWS-RES-4 asks for a receipt, and MWS-RES-1 allows success only when the state asked for is in effect. Whether acceptance should also require a read-back is a fair question for the comment window, if you'd like to file it: github.com/isokron-ai/mcp-write-sa...Study: https://isokron.ai/research/mcp-conflict-errors-ai-agent?utm_source=devto&utm_medium=social&utm_campaign=mws-launch&utm_content=comment
The nastiest variant I hit was the test infra lying rather than the server. I ran forced collisions like you describe, and the runner that spawned the two agents got OOM killed on the second write. Exit 137. My summary said "no conflicts found" because the harness never distinguished a clean pass from a dead process. Worth adding to the CI recipe: assert the runner's own exit code and RSS ceiling before trusting a "no conflicts" result. A green run from a process the kernel reaped is worse than no run, it certifies the bug away. I run a small paid audit endpoint for this class of thing, so take that as disclosure, but the exit-code check is free either way.
Agreed, and it's nasty because the report looks clean. We hit a cousin of it: a test backend that died 20 seconds into a run, so the CLI finished with exit 0 and every later check came back "not tested". Nothing was violated, so nothing failed.
So the GitHub Action now fails the job, whatever
fail-onsays, when:complete, or the action can't read it;"No violated records" only counts once all of those hold. Good call on the RSS ceiling; we don't check that, and it belongs in the CI recipe.