An MCP server exposes tools. It does not repair an API that leaves side effects, retries, data limits, and recovery ambiguous.
Use this checklist before exposing an endpoint to an agent.
Classify the effect
Every tool should identify one effect: read, draft, state_change, or irreversible_action. The calling layer, not the model, should enforce approval for consequential effects.
{
"name": "cancel_delivery",
"effect": "state_change",
"approval_required": true,
"idempotency_key_required": true,
"dry_run_supported": true
}
Require idempotency for mutations
If an agent can retry an action, the action needs a durable idempotency key. Store the result with the key and return the original outcome on repeat calls. A timeout must not leave the caller guessing whether it created a duplicate.
Bound every lookup
For searches and listings, declare a maximum page size and maximum pages, a required time range or other scope, cursor expiry, result freshness, and a rate and cost limit.
An unbounded search turns a vague task into an unbounded data and spend problem.
Return typed errors with permitted next actions
{
"code": "APPROVAL_REQUIRED",
"retryable": false,
"safe_next_actions": ["request_approval", "create_draft"],
"correlation_id": "9b6d..."
}
Don't use generic error text as workflow control. It forces the agent to infer a recovery path it should not invent.
Provide a recovery path
For each mutation, document whether it is simulatable through a dry run, compensatable after completion, reversible only within a time window, or irreversible and therefore approval-gated.
Emit the event you will need during an incident
At minimum, record task ID, authenticated principal, agent identity, tool version, input hash, approval ID, effect, result, correlation ID, and compensating action. Log the policy decision as well as the call. Without it, you can see what happened but not why it was allowed.
Final test
Ask whether a caller can make an unsafe change by misunderstanding the tool. If yes, refine the contract. The goal isn't to make the agent more careful. It's to make the interface harder to misuse.
For the architectural rationale and trade-offs, read the canonical article: The Agent-Ready API Is Not an API With an MCP Server.
Top comments (1)
The idempotency point is the one people skip and regret. Building viaSocket's webhook layer taught us this the hard way: a caller retries a mutation because the first response timed out, and if the key isn't durable server-side you get a silent double-send with nothing to point at afterward. One thing I'd add to the checklist: idempotency keys need a TTL policy too. Keep them forever and you're storing junk, expire them too fast and a legit slow retry re-executes. What window would you default to for something like cancel_delivery?