Skip to content
OmniRetailConnect Docs
Main site Demo aanvragen

Commerce · MCP

MCP overview

The endpoint, the transport, the fifteen read tools and the forty-five write tools of the Commerce MCP server.

View as Markdown

Endpoint

POST https://<your-shop-domain>/mcp/commerce

One endpoint for all MCP requests (JSON-RPC over HTTP).

The URL is the public base URL of the shop plus the MCP path. The default path is /mcp/commerce; the Connection details panel in the shop admin shows the full URL of this shop, so use that one. Only POST is served: GET and DELETE answer 405 with Allow: POST.

Transport and methods

  • MCP over HTTP with JSON-RPC 2.0 messages in the request body. Send Content-Type: application/json and Accept: application/json, text/event-stream.
  • The server is stateless: no initialize handshake and no session are needed before a call.
  • Supported methods are initialize, ping, server/discover, tools/list and tools/call. Any other method answers JSON-RPC "method not found" (-32601). A JSON-RPC notification (a message without an id, such as notifications/initialized) is accepted with 202 and an empty body.
  • The server offers tools only: no resources and no prompts.
  • Responses to routed requests carry Cache-Control: no-store. Responses the framework answers itself, such as OPTIONS, PUT and PATCH on the MCP URL, carry no-cache, private.

The tools

Fifteen read tools need the commerce.read scope, which every token has. tools/list only shows the tools the token is allowed to call.

Tools
Tool Purpose
search_products Find products by text, category or brand.
get_product One product by id or by the SKU of one of its variants.
check_sku_availability Bulk stock check for 1 to 50 SKUs.
search_orders Find orders, newest first.
get_order One order by reference or id.
list_categories The product category tree.
get_sales_summary Operational sales metrics for a date range.
list_brands, list_labels, list_tax_classes, list_properties The reference lists whose ids the catalogue write tools take.
list_discounts, get_discount The discount codes.
list_pages, get_page The CMS pages with their blocks, drafts included.

Forty-five write tools change data: the product catalogue (content, SEO, web address, variants, properties, labels, prices, sale prices, price breaks, stock, new products, images, brands, the label set, category placements, the category tree and featured products), discount codes, order status and shipments (never money), and CMS pages. Each only exists for a token with the matching write scope (commerce.write.products, commerce.write.collections, commerce.write.discounts, commerce.write.orders or commerce.write.content), and every change is recorded against the token. A token without a write scope is strictly read-only.

Inputs, limits and outputs are in the tool reference (the first read and write tools) and on the pages for catalogue write tools, discount tools, order tools and content tools.

What results look like

  • Tool results are returned both as structuredContent and as JSON text.
  • Money is always {"amount_minor", "currency", "formatted"}: amount_minor is an integer in cents, currency is EUR, and prices and order totals are tax-inclusive. Only EUR is supported.
  • List tools return items, next_cursor and has_more. There are no totals. See pagination.
  • Unknown arguments are rejected with invalid_argument.

Token channel

The MCP server needs a token with the mcp channel, which is the default for new tokens. A token that only has the api channel gets the same 401 as an unknown token. The read capabilities are also available as a REST API.

Before you connect

  1. Ask the shop administrator for the endpoint URL and a token, created in the shop admin (Authentication and tokens).
  2. Connect a client: Claude Code, other clients, or hand the task to an AI agent.
  3. Read Privacy and security if the client is a hosted AI service or the token can write.