Agent-Safe Orders MCP Server

An MCP server that lets LLM agents (Claude Desktop, Cursor) work with a real order and inventory database, without letting them break it.

Agents can read freely. Every write (cancel an order, issue a refund, adjust stock) becomes a pending action that a human approves or rejects in a dashboard. Nothing changes until a human says yes.

Why

Once an agent has write access to production data, a bad prompt or a confused model can do real damage ("clean up all the old orders"). This project treats the agent as an untrusted client and puts it behind the same controls you'd use for any external caller:

Related MCP server: varco_mcp

Architecture

flowchart LR
    A[LLM agent<br/>Claude Desktop / Cursor] -- MCP over stdio --> M[MCP server<br/>8 tools]
    M --> G{ToolGateway<br/>scope → rate limit → validate → audit}
    G -- reads --> DB[(PostgreSQL)]
    G -- writes --> P[pending_actions]
    H[Human admin] -- dashboard / REST<br/>X-Admin-Token --> API[Approval API<br/>FastAPI]
    API -- approve: one transaction<br/>claim → execute → record --> DB
    P --- DB

src/order_mcp/
  mcp_server.py   MCP tool definitions (thin wrappers)
  gateway.py      the choke point: scopes, rate limits, validation, auditing
  services.py     business rules + atomic conditional writes
  approvals.py    pending → executed | failed | rejected | expired
  guard.py        token bucket + scope checks
  approval_api.py FastAPI dashboard and REST API for humans
  db.py           schema (SQLAlchemy Core), works on SQLite and Postgres
  audit.py        append-only audit log
  seed.py         demo data

Action lifecycle

agent: request_refund(order 3, 899900, "arrived broken")
          │  validated, de-duplicated, stored
          ▼
      [pending] ──human rejects──► [rejected]
          │  └──── 30 min ──────► [expired]
     human approves
          ▼
   one DB transaction: claim row → re-check rules → write → store result
          ├─► [executed]
          └─► [failed]   (e.g. order already shipped; nothing written)

MCP tools

Write tools carry MCP destructive_hint annotations so clients can warn the user too.

Run it

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Option A: SQLite, no setup
export DATABASE_URL=sqlite:///./orders.db ADMIN_TOKEN=change-me
order-seed
order-approvals            # dashboard at http://127.0.0.1:8000

# Option B: Postgres + dashboard in Docker
docker compose up --build  # dashboard at http://localhost:8000

Connect Claude Desktop: copy claude_desktop_config.example.json into your Claude Desktop config, fix the path, restart, and ask things like "Which orders for rahul@example.com have shipped?" or "Refund order 3, the headphones arrived broken." Then approve the request in the dashboard.

Tests

pytest -q                                   # 54 tests on SQLite (3 concurrency tests skipped)
TEST_DATABASE_URL=postgresql+psycopg://user:pass@localhost:5432/orders_test pytest -q   # all 57

• test_agent_safety.py: 29 adversarial cases: mass-cancel attempts, over-refunds, negative refunds, SQL injection in arguments, missing reasons, scope bypass, retries, error leakage

• test_concurrency.py: real races on Postgres: 10 simultaneous approvals of one action (executes once), 10 parallel refunds against one order (never exceeds the total), 10 identical requests (one queued)

• test_approvals.py, test_services.py, test_guard.py, test_approval_api.py: unit + API tests

CI runs both suites on every push (GitHub Actions with a Postgres service container).

Design notes

• Why not let the agent call the DB directly? An agent is a non-deterministic client. The gateway makes its blast radius small and every action attributable.

• Why re-validate at approval time? Minutes can pass between request and approval. Checking only at request time is a time-of-check/time-of-use bug.

• Why idempotency keys from params? LLM clients retry on timeouts. Hashing tool + params means a retried request maps to the existing action instead of creating a second one.

• Why integer cents? 0.1 + 0.2 != 0.3 in floating point.

• Why stdout is never printed to: with stdio transport, stdout is the protocol channel.

License

MIT