WooCommerce MCP After 10.9: Moving AI Agents to the Built-in Abilities

In short: WooCommerce 10.9 deprecated the beta MCP endpoint at /woocommerce/mcp in favour of seven built-in abilities on the shared WordPress MCP endpoint. Moving a client swaps a possibly read-only REST API key for an Application Password with all of its user’s capabilities, so use a role that can only read.

If you connected Claude, Cursor or another MCP client to a WooCommerce store during the MCP beta, it almost certainly talks to an endpoint ending in /woocommerce/mcp and signs in with a WooCommerce REST API key. Since WooCommerce 10.9, that endpoint is a deprecated transition path. It still works in the 11.2.x releases covered here, but WooCommerce says it will be removed, its current documentation names 11.3 as the release that does it, and new domain abilities are no longer added to it automatically.

Moving to the replacement looks like a change of address. It is more than that. The credential changes, the tools the agent sees change, and the place where "read only" lives moves from the API key to the WordPress user. A client moved carelessly can end up with more power than it had before, not less.

This guide explains what changed in 10.9, how to move an existing client, how to keep an agent's writes denied unless you grant them, and how a store adds an ability of its own. It describes WooCommerce 11.1.2 and 11.2.0 (released on 22 September and 7 October 2026), whose MCP and abilities code is identical; 11.2.1, released on 9 October 2026, leaves those files untouched.^[1] Observations described below as happening "on the test store" come from a test with WordPress 7.1.2 and WooCommerce 11.1.2; everything else was checked against the cited source.

What changed in WooCommerce MCP in 10.9?

The beta (10.3). WooCommerce 10.3, released on 21 October 2025, added an MCP integration in beta.^[2] The call for testing that followed listed nine operations: list, retrieve, create, update and delete products, and list, retrieve, create and update orders. Clients authenticated with standard WooCommerce REST API keys.^[3] Each operation was a REST API call wrapped as an ability, and each appeared to the client as its own MCP tool.^[4]

The rebuild (10.9). WooCommerce 10.9 was released on 23 June 2026 with a rebuilt set of what WooCommerce calls canonical domain abilities.^[5] WooCommerce's engineering post explains the reason: a one-to-one wrapper around a REST endpoint adds another name, schema and permission boundary without adding anything new, so the new abilities start from the business operation instead.^[6] There are seven:

Ability	What it does	Kind	Permission it checks
woocommerce/products-query	Finds products by ID or common filters	Read	Read private products
woocommerce/product-create	Creates a product	Write	Publish products
woocommerce/product-update	Updates a product; publishing also needs the publish permission	Write, marked destructive	Edit that product
woocommerce/product-delete	Moves a product to the bin, or deletes it permanently when asked	Write, marked destructive	Delete that product
woocommerce/orders-query	Finds orders by ID or filters; line items only on request	Read	Read private orders
woocommerce/order-update-status	Changes an order's status, with an optional note	Write, marked destructive	Edit that order
woocommerce/order-add-note	Adds a note without changing the status	Write	Edit that order

The kinds come from each ability's annotations, and the permission column from its permission callback, which calls WooCommerce's usual REST permission helper for products and orders.^[7][8] Product deletion defaults to the bin; permanent deletion needs an explicit force flag, and the ability refuses rather than silently deleting when the bin is disabled.^[6]

The abilities are registered with the WordPress Abilities API on every request. They appear in the Abilities API's own REST routes under /wp-json/wp-abilities/v1/, and they are marked for exposure through the shared WordPress MCP Adapter, which WooCommerce bundles as a Composer package rather than keeping an MCP implementation of its own.^[6] With the WooCommerce MCP feature switched on, that adapter serves them at /wp-json/mcp/mcp-adapter-default-server.^[6][9]

The old endpoint stays, for now. WooCommerce kept /wp-json/woocommerce/mcp and its REST-derived abilities as a compatibility path. Its notice says they "will be removed in a future WooCommerce version", without naming one.^[6] The current documentation identifies 11.3 as the removal release.^[9] New abilities no longer join the old endpoint by namespace alone. The default inclusion rule requires a strict boolean opt-in flag, and the woocommerce_mcp_include_ability filter can override that decision.^[6]

It is still a preview. WooCommerce's documentation calls the MCP implementation a developer preview, warning that "Implementation details, APIs, and integration patterns may change in future releases".^[9] In 11.1.2 the feature is still marked experimental and is off by default, and 11.2.0 keeps it that way.^[10][11]

What changes when an MCP client moves to the new endpoint?

There are four differences between the old endpoint and the new one, and only the first is the address.

