Claude Code calls an MCP tool to raise the timeout on a payment service. The tool returns:
{
"success": true,
"message": "Configuration updated"
}
The agent marks the task complete.
An hour later, the incident is still active. The tool updated staging, not production. It authenticated with a shared administrator credential, although the run was approved for one service identity. The response never identified the account, previous value, new value, or authority behind the write.
The call succeeded. The task did not.
Once an MCP server can change cloud resources, deployment settings, tickets, customer records, or access policy, a positive response is weak evidence. Claude Code needs proof of what the external system accepted and what state now exists.
define the effect before the tool runs
Approval should name the transition, not merely the tool. “Update the service timeout” leaves too much room for interpretation. Which account, service, field, identity, and value did the reviewer approve?
Write the expected effect into the task contract:
approved_effect:
operation_id: pay-timeout-20260801-7ac81f2
principal: claude-code-prod-payments
target:
account: production-eu
service: payments-api
setting: upstream_timeout_ms
transition:
from: 2000
to: 3500
forbidden_changes:
- any_other_setting
- any_other_service
- access_policy
verification_required: true
Generate the operation ID before execution and bind it to the approved input. The MCP server should carry that identity into its downstream request. Without this link, the agent can show a well-formed record for the wrong operation.
The contract also gives the policy layer something precise to evaluate. It can allow one identity to change one field on one production service while refusing a broader credential or a different account. A tool allowlist alone cannot express that boundary. The same approved tool may be safe for one target and dangerous for another.
return evidence, not a cheerful Boolean
A write-capable MCP tool should return an effect receipt. This is a structured record of the action accepted by the external system and the resulting state.
effect_receipt:
operation_id: pay-timeout-20260801-7ac81f2
tool: config.update_service_setting
principal: claude-code-prod-payments
target:
account: production-eu
service: payments-api
setting: upstream_timeout_ms
before:
value: 2000
version: 184
after:
value: 3500
version: 185
request_digest: sha256:67d9...
policy_decision: allow
policy_id: prod-config-narrow-write-v4
external_event_id: cfg_evt_98412
observed_at: 2026-08-01T08:34:19Z
verification:
source: config.read_service_setting
observed_value: 3500
observed_version: 185
result: match
Now the workflow can compare evidence with intent. Did the tool use the approved principal? Did it reach the right account and service? Did the actual transition match the requested one? Can the system of record identify the event?
A missing field is not a minor logging gap. If the target or principal is absent, the run cannot prove that an important part of its authorization held. The honest result is unverified, not complete.
Keep the receipt outside the model transcript. The model can summarize it, but the summary is not the record. Store the structured receipt with the run and connect it to the downstream event ID. For sensitive systems, use an append-only audit store or sign the record so later investigation does not depend on mutable chat history.
verify through the system that owns the state
Do not let a write tool certify itself and call that independent verification. Follow the mutation with a narrow read from the system of record when the risk warrants it.
Read the resource by immutable identifier. Compare its version and only the fields that the task allowed to change. This catches several failures hidden by a Boolean response:
- the tool wrote to staging instead of production
- the requested field changed, but an unrelated field changed too
- one region accepted the update while another did not
- the write succeeded, but the audit tag or release reference was omitted
- a retry applied the transition twice
This verification step is related to handling an unknown outcome after a tool timeout. A timeout asks whether any write happened. An effect receipt asks whether the right write happened under the right authority. Production workflows need answers to both questions.
Use resource versions or idempotency keys to separate a fresh effect from a replay. If the expected version was 184 and the system now reports 186, Claude Code should stop and investigate. It should not assume that its own write was the only event between those states.
stop on mismatch and constrain recovery
The receipt comparison needs three clear outcomes:
receipt matches approved effect: continue
receipt proves a different effect: stop and begin recovery
receipt is missing or incomplete: mark unverified and stop
Do not give Claude Code an open instruction to “fix anything that went wrong.” A wrong-target write is already an incident. An improvising repair loop can spread it.
Define the recovery path before execution:
recovery:
on_target_mismatch: revoke_run_authority_and_escalate
on_partial_effect: execute_named_compensation_if_preapproved
on_unverified_effect: preserve_operation_id_and_stop
on_receipt_mismatch: create_incident_record
max_additional_writes: 1
The extra write budget matters. Recovery authority should be narrower than normal task authority. A preapproved compensation may be safe for a known partial result. A different account, identity, or policy decision should revoke the run’s authority and bring in a human.
make verified effect part of the completion gate
Claude Code should report completion only when it can fill a gate from recorded evidence:
completion_gate:
requested_effect_matches_receipt: true
approved_principal_matches_receipt: true
external_state_verified: true
unexpected_fields_changed: false
receipt_persisted: true
decision: complete
If any answer is unknown, the agent can report that the call returned success while the effect remains unverified. That language may sound less confident. It is far more useful during an incident or audit.
I wrote Claude Code: Building Production Agents That Actually Work for engineers who need this operating layer around Claude Code. The book covers task contracts, narrow MCP permissions, idempotency, evals, observability, review packets, stop rules, and rollback. Leanpub readers also receive future updates as I improve the production patterns.
My rule is simple: every external write ends with evidence that can be checked against the approved effect. success: true is transport output. Completion is a verified state change.