DEV Community

Cover image for Safe write tools for agents: preview, confirm, audit, and stale previews in a WooCommerce MCP server

Safe write tools for agents: preview, confirm, audit, and stale previews in a WooCommerce MCP server

Naser Sadrmanesh on October 31, 2026

Reading data is the easy part of connecting an agent to a store. Listing orders, summarizing sales, finding low stock: if the model gets one of tho...
Collapse
 
kevinhall profile image
Kevin Hall •

free count before the paid run is the same shape for data calls. what surprised me was that the count and the run never agree exactly, people change jobs in between and the run skips them, so i started reading the skipped rows as part of the answer

Collapse
 
sadrmanesh profile image
Naser Sadrmanesh •

That's a useful parallel for agent write tools too: a preview count that disagrees with the final run is itself a signal. In the WooCommerce MCP path we treat skipped or stale preview rows as part of the audit trail, not noise, so the confirm step can show what changed between preview and apply. Appreciate the concrete example.

Collapse
 
paul_irolla_6b5ae261d0224 profile image
Paul Irolla •

@sadrmanesh A hash check narrows the race to milliseconds without removing it. That difference is worth naming in the docs, so nobody reads stale_preview as a full lock.

Collapse
 
sadrmanesh profile image
Naser Sadrmanesh •

Agreed, and that distinction matters. It's check-then-write, not a lock: WooCommerce's REST API has no conditional writes, so a change that lands between the re-read and the write can't be caught. I've made that explicit in the docs: stale_preview protects against a preview that went stale while waiting for approval, not against concurrent writers. If you need a strict guarantee, keep other systems off the same records while a confirmed write runs.

sadrmanesh.github.io/woocommerce-m...
What is and is not guaranteed
Thanks for pushing on this, Paul.

Collapse
 
sadrmanesh profile image
Naser Sadrmanesh •

Thanks Paul. That distinction ended up driving v0.6.0 too: signed, single-use approval tokens bound to the exact preview, so a stale or replayed confirm is rejected outright.

Collapse
 
alexshev profile image
Alex Shev •

Stale previews are the subtle failure most approval designs miss. A preview should have a versioned snapshot or precondition, so confirmation fails rather than applying an old plan to newly changed state. That one rule turns preview/confirm from UX theater into a meaningful transactional boundary.

Collapse
 
sadrmanesh profile image
Naser Sadrmanesh •

Thanks, Alex, "UX theater" is exactly the failure I wanted to avoid. That's how it works since v0.5.0: the previewId carries a fingerprint of the store state the plan was computed from, and confirm re-checks it, refusing with stale_preview instead of applying the old plan. The remaining gap is that WooCommerce has no conditional writes, so it's a precondition check, not a true transaction. In 0.6.0 I also added optional signed, single-use approvals, so the preview binds both what is confirmed and who confirmed it.

Collapse
 
techdevfun profile image
TECHDEV •

One part of this design I'd steal: the state id covers the reads the plan was computed from, not just the arguments. That's the half of two-step approval most implementations skip — and the one that actually answers your failure mode 3. The 'what this is not' section is doing real work too; few writeups admit the check-to-use window out loud.

The piece I keep circling: the fingerprint binds the what across the two calls — arguments in v0.4, store state in v0.5 — but nothing binds the who. The server can't distinguish a confirm that came from a human who read the before/after from one issued by the same agent in a chained turn. The two-step flow is enforced by host convention ('server instructions tell clients what to do'), not by the server. Is that where single-use approvals are headed — proof of a human in the loop, like elicitation per confirm or a signed approval the server verifies?

Collapse
 
sadrmanesh profile image
Naser Sadrmanesh •

Quick follow-up @techdevfun: this is now shipped in v0.6.0. With WOOCOMMERCE_APPROVAL_SECRET set, every confirm needs a single-use HMAC token bound to the full previewId (arguments plus store state), the tool, the store and a short expiry. A person signs it out of band with woocommerce-mcp approve <previewId>, which shows the before/after first, and the agent never sees the key. Missing, expired, replayed or mismatched tokens are refused with their own error codes, and the result lands in the audit log.

Release notes: github.com/sadrmanesh/woocommerce-...
Design and limits: sadrmanesh.github.io/woocommerce-m...

Thanks again, your comment turned into the release.

Collapse
 
sadrmanesh profile image
Naser Sadrmanesh •

Thanks @techdevfun , this is exactly the gap. You're right: v0.5 binds the what (arguments plus the state the plan was computed from), but not the who. Today the server can't tell a human-read confirm from the same agent chaining preview and confirm in one turn, so the two-step flow is a host convention, and the audit log is the backstop rather than the gate.

The direction I'm leaning toward is an opt-in mode where confirm only succeeds through a channel the agent can't fill in itself: MCP elicitation per confirm, showing the before/after diff, when the client supports it, and otherwise an approval token signed by something outside the model's context (a small approval UI or webhook holding a key the agent never sees). The previewId would be part of what gets signed, so an approval can't be replayed on a different plan or a changed store state.

Elicitation alone still trusts the client to render it honestly, so I'd treat it as "a human was asked" rather than "proof of a human." Signed approval is a great idea and I'd welcome it as the next step for the project. Thanks for pushing on this.

Collapse
 
sadrmanesh profile image
Naser Sadrmanesh • • Edited

Update since this went out, mostly driven by the comments here:

v0.6.0: opt-in signed approvals. With WOOCOMMERCE_APPROVAL_SECRET set, every confirmed write needs a short-lived, single-use HMAC token bound to the exact previewId, tool and store. A person signs it with woocommerce-mcp approve, so an agent can't chain preview and confirm by itself. Without the secret nothing changes. github.com/sadrmanesh/woocommerce-...

Docs: stale_preview is not a lock. It's check-then-write; it catches a preview that went stale while waiting, not a concurrent writer in the last milliseconds. Thanks @paul_irolla_6b5ae261d0224 for pushing on that. github.com/sadrmanesh/woocommerce-...

Tests now cover every registered tool by name. github.com/sadrmanesh/woocommerce-...

Collapse
 
paul_irolla_6b5ae261d0224 profile image
Paul Irolla •

@sadrmanesh The line that stale_preview guards against a preview going stale, not against concurrent writers, is the one readers need. Thanks for turning the objection into that sentence.

Collapse
 
paul_irolla_6b5ae261d0224 profile image
Paul Irolla •

A preview is only as fresh as its last check. Does the stale-preview check run again at confirm time?

Collapse
 
sadrmanesh profile image
Naser Sadrmanesh •

Yes, it does. Since v0.5.0, tools that compute a write from store data (bulk_adjust_prices, schedule_sale, end_sale, fulfill_order) return a previewId that includes a hash of the records the plan was built from. On confirm, the server re-reads those records and re-runs the plan; if the hash no longer matches, the call fails with stale_preview, nothing is written, and the client re-previews. Honest caveat: WooCommerce's REST API has no conditional writes, so this narrows the race to milliseconds rather than locking it.