Production patterns

The framework's strongest features are easier to remember as failure patterns. Each row below is a real class of production incident and a concrete mechanism, not a slogan.

Partial failure in a multi-step operation

Failure: step one succeeds, step two fails, and the agent cannot tell which side effect already happened.

Mechanism: compose the workflow into one action with an explicit compensation path. Return f.error() with available recovery actions; do not ask an agent to guess whether it is safe to retry. A transaction or idempotency key belongs in your handler and database.

Parameter hallucination

Failure: the model invents tenantId, emailAddress or another plausible field.

Mechanism: every action schema is strict. Unknown keys are rejected before middleware and the handler, with <validation_error> explaining what was sent and what was expected. Tenant identity must come from ctx, never from tool input.

Thundering herd

Failure: many agents retry the same slow upstream until your connector exhausts its own resources.

Mechanism: .concurrency({ maxActive, maxQueue }) bounds active work and queued work. Full capacity returns SERVER_BUSY with retry guidance. Pair it with upstream timeouts and a rate limiter keyed by tenant or token.

Context window overflow

Failure: a collection response is too large, the model loses the important row and makes a bad decision.

Mechanism: Presenter .agentLimit() truncates before serialization and prepends a summary saying how many rows were hidden and to use filters. .enableSelect() lets the model request only top-level fields. The egress byte guard catches a final oversized text response.

Stale data after a mutation

Failure: the agent sees an old read in its own context after a successful write.

Mechanism: mark reads .cached() or .stale(), and writes .invalidates('domain.pattern'). The state-sync layer decorates descriptions, emits a first-block invalidation marker and publishes resource updates only after a successful mutation.

Blind retry loops

Failure: a model repeats the same invalid call because the error only says "failed".

Mechanism: toolError(code, { suggestion, availableActions, retryAfter }) emits a structured XML recovery contract. The next action is named, the delay is explicit and the typed client can parse it into MCPFusionClientError.

Data leaking to the model

Failure: a handler returns a database row containing a field the model should never see.

Mechanism: attach a Presenter with an allowlist schema and .redactPII(). Undeclared fields never enter the validated output; redaction masks declared sensitive paths on the cloned wire copy. Test result.data with @mcpfusion/testing.

Races on destructive operations

Failure: two agents issue a refund, transition a workflow or update the same record at once.

Mechanism: f.mutation() marks the action destructive by default and the builder creates a per-action FIFO mutation serializer. Add idempotency in the domain layer too: serialization orders calls, it does not make an external payment API idempotent.

The operational checklist

Before Deploy:

• strict inputs and tenant identity from context
• Presenter on every tool that returns domain data
• limits on every collection
• concurrency and rate limits on upstream calls
• invalidation on writes
• recovery fields on expected errors
• lockfile and tests in CI
• telemetry and an audit sink that never stores raw secrets

Next steps

• Testing: turn each row into a regression test
• Contracts: block drift in CI
• Security pipeline: see the execution order