# MCP overview

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

Section: Commerce · MCP
Canonical URL: https://docs.omniretailconnect.nl/commerce/mcp/overview

## 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](https://docs.omniretailconnect.nl/commerce/mcp/tools.md) (the first read and write tools) and on the pages for [catalogue write tools](https://docs.omniretailconnect.nl/commerce/mcp/catalogue-tools.md), [discount tools](https://docs.omniretailconnect.nl/commerce/mcp/discount-tools.md), [order tools](https://docs.omniretailconnect.nl/commerce/mcp/order-tools.md) and [content tools](https://docs.omniretailconnect.nl/commerce/mcp/content-tools.md).

## 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](https://docs.omniretailconnect.nl/commerce/getting-started/limits.md#pagination).
- Unknown arguments are rejected with `invalid_argument`.

> **Note — 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](https://docs.omniretailconnect.nl/commerce/api/overview.md).

## Before you connect

1. Ask the shop administrator for the endpoint URL and a token, created in the shop admin ([Authentication and tokens](https://docs.omniretailconnect.nl/commerce/getting-started/authentication.md#creating-tokens)).
2. Connect a client: [Claude Code](https://docs.omniretailconnect.nl/commerce/mcp/connect-claude-code.md), [other clients](https://docs.omniretailconnect.nl/commerce/mcp/connect-other-clients.md), or hand the task to an [AI agent](https://docs.omniretailconnect.nl/commerce/mcp/connect-with-an-agent.md).
3. Read [Privacy and security](https://docs.omniretailconnect.nl/commerce/mcp/privacy-and-security.md) if the client is a hosted AI service or the token can write.