Who generates the idempotency key?

The caller, once per intended action, and reuses it on every retry of that same action.

Are reads safe to retry?

Generally yes. The risk is concentrated in writes and outbound sends.

What should an assistant do after an ambiguous failure?

Retry with the same key if one was used, otherwise read the record back before acting again — never blindly repeat a send.

Knowledge · MCP

MCP failure, retry and recovery

Agent calls time out, transports break, and assistants retry. How idempotency keys and typed errors stop a retry from becoming a duplicate invoice.

What happens when an MCP tool call fails?

It depends on whether the failure was before or after the write. An assistant that cannot tell will retry, and a retried write without an idempotency key creates a duplicate. Safe recovery needs typed errors that state whether the action was applied, plus keys that make repeats harmless.

Key takeaways

A timeout is ambiguous: the write may or may not have landed.
Idempotency keys make a repeated call return the original result.
Typed errors tell the agent whether retrying is safe.
Generic internal errors force assistants to guess, and they guess wrong.
Mutating retries without keys create duplicate records and duplicate sends.

The three failure positions

Before the write: nothing happened; retry is safe.
After the write, before the response: the change landed; a naive retry duplicates it.
Partially through a sequence: some steps applied; retry must resume, not restart.

How idempotency keys solve the middle case

The caller supplies a key with the mutation. The server records the key with the result. A second call with the same key returns the stored result instead of performing the work again. The ambiguous timeout stops mattering, because the retry converges on the same outcome.

Errors have to be legible

A raw internal error tells an assistant nothing. A typed payload — what failed, whether it is retryable, and a correlation identifier — lets it either retry safely or report accurately to a person. Turning opaque transport failures into typed responses is part of building an agent surface, not a nicety.

Where URBLD fits

URBLD's MCP dispatcher accepts an optional idempotency key on mutations so retries are safe, and wraps the transport so a failure before tool execution returns a typed error with a correlation identifier rather than an opaque internal-error envelope.

FAQ

Frequently Asked Questions

Straight answers about how URBLD runs the business end-to-end.

Related knowledge

MCP tool schemas and input validation

Retries, idempotency and failure states