1. The address. Remote clients move from /wp-json/woocommerce/mcp to /wp-json/mcp/mcp-adapter-default-server. Both routes are usually reached through the same local proxy, Automattic's mcp-wordpress-remote, which turns the client's messages into HTTP requests.^[9][12] For a store running on the same machine as the client, the documentation also describes a STDIO connection through WP-CLI, which signs in as a named WordPress user and needs no password.^[9]

2. The credential. The old endpoint expects a WooCommerce REST API key, sent as consumer key and secret in an X-MCP-API-Key header.^[12][13] The new one uses a WordPress username and an Application Password. WooCommerce's documentation is explicit: "Do not use your account password or a WooCommerce REST API key."^[9] Application Passwords have been part of WordPress since 5.6, and the REST API handbook prefers them to sending an account password with every request.^[14]

3. The tools. On the test store, the old endpoint listed nine tools with names such as woocommerce-products-delete, one per operation. The new endpoint lists three: one to discover abilities, one to describe an ability, and one to execute an ability by name. The bundled adapter registers exactly those three on its default server, and finds the WooCommerce abilities through them rather than as tools of their own.^[6][15] Any agent instructions, approval lists or scripts that name the old tools stop matching.

Two old operations have no direct successor. Retrieving one product or order becomes a query by ID. Creating an order, and general order edits beyond status and notes, are not covered by the seven abilities. WooCommerce's own migration checklist says to call the WooCommerce REST API directly when an integration needs raw REST behaviour, and to open an issue when it needs a new canonical ability.^[6]

4. Where "read only" lives. This is the change that matters most. A WooCommerce REST API key carries its own permission level: read, write, or read and write.^[16] For the old endpoint's REST-derived compatibility abilities, WooCommerce checked the key's read or write level on each operation.^[13][17] Custom abilities added to that endpoint do not automatically inherit this check; their permission callbacks must enforce the intended access. On the test store, a read key could list products, and its attempt to delete one was refused.

The new endpoint has nothing equivalent. An Application Password carries no scope of its own; it acts with every capability of the user who owns it. The only thing between an agent and a write is that user's role and each ability's permission callback.^[9] If you move a client from a read-only key to an Application Password for a Shop Manager account, you have quietly turned a read-only agent into one that can change prices, delete products and complete orders. On the test store, a Shop Manager's Application Password did two of those over MCP in two calls: one moved a product to the bin and the other marked an order completed.

One more detail affects client-side safety prompts. Because every ability runs through the single execute tool, a client sees one tool for reads and writes alike. The adapter version WooCommerce bundles marks that tool as not read-only, and the current standalone adapter marks it destructive.^[18][19] A client set to approve read-only tools without asking therefore cannot tell a product query from a product deletion. The permission decision has to happen on the server.

How do you stop a WooCommerce AI agent from writing?

The safe starting point is an agent account that can read what it needs and write nothing, with write access added later, deliberately, for named operations.

None of the stock roles fits. A Shop Manager can run all seven abilities. A Customer cannot run any of them: on the test store, a Customer's call to the product query was refused. There is no stock WooCommerce role that can read products and orders without also editing them.

A three-capability role does. The read abilities check two capabilities: reading private products and reading private orders. The write abilities check publishing, editing and deleting products, and editing orders.^[7][8] Among WooCommerce's seven canonical abilities, a custom role holding only WordPress's basic read capability plus read_private_products and read_private_shop_orders permits the two queries and denies the five writes. Other abilities and REST routes may also accept these capabilities, so check the account's access across the site. On the test store, an account with that role ran both queries and was refused all three writes it tried: deleting a product, changing an order status and adding an order note. You can create the role with a role-editor plugin or with WP-CLI's role and capability commands. Name it plainly, for example "Agent reader", so that nobody later mistakes it for a human account.

Two refinements are worth making:

• Leave orders out if the agent does not need them. WooCommerce warns that order and customer operations may expose personal data, including names, email and postal addresses and payment details.^[9] An agent that only answers catalogue questions should not hold read_private_shop_orders.
• Do not reach for manage_woocommerce by reflex. WooCommerce's extensions are adding read-only abilities of their own, for subscriptions, payments, shipping and more. WooCommerce says their execution still runs each ability's permission callback, "typically requiring a store-management or admin capability".^[20] Adding that capability to the reader role widens what the account can do across the store, so treat it as a decision for each extension, made after reading what it checks.

The role is the boundary everywhere, not only over MCP. An Application Password authenticates its user to the whole WordPress REST API, and to XML-RPC where that is enabled.^[21] On the test store, the Shop Manager's MCP password changed a product's price directly through WooCommerce's REST API and listed customers, without going near MCP. The reader's password could list products through the same API and was refused when it tried to create one. Whatever the agent's account can do through REST, the agent can do, so size the role for the whole API.

