# 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. Last verified against MCP Write-Safety Requirements 0.9 on 2026-11-18.

## 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](https://isokron.ai/mws#mws-conc-2)

## 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

```ts
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"
```

## 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](https://isokron.ai/mcp-check/checks/surface-full-replace)
- [Read tools declare an outputSchema](https://isokron.ai/mcp-check/checks/schema-output-schema)
- [Create and send tools take a retry key](https://isokron.ai/mcp-check/checks/surface-retry-key)
- [Write-surface design for MCP tools](https://isokron.ai/mcp-check/checks/write-safety)

## Further reading

- [MWS-CONC-2: refuse stale writes](https://isokron.ai/mws#mws-conc-2)
- [Lost updates in four MCP servers](https://isokron.ai/research/mcp-lost-updates-four-servers)
- [Conflict errors and an AI agent](https://isokron.ai/research/mcp-conflict-errors-ai-agent)

Counts toward: Write-surface design.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
