Safe MCP patterns for agents that mutate business state

A minimal MCP server showing three patterns for giving AI agents safe write-access to real business systems: phase-gating, validation-before-mutation, and structured audit logging.

This is a demo, not a product. The domain (a toy inventory + purchase order system) exists only to give the patterns something concrete to apply to — the patterns themselves are the point, and they're domain-agnostic.

Why this exists

AI agents are increasingly given write access to real systems — orders, inventory, CRM records, forecasts. The common failure mode isn't that the underlying LLM is unreliable in some abstract sense; it's that implementations often trust the model to "do the right thing" with no structural guardrail behind it. When an agent hallucinates a state, gets manipulated by a prompt injection, or just gets the order of operations wrong, the result is a silent, incorrect write to a system that a human now has to notice, diagnose, and fix after the fact.

The three patterns below aren't novel research — they're standard engineering discipline for anything touching production state, applied specifically to agent tool calls.

The three patterns

1. Phase gating. A mutating operation (submit_purchase_order) cannot succeed unless a corresponding read/preview operation (draft_purchase_order) happened first, in the same session. This is enforced in code — a hard error, not a prompt instruction the model can ignore or be talked out of. The error message tells the caller exactly what to do next, which is what lets an agent self-correct instead of just failing.

2. Validation-before-mutation. Every check — does the SKU exist, is the quantity sane, does this exceed a sane order threshold — runs against a pure representation of the proposed change, before anything is written. Validation never has side effects. And critically: all checks run regardless of earlier failures, so a caller sees every problem at once instead of fixing one, resubmitting, and hitting the next.

3. Structured audit logging. Every tool call is logged — including blocked and rejected ones, not just successful mutations. An audit trail that's silent about denied attempts is missing exactly the events most worth reviewing later: what did the agent try that got stopped, and why.

The demo

• examples/happy_path.md — draft → review → submit, with real captured output
• examples/blocked_paths.md — five ways the safety layer actually stops a bad call, also with real output

Try it yourself

pip install -r requirements.txt
pytest tests/ -v          # 17 tests, exercises every pattern above
python server.py          # runs the MCP server over stdio

The tests are the actual proof, not the prose above. If you want to verify a claim in this README, the corresponding test is a better source of truth than my description of it.

Structure

server.py              # MCP tool definitions — thin, delegates everywhere
safety/
  phases.py             # session state + the phase gate itself
  validation.py         # pure validation functions
  audit.py               # structured logging, including failures
domain/
  inventory.py           # toy in-memory "database"
  purchase_orders.py    # draft/commit data + transformations
tests/                   # one file per pattern, ~17 tests total
examples/                 # real captured walkthroughs

safety/ and domain/ don't import from each other in the direction you'd expect a "business logic" and "guardrails" split to invert: the domain layer has no idea sessions or approval exist. The gate lives entirely outside it, in safety/phases.py, which decides whether domain.purchase_orders.commit_draft() is ever reached at all. That separation is deliberate — it's what makes it possible to reason about the safety properties without also reasoning about inventory logic at the same time.

What this is not

Not production code. No real database — inventory is a Python dict. No authentication. Session state is in-memory and single-process. This exists to make the safety patterns inspectable and testable in isolation, not to be a system anyone should deploy.

Background

I designed and built production MCP servers (Go, Kubernetes) during my internship at Eli Lilly, including phase-gated tool access and mandatory validation before any state-mutating deployment operation. This demo is built fresh, in a different domain, using none of that code — it isolates the same underlying patterns so they can be read, run, and tested without requiring access to anything proprietary.