One account and one password per agent. Give each client its own WordPress user and its own Application Password, named after the client. Application Passwords can be revoked one at a time from the user's profile, which is the whole point of having one per client.^[9][21] WordPress makes them available on HTTPS sites and on sites with a local environment type, and WooCommerce's documentation also asks for permalinks other than "Plain".^[9][22] The earlier article WordPress MCP Server: Least-Privilege Abilities for Claude Code and Codex covers the availability rules, agent accounts, permission callbacks and the filter that can undo them, and all of it applies to WooCommerce's abilities too.

The WooCommerce MCP switch is not a security switch. Turning the feature off removes both WooCommerce-provided MCP endpoints; on the test store both returned "not found". It does not remove the abilities. WooCommerce says plainly that the feature flag "does not gate ability registration and it does not gate the Abilities REST API surface".^[6] On the test store, with the feature off, the reader's password still ran the product query through the Abilities API's REST route. And if the standalone MCP Adapter plugin is also installed, as the WordPress MCP article describes, the shared MCP endpoint keeps serving WooCommerce's abilities whatever WooCommerce's own setting says. Control access with roles and passwords; use the feature switch only to tidy up.

Visible is not usable. The shared endpoint lets any logged-in user with the basic read capability list abilities.^[9] On the test store, a Customer saw all seven WooCommerce abilities in the list, and was refused when it tried to run one. A list of tools in a client's panel tells you what is exposed, not what that account may do. Test with the agent's own account.

How do you migrate a WooCommerce MCP client, step by step?

The order below keeps the old connection working until the new one is proven, then retires its credentials.

1. Find every client and what it uses. Search for configurations that point at /woocommerce/mcp or set an X-MCP-API-Key: MCP settings in Claude Code, Claude Desktop, Cursor and VS Code, shared project configuration files, automation scripts and CI jobs. For each, list which old tools its agent actually calls. Map them across: listing or retrieving products becomes the product query; listing or retrieving orders becomes the order query; product create, update and delete map one to one; an order update becomes either a status change or a note. Anything left over, such as order creation, needs the REST API or a custom ability.

2. Decide what each agent may do. Start from the reader role above. Grant a write only where the agent's job needs it, and then to a separate account, so that a reporting agent and a catalogue-editing agent never share credentials.

3. Create the account and the password. Create the WordPress user with the chosen role, then create an Application Password on that user's profile, named after the client. WordPress shows it once. Store it in the client's secret store or environment, never in a file under version control; WooCommerce's documentation makes the same point about MCP configuration files.^[9]

4. Change the client entry. For a remote store, keep the same proxy and change two things: the URL now ends in /wp-json/mcp/mcp-adapter-default-server, and the custom API-key header gives way to the proxy's username and password settings, which take the agent user and its Application Password. WooCommerce's MCP documentation gives the exact configuration for Claude Desktop, Claude Code, Cursor and VS Code.^[9] For a local development store, the WP-CLI route with the user set to the agent account avoids a password altogether.^[9]

5. Prove it with the agent's account. Ask the client to list abilities: you should see the seven WooCommerce abilities, plus any that extensions, other plugins or WordPress itself expose. Run one query. Then ask for a write the account should not have, such as moving a test product to the bin, and confirm that it is refused. A migration is not finished until a refusal has been seen.

6. Update the agent's instructions. If an AGENTS.md file, a system prompt or a saved workflow names the old tools, rewrite it in terms of abilities: "use the order query ability", not "call woocommerce-orders-list". Agents that discover abilities by themselves cope well, but explicit instructions written for the old names will mislead them.

7. Retire the old client credentials. Once every client works on the new endpoint, identify the WooCommerce REST API keys those clients used, under WooCommerce, Settings, Advanced, REST API.^[12] Check whether another integration shares each key before revoking it. Revocation blocks that credential, but the deprecated endpoint remains available to other valid WooCommerce REST API keys.^[13] The settings screen cannot disable it independently because the same WooCommerce MCP feature controls both endpoints.^[4][9]

How do you add your own WooCommerce ability?

The seven canonical abilities cover common catalogue and order work. A store will soon want something they do not cover: an operation unique to its business, or a narrower version of an existing one.

Narrowing is the case people miss. Changing an order's status and adding an order note both check the same permission: editing that order.^[8] A role cannot grant one without the other. If an agent should be able to annotate orders but never change their status, the clean answer is a custom ability that adds notes only, checks a capability you create for that purpose, and is granted to the agent's role alone.

