Skip to content
IsoKron

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.

Source: MCP Write-Safety Requirements 0.9

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.

  1. Return the current version from read tools (see the outputSchema check).
  2. Add expected_version (or if_match) to update and delete tools.
  3. Refuse with a clear conflict error when it does not match, naming the current version.

TypeScript SDK

TypeScript
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

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

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