Agent Studio — WooCommerce Private Connector
Read-only connector to a WooCommerce store's REST API, letting agents query orders, products, inventory and customer data with filtering, search and pagination. Authenticates with a least-privilege read-only API key over HTTPS, handles host rate limits with a token bucket plus retry/backoff, and normalises raw payloads into small stable objects for agent consumption.
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., "@Agent Studio — WooCommerce Private Connector show me today's orders stuck on pending payment"
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.
Agent Studio — WooCommerce Private Connector
A read-only MCP connector that lets an Agent Studio agent read orders, products, inventory and customers from a WooCommerce store.
Built for the Razorpay Forward-Deployed Engineer, Agent Studio assignment (Option 3: private connector for a merchant tool).
Try it in 10 seconds — no Docker, no credentials, no network:
pip install -r requirements.txt python demo/demo_offline.pySpins up a mock WooCommerce store in-process and drives the real connector against it: auth, filtering, pagination and a simulated
429that the client retries automatically. Captured output indocs/demo-output.md.
The problem this solves
The brief asks for a connector. The job behind the brief is to understand a merchant's workflow and move a number. So the design starts there, not at the API.
A D2C merchant's ops team spends 30–60 minutes a day manually filtering stuck payments, scanning for stockouts and digging through order history. The connector turns those questions into answers in seconds, grounded in the merchant's own live data. It is deliberately read-only first — an agent that can mutate a merchant's orders is one that can lose the merchant's money — and it ships with the metrics to prove it worked.
Full framing, the four merchant questions it unlocks, and the impact metrics:
docs/problem-and-impact.md.
Related MCP server: Shopify MCP
Architecture
flowchart LR
A["Agent Studio agent"] -->|"MCP tool call"| B["MCP server"]
B --> C["tools.py"]
C --> I["models.py (normalisers)"]
C --> D["WooCommerceClient"]
D --> E["TokenBucket (rate limiter)"]
D --> F["Retry + backoff (Retry-After)"]
D --> G["paginate() / page()"]
D -->|"Basic auth over HTTPS"| H[("WooCommerce REST API")]The MCP server is a thin adapter over a framework-agnostic core — the
connector/ package has no MCP dependency, so the same core could back a REST
service or a different agent host. Details:
docs/architecture.md.
Why WooCommerce
Self-hostable: the whole demo runs locally via Docker — no vendor account, no approval wait, and no real credentials anywhere in the repo.
Razorpay-relevant: orders, payments and inventory are exactly the merchant commerce data a Forward-Deployed Engineer works with.
A real API surface: genuine pagination, filtering, auth and host-level rate limits, so the connector exercises the hard parts honestly.
What's in the box
connector/ framework-agnostic core (no MCP dependency)
config.py env-driven config; secrets never hard-coded
errors.py typed errors (Auth/NotFound/RateLimited/Upstream)
rate_limiter.py token bucket + backoff-with-jitter
models.py normalisers (raw payload -> small, stable dicts)
woocommerce_client.py auth, retry, pagination, search primitives
tools.py agent-facing read operations
mcp_server/server.py MCP server exposing 7 tools
docs/ auth, tool spec, capabilities, limitations,
architecture, problem+impact, webhooks, demo output
demo/ offline demo (zero setup) + Docker live demo
tests/ 27 tests, no network
pyproject.toml packaging + ruff / mypy / pytest config
Makefile make test | demo | lint | typecheckQuickstart — real store (Docker)
cd demo
bash setup_store.sh # brings up WordPress + WooCommerce
# create a Read API key at http://localhost:8080/wp-admin
export WC_STORE_URL=http://localhost:8080
export WC_CONSUMER_KEY=ck_...
export WC_CONSUMER_SECRET=cs_...
python seed_data.py # sample products + orders
python demo_live.py # the connector in actionConfiguration
Copy .env.example to .env. All secrets are read from the environment —
nothing is hard-coded and nothing secret is ever logged or returned.
Variable | Required | Default | Purpose |
| yes | — | store base URL (HTTPS in production) |
| yes | — |
|
| yes | — |
|
| no | 20 | per-request timeout (s) |
| no | 4 | retries on 429/5xx |
| no | 100 | page size (max 100) |
| no | 5 | client-side request rate |
| no | true | TLS verification |
Run the MCP server
python -m mcp_server.server # stdio (MCP hosts)
MCP_TRANSPORT=streamable-http python -m mcp_server.server # HTTPDevelop
make dev # install dev dependencies
make test # pytest
make cov # pytest + coverage
make demo # zero-setup offline end-to-end demo
make lint # ruff
make typecheck # mypyCurrent state: 27 tests passing, 87% coverage, ruff clean. CI runs lint plus the tests and the offline demo on Python 3.11 and 3.12.
Design decisions
Authentication. HTTP Basic (ck/cs) over HTTPS, never in the query
string. The key is issued with Read permission to a dedicated
least-privilege user, so a leak can only read — it cannot damage the store.
Full flow in docs/auth.md.
Pagination / search primitives. paginate() follows the store's
X-WP-TotalPages header and streams lazily with an optional max_items cap;
page() returns one slice plus metadata. This is the scalable primitive:
callers bound their own cost. Deep-pagination limits — and the index-backed
long-term fix — are called out honestly in
docs/limitations.md.
Rate-limit handling. Two layers: a client-side token bucket so we never
hammer the store, and exponential backoff with jitter that honours
Retry-After on 429/5xx. Exhausted retries raise a typed RateLimitedError.
Normalisation. Raw WooCommerce objects are large; returning them would blow
up the agent's context and leak fields it shouldn't rely on. Every resource is
projected to a small, documented shape in models.py.
Typed errors. The agent gets AuthError, NotFoundError,
RateLimitedError or UpstreamError — and can reason about them — instead of a
raw stack trace.
Read-only. No tool mutates the store. Bounded blast radius by design.
Event-driven v2. The request-driven ceiling and the webhook + index design
that removes it are in docs/webhooks.md.
How this maps to the assignment brief
Requirement | Where it's satisfied |
Connector lets an agent read tickets/orders/inventory |
|
Working demo or key authentication flow | Both: |
Scalable long-term search primitives |
|
Rate-limit handling |
|
Webhook handling (event-driven) | designed in |
MCP tool specification or equivalent |
|
Short doc: what the agent can and cannot do |
|
Setup steps, restrictions, assumptions, limitations |
|
No real customer data / secrets |
|
Docs index
Doc | What it covers |
the merchant problem, and how we'd measure impact | |
layering, request lifecycle, failure path | |
the REST API key authentication flow | |
every tool, with input/return schemas | |
what the agent can and cannot do | |
limitations, assumptions, the long-term fix | |
event-driven v2: webhooks + incremental sync | |
captured demo output | |
how this was planned and sequenced |
Available Tools
7 toolsget_customerA
Fetch a single customer by id (orders count, lifetime spend).
Inputs: customer_id (required).
get_orderB
Fetch a single order (line items, status, totals) by id.
Inputs: order_id (required).
get_productB
Fetch a single product by id (price, stock, categories).
Inputs: product_id (required).
health_checkA
Check connectivity and credentials against the configured store.
Inputs: no named parameters.
list_inventoryB
List products at or below low_stock_threshold units.
Scans the published catalogue via pagination, capped at max_items.
Inputs: max_items, only_managed, low_stock_threshold.
list_ordersB
List orders. status e.g. pending/processing/completed/refunded.
after/before are ISO-8601 dates (e.g. 2026-01-01T00:00:00). search
matches order/customer fields. Returns a page plus pagination metadata.
Inputs: page, after, before, search, +3 more.
search_productsB
Search products by free text, SKU, category id/name, or stock status.
stock_status is one of instock/outofstock/onbackorder.
Inputs: sku, page, query, category, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools target a clear resource+action (list_orders/get_order, search_products/get_product, get_customer). The main overlap is between list_inventory and search_products, since search_products also accepts a stock_status filter, so an agent could hesitate between them for low-stock queries.
Nearly all tools follow a clean snake_case verb_noun pattern (list_inventory, list_orders, get_order, search_products, get_product, get_customer). health_check breaks the verb-first convention but is still readable and unambiguous.
Seven tools is well-scoped for a read-only storefront connector, with each tool earning its place for a distinct resource. No redundant or filler tools.
Product and order access is solid (list/get/search), but customer coverage is only get_customer with no list/search counterpart, and there is no general product listing beyond search/inventory. The surface is usable but has notable gaps for a WooCommerce connector, with no write operations.
Maintenance
Related MCP Connectors
Federated commerce search across independent WooCommerce merchants. Keyless, read-only MCP server.
Hosted WooCommerce MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
MerchantFlow is a hosted, read-only ecommerce analytics MCP server for Shopify and WooCommerce. It gives AI assistants tenant-scoped access to revenue, profit and loss, product and SKU profitability, COGS coverage, fulfillment costs, advertising spend, ROAS, marketing performance, cohorts, LTV, and business valuation across connected commerce and marketing platforms. Connect with OAuth over Streamable HTTP. No local server installation is required.
WooCommerce MCP server for ChatGPT, Claude and any AI agent: list orders, update order status, create refund, create coupon, update product and get sales report in your own WooCommerce account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to WooCommerce yourself; Cotlet does not store your password and you need no WooCommerce API key. About the official WooCommerce API: Yes. WooCommerce has a full REST API (wc/v3) for orders, products, customers, coupons, refunds and reports, and a store owner creates consumer keys for it per store (checked 16 Oct 2026). Setup and FAQ: https://cotlet.dev/integrations/woocommerce-api-mcp-server
Related MCP Servers
- AlicenseBqualityBmaintenanceRead-only MCP server for WooCommerce that enables answering questions about products, orders, sales, and blog posts via the WordPress REST API without needing plugins or write access.590 npm2MIT
- AlicenseAqualityDmaintenanceA read-only MCP server that lets AI assistants answer Shopify store operations questions via tools like get_shop, list_products, get_product, and list_orders.4MIT
- AlicenseAqualityBmaintenanceEnables AI agents to securely access and reason over WooCommerce orders, products, and inventory through read-only MCP tools, with PII redaction, rate-limit handling, and bounded pagination.5MIT
- FlicenseNot gradedqualityBmaintenanceMCP server that gives AI agents secure, read-only access to WooCommerce merchant orders through validated list, get, and search tools. It returns normalized order data with bounded pagination, Zod validation, timeouts, retry/backoff and Retry-After-aware rate-limit handling, plus safe structured errors instead of raw payloads or credentials.-