WooCommerce documents two ways to register one.^[6][9]

• Through the Abilities API directly. Register a category on the Abilities API's category hook, then the ability on its main hook, with a label, a description, input and output schemas, an execute callback and a permission callback. This is the route in WooCommerce's MCP documentation, and it suits a store's own plugin.^[9]
• Through WooCommerce's definition classes. Extensions can add a class implementing WooCommerce's ability definition interface through the woocommerce_ability_definition_classes filter, which places the ability in WooCommerce's own loading path.^[6]

Either way, a few rules decide whether the ability behaves:

• Use your own prefix. The woocommerce/ prefix is reserved for WooCommerce core. If a plugin registers an ability under a canonical WooCommerce name, WooCommerce unregisters it, logs a warning and registers its own. Set the category to woocommerce when the ability belongs with store operations.^[6]
• Expose it deliberately. Set the MCP metadata to public, with the type tool, if agents on the shared endpoint should see it, and set show_in_rest if it should appear in the Abilities REST routes.^[9] Add the old endpoint's opt-in flag, expose_in_deprecated_woocommerce_mcp, only if a client that has not moved yet still needs the ability there, and remember that a read key does not limit it on that endpoint. It must be the boolean true; values such as 1 or the string "true" do not count.^[6] WooCommerce's advice for internal or experimental abilities is to leave the MCP metadata off until they are designed for it.^[6]
• Make the permission callback the gate. Check a specific capability, and for anything that acts on one product or order, check it against that object, as WooCommerce's own abilities do.^[7][8] Exposure metadata controls discovery and execution through the shared adapter, while the permission callback decides whether the authenticated user may perform the operation. Removing MCP exposure does not remove access through REST when show_in_rest remains enabled.^[6][18]
• Describe the ability honestly. Mark reads as read-only and idempotent, and writes as destructive where they are. These annotations are hints for clients, not enforcement. The WordPress agent skills that WooCommerce points extension authors to include a verification skill with a "readonly-but-writes detector" for exactly this mistake.^[20]
• Keep the input schema strict. WooCommerce's abilities reject unknown fields and unsupported values before they run.^[6] Do the same, so that an agent's improvised parameter fails loudly instead of being ignored.

Letting an AI coding agent write it. WooCommerce points extension authors to two sets of agent skills for this job: WordPress's own, which audit a plugin, propose abilities and verify them, and WooCommerce's overlay, an end-to-end implementation playbook. They install into Claude Code, Codex or Cursor.^[20] They speed up the scaffolding. They do not decide which capability an ability should check, so review every permission callback yourself, and test the finished ability with the agent's own account: one call that should succeed and one that should be refused.

What could change next for WooCommerce MCP?

Three things are moving, so check them before relying on this guide for long.

• The old endpoint's removal. The deprecated endpoint remains available in the 11.2.x releases covered here. WooCommerce's 10.9 notice named no removal version, but its current documentation says WooCommerce 11.3 removes /woocommerce/mcp, its REST-derived abilities and the opt-in flag for them.^[6][9] The 11.3 release was still in development when this was checked, so move clients before it ships rather than after.
• The preview status. The documentation still warns of possible breaking changes.^[9] WooCommerce's engineering post describes the seven abilities as a first set, with "still gaps to close".^[6]
• The adapter's home. WooCommerce 11.1.2 bundles MCP Adapter 0.3.0 as a Composer library, and 11.2.0 still does.^[23][24] Adapter 0.7.0, released on 2 October 2026, is the first version in the WordPress.org plugin directory, and it deprecates exactly that bundled use: "Install the plugin instead." It also changes how custom transports must be built, which is how WooCommerce implements its old endpoint.^[25] A maintenance release, 0.7.1, followed on 16 October 2026.^[26] On the test store, WooCommerce 11.1.2 with the 0.7.0 plugin active served both endpoints and loaded the plugin's adapter. The reader could query products and was refused product deletion; on the deprecated endpoint, a read key could list products and was refused deletion. Expect WooCommerce to change how it ships the adapter; it says it will follow the upstream direction, and its current documentation already says WooCommerce does not bundle the adapter.^[6][9] The WordPress 7.2 roadmap, aiming for early December 2026, plans administrator controls over which abilities are exposed, and agent identities separate from human accounts. That is a plan, not a release, and agent identity in particular would change the advice here.^[27]

What should you remember when moving a WooCommerce MCP client?

