MCP Idempotency: Prevent Duplicate Actions When a Request Retries

An assistant submits a draft request, loses its connection, and tries again. If the server already saved the first draft, the second request can create a duplicate. The assistant's uncertainty about the response does not mean the first action failed.

Idempotency gives an intended action a stable identity so supported retries can refer to the same work. Caroush requires an idempotency key for mutations and documents how that key is scoped. Understanding the rules prevents network recovery from becoming duplicate content, unnecessary generation, or repeated publication requests.

Separate an action from an attempt to deliver it

An intended action is the business decision: save this draft with these arguments in this context. An attempt is one effort to send that request and receive its result. Several attempts can belong to the same action when the network or queue is unreliable.

The HTTP Semantics standard defines idempotent methods and cautions against automatically retrying non-idempotent requests without evidence that doing so is safe. MCP tool calls commonly travel through POST, so the HTTP method alone does not make a content mutation safe to repeat.

The service can provide application-level idempotency. Caroush's retries and approvals guide requires a new UUID for each intentional mutation and the same UUID with exactly the same arguments for retries.

This is relevant even to a simple AI draft workflow. The goal is one saved object, not one object for every time the client attempted to obtain a response.

Know which identifier serves which purpose

A protocol request identifier helps match a message with its response. A server-generated request identifier helps trace handling. An operation identifier can point to background work. An idempotency key identifies the intended mutation under the service's rules.

These identifiers should not be treated as interchangeable. The MCP tools specification defines tool requests and results, but a particular application's action-identity contract is additional behavior that must be read from its documentation.

For Caroush, preserve the mutation key with the tool name and exact arguments. Also retain returned request and operation references for inspection. A later status read should use the identifier its schema requires rather than guessing that every UUID identifies the same kind of object.

A useful task record can describe the intended draft, its workspace, the mutation identity, and the returned object. Keep it within the appropriate working environment and avoid copying full private prompts into public diagnostics.

Reuse the key only for an identical retry

If the intended action and arguments have not changed, the documented retry should use the original key. If the caption, destination, or other meaningful argument changes, that is a different request and must follow the service's rules for a new intentional action.

Caroush returns idempotency_conflict when a key is reused with different arguments. That conflict protects the relationship between identity and effect. It should not be “fixed” by hiding the difference or cycling through keys until the server accepts something.

Suppose a store asks for a draft announcing a Saturday workshop. The client times out. An identical retry should preserve the original key and Saturday text. If the workshop moves to Sunday, first determine whether the Saturday draft exists, then handle the revision through the supported workflow.

This supports a cleaner content calendar. The team can distinguish recovery of an existing task from a new editorial decision instead of accumulating near-duplicate objects with unclear origins.

Inspect uncertain outcomes before creating fresh work

A lost response leaves several possibilities. The server may not have received the request. It may have saved a result that the client never saw. It may have queued work that is still running. The right recovery depends on evidence about that particular action.

Caroush documents outcome_unknown as requiring reconciliation of existing records before a new request. Preserve the returned references where available and inspect the relevant content or delivery state. Do not interpret uncertainty as proof that nothing happened.

For generation, a new request can also consume additional credits. For publication, a duplicate can create an external consequence. Even when the object is only a draft, unnecessary duplicates make review and cleanup harder.

A social scheduling process should have a clear unresolved state in its handoff. If one teammate is investigating the original request, another should not submit replacement work simply because the campaign deadline is approaching.

Reconnection changes the namespace

Caroush scopes an idempotency key to the connection and tool. Its documentation explicitly notes that a new connection creates a new idempotency namespace. Reusing the same UUID after reconnection does not necessarily refer to the old connection's action.

This is easy to miss during authentication recovery. A user reconnects, the assistant resends the previous mutation, and both assume the old key protects them. The service may correctly treat it as a different action because the connection identity changed.

Before repeating a mutation after reconnection, reconcile the previously created content or delivery records through the authorized application context. Confirm the intended workspace again. If the previous operation reference is visible only to its creating connection, use the appropriate account-owner inspection path rather than guessing.

Your multi-account practices should record this boundary. Reconnecting is not just refreshing a screen; it can change the identity under which action deduplication is evaluated.

Distinguish duplicate queue delivery from a new request

A queue may deliver the same accepted operation more than once. An application can use atomic execution claims to ensure that repeated delivery does not start the handler twice. Caroush documents such protection for its MCP operations.

That server-side protection complements client idempotency; it does not excuse a client from creating unnecessary new actions. Two distinct keys can represent two intentional requests even if their captions happen to match. The server cannot always infer that the user meant only one.

The same principle applies to browser approval. Reopening or approving the same recorded request should not execute it twice, but creating a second request with a new identity is a separate event. Preserve the existing approval and operation reference when checking progress.

This is why deduplication based only on content text is inadequate. A business might legitimately repost a similar message at another time, while two different-looking captions might still represent one accidentally duplicated task. Identity should follow intent and the documented contract.

Walk through a controlled failure scenario

Use a nonproduction fixture or an explicitly authorized draft test. Create one recognizable draft request and record its key before dispatch. Simulate or observe a response interruption without changing the arguments. Then follow the documented retry and inspect the resulting objects.

The expected result is one intended draft, with a traceable relationship between attempts and outcome. Next, test that changed arguments with the same key produce the documented conflict. Do not test duplication protection by making real social publications.

For a queue-dispatch failure, Caroush documents retrying the identical call with the same key. For an unknown outcome, its guidance requires inspection before a new request. These are different recovery paths, so a single blanket “retry on error” rule is insufficient.

The assistant's final report should explain whether it recovered the original action, created a new intentional action, or left an unresolved outcome for inspection. That language helps the editor understand the content inventory without reading transport logs.

Make retry identity part of the normal workflow

Record the key when the action is created, not after a timeout occurs. Keep exact arguments available to the component responsible for retrying, subject to the application's data-handling rules. If the arguments cannot be reconstructed safely, do not improvise a supposedly identical retry.

Review client changes that affect retry behavior. A new library version or agent wrapper can introduce automatic retries, fresh keys, or altered defaults. Test the specific mutation path with controlled artifacts after such changes.

Idempotency is useful because it preserves a simple business expectation: one intended action should produce one intended effect, even when communication takes several attempts. The expectation becomes dependable when client identity, exact arguments, server records, and human handoffs all refer to the same piece of work.