Skip to content
IsoKron

Create and send tools take a retry key

A create or send tool should accept an idempotency key from the caller, so a retry after a lost answer returns the first result instead of creating a duplicate (MWS-RETRY-1).

Check surface-retry-key · Write-surface design · default severity: attention · rubric 2.1.0

What fails

If the answer to a create is lost, the model retries and creates a duplicate. An idempotency key lets the server recognise the repeat. idempotentHint: true is counted as declared, not shown: only a test (MWS-RETRY) can confirm it.

The rule

A create tool whose repeated call would create a second object SHOULD accept an idempotency key from the caller.

Source: MCP Write-Safety Requirements 0.9

How to fix it

Add an "idempotency_key" string argument and have the server return the first result for a repeated key.

  1. Add an optional idempotency_key string argument to create and send tools.
  2. On the server, store key to result for a retention window; return the stored result for a repeated key.
  3. Say in the description that repeats with the same key are safe.
Before
"properties": { "project": {...}, "title": {...} }
After
"properties": { "project": {...}, "title": {...}, "idempotency_key": { "type": "string", "description": "Client-chosen key; a repeat call with the same key returns the first result instead of creating a duplicate." } }

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(
  'create_issue',
  {
    title: 'Create issue',
    description: 'Create one issue in a project. Use when the user asks to file something. Retry with the same idempotency_key returns the first result.',
    inputSchema: z.strictObject({
      project_id: z.string().describe('Project ID, for example PRJ-7'),
      title: z.string().describe('Issue title, one line'),
      idempotency_key: z.string().describe('Client-chosen key; a repeat call with the same key returns the first result instead of creating a duplicate'),
    }),
    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
  },
  async ({ project_id, title, idempotency_key }) => ({ 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="Create issue",
    annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=False),
)
def create_issue(
    project_id: Annotated[str, Field(description="Project ID, for example PRJ-7")],
    title: Annotated[str, Field(description="Issue title, one line")],
    idempotency_key: Annotated[str, Field(description="Client-chosen key; a repeat call with the same key returns the first result instead of creating a duplicate")],
) -> str:
    """Create one issue in a project. Use when the user asks to file something. Retry with the same idempotency_key returns the first result."""
    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

Is idempotentHint: true enough?

It declares the property; it does not create it. The checker counts it as declared but not shown, because only a test against the server (MWS-RETRY) can confirm a repeated create is harmless.

Who chooses the key, the model or the server?

The caller. The model generates one per intended action and reuses it on retry.

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