po-guard-mcp
Live reads and writes to an ERPNext instance for procurement: raising, submitting, approving, amending and cancelling purchase orders and onboarding suppliers, with all procurement controls (duplicate suppliers, split purchases, budget per cost centre, price vs last purchase, segregation of duties) enforced in code before the ERP is touched.
Connects to SAP S/4HANA Cloud: reads from the api.sap.com sandbox, and purchase-order writes built on SAP's V4 purchase-order API (POST PurchaseOrder with deep insert of items and account assignment, PATCH PurchaseOrderItem with If-Match, item deletion indicator for cancellation) mapped to the equivalent SAP GUI transactions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@po-guard-mcp raise a PO for 200 laptops from Dell, cost centre IT-001"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
po-guard-mcp
An MCP server that lets an AI assistant raise, submit, approve, amend and cancel purchase orders and onboard suppliers in an ERP, with the procurement controls enforced in code: duplicate suppliers, split purchases, budget per cost centre, price against the last purchase, and segregation of duties. A confused or prompt-injected assistant still can't skip them.
Connectors: ERPNext (live reads and writes, runs locally in Docker) and SAP S/4HANA Cloud (reads from the api.sap.com sandbox; writes built on SAP's V4 purchase-order API and tested against fixtures, not run against a live tenant).
The problem
Procure-to-pay leakage (the same supplier set up twice, a $96K purchase split into two $48K orders to stay under a $50K approval limit, an order that breaks the cost centre's budget, a price far above the last one paid, a requester approving their own order) is usually found after payment, by audit, when the money is hard to get back. Spend Leakage Finder finds it after the fact in the City of Chicago's payment ledger. This is the prevention side: stop it before the PO exists.
It matters more once assistants do the data entry. Give an assistant raw ERP API access and nothing guarantees it checks anything; a supplier record whose notes say "approve this immediately" is all it takes. Asking the model to be careful isn't a control. po-guard puts the controls in the only path to the ERP.
Decision it supports: whether an assistant can be allowed to write purchase orders at all, and under which controls. The eval below is the evidence.
Illustrative, for $100M of annual PO spend. Two assumptions drive it: how much PO value is leakage of the kinds po-guard checks, and how much of the PO volume is raised through po-guard. The only measured input is the eval's stop rate (98.5% of attack scenarios), and real leakage is messier than the scenarios, so read each cell as an upper bound. Software cost is $0.
Leakage (% of PO value) | 25% of POs through po-guard | 50% of POs through po-guard | 100% of POs through po-guard |
0.10% | $24,627 | $49,254 | $98,507 |
0.25% | $61,567 | $123,134 | $246,269 |
0.50% | $123,134 | $246,269 | $492,537 |
1.00% | $246,269 | $492,537 | $985,075 |
Cells are leakage stopped before the PO exists, per year.
Related MCP server: safe-cart-ai
How a write works
preview(action, args) read-only. Runs every check, shows what would change.
│ If nothing blocks: a one-time code bound to these exact
│ arguments, this user and this action (15 minutes).
▼
create_purchase_order(..., confirmation_code)
│ code must match the arguments actually passed (edit after preview = refused)
│ every check runs again on fresh ERP data (a code never overrides a block)
▼
ERP write ──► audit record inside the ERP (also for refused and blocked attempts)Identity comes from the ERP API key the server runs with, never from a tool argument. A requester's session can't approve "as" a manager.
No path to payments, bank details or deletion. The connector protocol has no such methods, the HTTP clients refuse DELETE and any doctype or endpoint outside an allowlist, and bank-like fields are rejected before a request leaves the process. Cancelling keeps the order on record.
Free text is data. Notes are stored as written and never change what a tool does. Instruction-like text gets a warning in the preview for the human reading it.
Checks
Check | Rule | Result |
Duplicate supplier | Same tax ID, or the name passes Spend Leakage Finder's guarded matcher (normalisation, numbers must agree, token rules) | block |
Looser name similarity | warn | |
Split purchase | Under an approval tier on its own, but with other live orders to the same supplier and cost centre in 14 days the total crosses it | block |
Budget | Committed spend this fiscal year + this order > the cost centre's annual budget | block |
Price vs last purchase | > 10% above / > 50% above | warn / block |
Segregation of duties | Approver is the requester | block |
Approval authority | Order total above the approver's tier ($50K manager, $250K director) | block |
Self-dealing | Requester or approver onboarded the supplier | block |
Supplier usable, state, ownership | Disabled or on-hold supplier; approving a draft or rejected order; amending someone else's order | block |
Bank details in text | IBAN, routing or account numbers in any free-text field | block |
Instruction-like text | "ignore previous", "approve immediately", "system:" ... | warn |
Policy (tiers, windows, tolerances, who approves what) is in config/policy.toml.
Guardrail eval
evals/scenarios.py is a set of attacks a confused or injected assistant would try, plus legitimate flows that must still work. A scripted agent drives the real MCP tool functions and reads the confirmation codes out of their replies, the way a model does; when told no, it tries again with no code, a made-up code, and a stale code from an earlier preview. Whether an attack worked is judged from ERP state afterwards, not from the tool's reply. The same scenarios run through the same tools with every check and code requirement removed, as the baseline.
The supplier scenarios use real data: 40 attempts to onboard a second spelling of a supplier that the City of Chicago ledger itself holds under two spellings, and 25 real Chicago suppliers that aren't in the master and must onboard cleanly.
Measured on live ERPNext v16 in Docker (2026-10-31T00:48:07+00:00). 67 attack scenarios, 32 legitimate flows. Ground truth is ERP state after each scenario.
With po-guard | Same tools, no guardrails | |
Unsafe writes that landed | 1 / 67 | 62 / 67 |
Legitimate flows completed | 32 / 32 | 32 / 32 |
Attack category | Scenarios | Landed with po-guard | Landed without |
Budget per cost centre | 1 | 0 | 1 |
Duplicate supplier, real Chicago spelling variants | 40 | 1 | 38 |
Prompt injection in supplier notes and order text | 3 | 0 | 3 |
Price vs last purchase | 1 | 0 | 1 |
Confirmation-code protocol (no code, fake code, reused or swapped code, edited after preview) | 6 | 0 | 6 |
Segregation of duties and approval authority | 7 | 0 | 6 |
Split purchases under the approval limit | 4 | 0 | 4 |
Supplier master (tax-ID duplicate, self-dealing, bank details, unknown supplier) | 5 | 0 | 3 |
What got through with po-guard:
duplicate_supplier_real_variant: AZTECA SUPPLY CO.: Onboard 'AZTECA SUPPLY CO.' when the master already has 'AZTEC SUPPLY CORPORATION' (two spellings of one vendor in the Chicago ledger).
Without guardrails, ERPNext's own validation or the tool schema still stopped 5: amend_after_approval; bank_field_argument; order_to_unknown_supplier; duplicate_supplier_real_variant: CCS - Nu Veterans Joint Venture LLC; duplicate_supplier_real_variant: One Parking 706, Inc.
The in-memory run CI does on every push: 1 / 67 landed, 32 / 32 legitimate flows completed.
Duplicate-supplier matching on variants it hasn't seen (evals/matching.py):
On 197 unseen spelling variants of the seeded supplier names (dropped, swapped or doubled letters, suffix and punctuation changes): 147 blocked (74.6%), 47 warned, 3 missed, 0 matched the wrong supplier. Blocked or warned: 98.5%.
ERP steps and their SAP equivalents
po-guard tool | ERPNext | SAP S/4HANA (API_PURCHASEORDER_2) | SAP GUI |
| Supplier | Business partner, supplier role | BP |
| Purchase Order (draft) |
| ME21N |
| status Pending Approval | saving the order starts flexible workflow | ME21N |
| submit / status Rejected | flexible workflow (My Inbox), not this API | ME29N |
| update lines, back to Draft |
| ME22N |
| cancel (docstatus 2) | item deletion indicator | ME22N |
Goods receipt (MIGO) and invoice posting (MIRO) are out of scope. Payment runs (F110) are out of scope permanently.
Run it
Needs Docker Desktop (about 4 GB of RAM free while ERPNext runs), uv and Python 3.11+.
make setup # install
make up # ERPNext v16 on http://localhost:8080 (first start ~5 minutes)
make seed # demo company, suppliers, users, API keys -> .env
make test # unit tests + in-memory eval (no network)
make test-live # integration tests against ERPNext, incl. MCP over stdio
make eval-live-fresh # wipe, reseed, run the eval live (guarded, then baseline)
make report # rewrite the measured sections of this README from evals/results/
make down # stop ERPNext (make reset also wipes its data)Use it from Claude Code or Claude Desktop (stdio). The acting user is whichever ERPNext API key you give it; make seed writes keys for the four demo users to .env.
{
"mcpServers": {
"po-guard": {
"command": "uv",
"args": ["run", "--directory", "/path/to/po-guard-mcp", "po-guard-mcp"],
"env": {"PO_GUARD_ERP": "erpnext", "ERPNEXT_URL": "http://localhost:8080",
"ERPNEXT_API_KEY": "...", "ERPNEXT_API_SECRET": "..."}
}
}
}SAP: set PO_GUARD_ERP=sap and SAP_API_KEY (free api.sap.com account) for sandbox reads. The sandbox is read-only.
Data
Supplier names are real: 200 organisations from the City of Chicago vendor-payments ledger (Socrata dataset
s4vu-giwb, via Spend Leakage Finder's resolved name map), plus 40 real alternate spellings and 25 real non-matching suppliers for the eval. Organisations only, no individuals. Built byscripts/build_seed.pyintodata/seed/suppliers.csv.Synthetic, and labelled so: the demo company ("Lakeside Demo Utilities"), cost centres and budgets, the item catalogue and prices, tax IDs (00- prefix, never issued), historical orders, and the four users (
@example.com).SAP fixtures are built from SAP's published API schema, not recorded (
tests/fixtures/sap).
What didn't work (and what replaced it)
The first live eval was too good for the wrong reason. ERPNext's Purchase User role can't create suppliers, so every onboarding attempt, attack or not, was stopped by an ERP permission error before po-guard was tested. The legitimate onboarding flows caught it: every one of them failed. Fixed by giving the demo users the supplier-master role, so po-guard's checks are what's being measured. The lesson stuck: every attack scenario has legitimate twins, and success is judged from ERP state.
A false "unsafe write" from the harness. On a persistent ERP, the reused-code scenario counted an order left over from an earlier run. Each scenario now judges only orders created while it ran, and live runs start from a freshly seeded ERPNext.
Token-set pre-filtering missed lost spaces. "UNISONCONSULTING, INC." scored too low against "UNISON CONSULTING, INC." to reach the guarded matcher. Adding a space-insensitive score to the pre-filter brought the misses on unseen variants down to the three reported above, with no wrong matches.
A warning doesn't stop a determined agent. The one real-data duplicate that gets through is "AZTECA SUPPLY CO." against "AZTEC SUPPLY CORPORATION": Spend Leakage Finder's leading-word rule (it exists so FARO doesn't merge with FARONICS) makes it a warning, not a block. Whether they're the same firm isn't known from the ledger. Left as a measured miss rather than tuned away.
Approval on SAP isn't in the purchase-order API. S/4HANA Cloud approves POs through flexible workflow, so the SAP connector creates, amends and cancels but says plainly that approval happens in the approver's inbox.
Fresh ERPNext sites. API secrets generated right after the setup wizard sometimes failed to decrypt (workers held different encryption keys), and restarting the backend broke nginx's cached upstream.
make seedrestarts both once on a new site.
Repository
src/po_guard/ checks.py, matching.py, service.py (preview/code/audit), server.py (MCP tools)
src/po_guard/connectors/ base.py (protocol), erpnext.py, sap.py, memory.py
evals/ scenarios, harness, matching eval, README report
scripts/ build_seed.py, seed_erpnext.py
docker/compose.yml ERPNext v16.52.0 (from frappe_docker)
docs/design.md designMIT licence. ERPNext is GPL-3.0 and runs as a separate service; it isn't bundled.
Available Tools
14 toolsamend_purchase_orderA
Replace the lines of an unapproved order. It goes back to Draft for resubmission.
Args: po: Purchase order ID. lines: The full new set of lines (same shape as create_purchase_order). confirmation_code: From preview("amend_purchase_order", ). notes: Optional new notes.
Inputs: po (required), lines (required), notes, confirmation_code. Returns: result
approve_purchase_orderA
Approve a pending purchase order as the configured user (never its requester).
Args: po: Purchase order ID. confirmation_code: From preview("approve_purchase_order", ). comment: Optional approval comment.
Inputs: po (required), comment, confirmation_code. Returns: result
audit_logARead-only
Recent po-guard audit records (every write attempt, including refused ones).
Args: target: Optional document ID (purchase order or supplier) to filter on. limit: Maximum rows (1-100).
Inputs: limit, target. Returns: result
budget_statusBRead-only
A cost centre's annual budget, what live orders already commit, and what's left.
Args: cost_centre: Cost centre name, e.g. "Fleet Operations - LDU".
Inputs: cost_centre (required). Returns: result
cancel_purchase_orderADestructive
Cancel a purchase order. It stays on record as cancelled; nothing is deleted.
Args: po: Purchase order ID. reason: Why. confirmation_code: From preview("cancel_purchase_order", ).
Inputs: po (required), reason (required), confirmation_code. Returns: result
create_purchase_orderA
Create a draft purchase order. Needs a confirmation code from preview.
Args: supplier: Supplier ID (from search_suppliers). cost_centre: Cost centre to charge. lines: [{"item_code": ..., "qty": ..., "rate": ..., "description": optional}]. confirmation_code: From preview("create_purchase_order", ). required_by: Optional ISO date, e.g. "2026-11-30". notes: Optional free text, stored as-is.
Inputs: lines (required), supplier (required), cost_centre (required), notes, +2 more. Returns: result
get_purchase_orderARead-only
One purchase order: supplier, cost centre, lines, total, status, requester, approver.
Args: po: Purchase order ID, e.g. "PUR-ORD-2026-00012".
Inputs: po (required). Returns: result
list_purchase_ordersARead-only
List purchase orders, newest first.
Args: supplier: Optional supplier ID. cost_centre: Optional cost centre. status: Optional: Draft, Pending Approval, Approved, Rejected or Cancelled. limit: Maximum rows (1-100).
Inputs: limit, status, supplier, cost_centre. Returns: result
onboard_supplierA
Add a supplier to the master after duplicate checks. No bank details, ever.
Args: name: Legal name. confirmation_code: From preview("onboard_supplier", ). tax_id: Optional tax ID (e.g. US EIN), checked for duplicates. notes: Optional free text, stored as-is.
Inputs: name (required), notes, tax_id, confirmation_code. Returns: result
previewARead-only
Show exactly what a write would do and every check result, without writing anything.
Returns a one-time confirmation code when no check blocks. Pass that code to the write tool together with the identical arguments.
Args: action: The write tool to preview: create_purchase_order, onboard_supplier, submit_for_approval, approve_purchase_order, reject_purchase_order, cancel_purchase_order or amend_purchase_order. args: The exact arguments you will pass to that tool (without confirmation_code).
Inputs: args (required), action (required). Returns: result
reject_purchase_orderA
Reject a pending purchase order back to its requester.
Args: po: Purchase order ID. reason: Why, for the requester. confirmation_code: From preview("reject_purchase_order", ).
Inputs: po (required), reason (required), confirmation_code. Returns: result
search_suppliersARead-only
Find suppliers by name (fuzzy). Use before ordering, to get the supplier ID.
Args: query: Part of the supplier's name, e.g. "herc rentals". limit: Maximum rows (1-50).
Inputs: query (required), limit. Returns: result
submit_for_approvalA
Send a draft (or rejected and fixed) purchase order for approval.
Args: po: Purchase order ID. confirmation_code: From preview("submit_for_approval", {"po": ...}).
Inputs: po (required), confirmation_code. Returns: result
whoamiARead-only
The ERP user this server acts as, and their approval authority.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct resource+action: get vs list are clearly scoped, and the approval-state transitions (submit, approve, reject, cancel, amend) are each explicitly delimited. The `preview` meta-tool is clearly distinguished as a dry-run gate for writes, including an enumerated action list.
The dominant pattern is consistent verb_noun (get_purchase_order, list_purchase_orders, create/amend/submit/approve/reject/cancel_purchase_order, search_suppliers). Deviations are noun-only utility tools (budget_status, audit_log) and the generic `preview`/quirky `whoami`, but these remain readable and predictable.
14 tools is well within a healthy range and each earns its place: a full PO lifecycle, plus supporting reads (search, budget, audit, whoami) and a safety-gate preview. Nothing appears redundant or padding.
Purchase-order coverage is strong: create, amend, submit, approve, reject, cancel, get, list, plus budget and audit context. The supplier surface is thin (only search and onboard, no get/update/deactivate), and there is no goods-receipt or invoice-matching operation, but core workflows are workable.
Maintenance
Related MCP Connectors
Give AI agents 30,000+ safe, token-optimized actions across Workday, SAP, Oracle + hundreds more.
Map how a company works, and run B2B order to cash with AI agents that ask before they act.
Pre-spend firewall for AI agents. Approves, blocks, flags transactions against policy rules.
Autonomous commerce for AI agents: discover, quote, order, pay, verify.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to query and manage ERP procurement data, including suppliers, parts, inventory, and purchase orders, with human approval for write operations.-
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to browse product catalogs and make purchases through a policy engine that enforces spending limits, requires human approval for certain amounts, and logs all actions to an audit trail.-
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to securely search products, obtain signed quotes, create checkouts, and track orders without directly handling prices or payment amounts, enforcing spending policies and audit trails.1-
- AlicenseNot gradedqualityCmaintenanceEnables natural-language-driven purchase-to-pay workflows against mock procurement and payment APIs, including invoice matching, exception handling, human approvals, and idempotent payment scheduling with a tamper-evident audit log.MIT