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.
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
}
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.
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.
{
"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.
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.
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.
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.