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

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

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

```json
"properties": { "project": {...}, "title": {...} }
```

After:

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

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

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

## Related checks

- [Write tools say whether a retry repeats the effect](https://isokron.ai/mcp-check/checks/openai-retry)
- [Update and delete tools take a version or precondition](https://isokron.ai/mcp-check/checks/surface-version-guard)
- [Read tools declare an outputSchema](https://isokron.ai/mcp-check/checks/schema-output-schema)
- [Write-surface design for MCP tools](https://isokron.ai/mcp-check/checks/write-safety)

## Further reading

- [MWS-RETRY-1: retry keys on creates](https://isokron.ai/mws#mws-retry-1)
- [MCP write safety](https://isokron.ai/write-safety)

Counts toward: Write-surface design.

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

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