• 10.9 added seven canonical abilities on the shared WordPress MCP endpoint as the successor to the beta's nine REST-shaped tools. The old /woocommerce/mcp endpoint still works in the 11.2.x releases covered here but is deprecated, and the current documentation says 11.3 removes it.
• Moving a client changes four things: the address, the credential (an Application Password, not a REST API key), the tools (three generic ones, not nine named ones) and where read-only is enforced.
• A read-only API key does not carry over. Build a role with read, read_private_products and, only if needed, read_private_shop_orders, and give each agent its own account and password.
• The role limits the agent everywhere, because an Application Password works across the whole REST API.
• The WooCommerce MCP switch is not a security control. The abilities stay reachable through REST, and through MCP if the adapter plugin is installed.
• Narrow with custom abilities. Use your own prefix, a specific capability check, honest annotations and a strict schema, and test with the agent's account until you have seen a refusal.

References

Numbers in square brackets in the text link to these sources.

1. WooCommerce on GitHub: releases (opens in a new tab).Used for: the 11.2.0 and 11.2.1 releases and their dates.
2. WooCommerce Developer Blog: WooCommerce 10.3: COGS comes to core and MCP beta (opens in a new tab).Used for: the 10.3 beta and its release date.
3. WooCommerce Developer Blog: Call for Testing: WooCommerce MCP Beta (opens in a new tab).Used for: the nine beta operations and key-based sign-in.
4. WooCommerce 11.1.2 source: MCPAdapterProvider.php (opens in a new tab).Used for: the bundled adapter and the single feature switch.
5. WooCommerce Developer Blog: WooCommerce 10.9 (opens in a new tab).Used for: the 10.9 release date and the rebuilt abilities.
6. WooCommerce Developer Blog: Introducing canonical WooCommerce abilities for products and orders (opens in a new tab).Used for: the seven abilities, the deprecation notice, the opt-in flag and the migration checklist.
7. WooCommerce 11.1.2 source: product and order domain abilities (opens in a new tab).Used for: the permission each ability checks and its read or write kind.
8. WooCommerce 11.1.2 source: wc-rest-functions.php (wc_rest_check_post_permissions) (opens in a new tab).Used for: how product and order permissions are checked.
9. WooCommerce Developer Docs: Model Context Protocol (MCP) (opens in a new tab).Used for: setup, Application Passwords, preview status and the deprecated endpoint.
10. WooCommerce 11.1.2 source: FeaturesController.php (opens in a new tab).Used for: the experimental flag in 11.1.2.
11. WooCommerce 11.2.0 source: FeaturesController.php (opens in a new tab).Used for: the experimental flag in 11.2.0.
12. WooCommerce 10.8.0 MCP documentation (docs/features/mcp/README.md) (opens in a new tab).Used for: the old client setup and API key header.
13. WooCommerce 11.1.2 source: WooCommerceRestTransport.php (opens in a new tab).Used for: how the old endpoint checks key permissions.
14. WordPress REST API Handbook: Authentication (opens in a new tab).Used for: why Application Passwords are preferred.
15. WordPress/mcp-adapter v0.3.0 source: DefaultServerFactory.php (opens in a new tab).Used for: the three tools the default server registers.
16. WooCommerce REST API documentation: authentication and key permissions (opens in a new tab).Used for: what read and write keys allow.
17. WooCommerce 11.1.2 source: RestAbilityFactory.php (opens in a new tab).Used for: how the old abilities were derived from REST routes.
18. WordPress/mcp-adapter v0.3.0 source: ExecuteAbilityAbility.php (opens in a new tab).Used for: the execute tool in the bundled adapter.
19. WordPress/mcp-adapter v0.7.0 source: ExecuteAbilityAbility.php (opens in a new tab).Used for: the execute tool in the current adapter.
20. WooCommerce Developer Blog: Expanding Abilities across WooCommerce Extensions (opens in a new tab).Used for: extension abilities and the agent skills for authors.
21. Make WordPress Core: Application Passwords: Integration Guide (opens in a new tab).Used for: what an Application Password can reach and revocation.
22. WordPress Developer Resources: wp_is_application_passwords_available() (opens in a new tab).Used for: when Application Passwords are available.
23. WooCommerce 11.1.2 source: composer.lock (opens in a new tab).Used for: the adapter version bundled in 11.1.2.
24. WooCommerce 11.2.0 source: composer.lock (opens in a new tab).Used for: the adapter version bundled in 11.2.0.
25. WordPress/mcp-adapter on GitHub: release v0.7.0 (opens in a new tab).Used for: the 0.7.0 release and its deprecation of bundled use.
26. WordPress/mcp-adapter on GitHub: release v0.7.1 (opens in a new tab).Used for: the 0.7.1 maintenance release.
27. Make WordPress Core: Roadmap to 7.2 (opens in a new tab).Used for: the planned exposure controls and agent identities.