Update and delete tools take a version or precondition
Update and delete tools should take an expected version (an ETag, revision or updated_at) and refuse the write with a conflict when the object changed since it was read; otherwise a stale write silently replaces another writer’s change (MWS-CONC-2).
Check surface-version-guard · Write-surface design · default severity: attention · rubric 2.1.0
What fails
Without an expected version (an ETag, revision or updated_at), a write based on stale data replaces another writer's change. An x-mcp-header named If-Match counts as a version argument.
The rule
A tool that replaces a whole object, deletes an object or accepts a version MUST refuse the write with a conflict when the object has changed since the state the caller read, wherever the backend can detect the change.
How to fix it
Add an "expected_version" argument (or if_match), refuse with a conflict when it no longer matches, and return the version from read tools.
- Return the current version from read tools (see the outputSchema check).
- Add expected_version (or if_match) to update and delete tools.
- Refuse with a clear conflict error when it does not match, naming the current version.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'update_issue_title',
{
title: 'Update issue title',
description: 'Change the title of one issue if it is still at expected_version; otherwise returns a conflict with the current version. Use when the user asks to rename an issue.',
inputSchema: z.strictObject({
issue_id: z.string().describe('Issue ID, for example ISS-42'),
new_title: z.string().describe('New title, one line'),
expected_version: z.number().int().describe('The version get_issue returned'),
}),
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
},
async ({ issue_id, new_title, expected_version }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
server = MCPServer("issues")
@server.tool(
title="Update issue title",
annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True, idempotentHint=True, openWorldHint=False),
)
def update_issue_title(
issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
new_title: Annotated[str, Field(description="New title, one line")],
expected_version: Annotated[int, Field(description="The version get_issue returned")],
) -> str:
"""Change the title of one issue if it is still at expected_version; otherwise returns a conflict with the current version. Use when the user asks to rename an issue."""
return "Done"Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
What does a lost update look like with an AI agent?
The agent reads a record, a person edits it, the agent writes its version back: the person’s edit is gone and nobody is told. IsoKron found this in several widely used MCP servers.
Does an x-mcp-header named If-Match count?
Yes. The checker treats it as a version argument.
Related checks
- Updates send the change, not the whole object
- Read tools declare an outputSchema
- Create and send tools take a retry key
- All checks in Write-surface design for MCP tools
Further reading
How this check is graded
It counts toward: Write-surface design. See the rubric.
Last verified against MCP Write-Safety Requirements 0.9 on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere