Store API MCP

Next to the Admin API MCP server at /api/_mcp, Shopware exposes a second, sales-channel-facing MCP server at /store-api/_mcp. It runs in a Store API sales-channel context instead of an Admin API session, which makes it the endpoint for shopper-side agents: an AI client that browses a shop, resolves the current context, and works with the same data a storefront would see.

Experimental

The Store API MCP server was introduced in Shopware 6.7.11.0 and, like the Admin API server, is experimental until Shopware 6.8. Tool names and payloads may still change.

Endpoint

Property	Value
Path	/store-api/_mcp
Methods	GET, POST, DELETE, OPTIONS
Transport	Streamable HTTP transport
Route scope	store-api

POST carries the JSON-RPC messages, GET opens a stream for server-initiated messages such as notifications/tools/list_changed, and DELETE ends the MCP session and releases its state.

If symfony/mcp-bundle is not installed, the endpoint answers with HTTP 404.

Authentication and authorization

The endpoint uses standard Store API authentication:

Header	Required	Purpose
sw-access-key	yes	Sales channel access key, as for any other Store API route
sw-context-token	no	Continues an existing sales-channel context. Without it, Shopware creates an anonymous context
Mcp-Session-Id	no	Returned by initialize; required for session-scoped features such as toolsets

No customer login is required. Whether a customer is logged in only changes what the context reports and what the sales-channel context permits.

Authorization differs from the Admin API server in two important ways:

• No Admin API ACL. Access is bounded by the Store API and the current sales-channel context, not by ACL privileges.
• No MCP allowlist. The per-integration and per-user allowlists apply to the Admin API server only. Every tool registered for the Store API scope is reachable by every client that can authenticate against the sales channel.

Keep both in mind when you register your own Store API tools: the sales channel context is the entire security boundary, so each tool must validate its own input and scope its own data access.

Progressive discovery

The Store API server uses the same progressive discovery flow as the Admin API server. A fresh session advertises only the discovery tools; every other tool is deferred until its toolset is enabled.

Behavior change

Since Shopware 6.7.14.0, a bare tools/list on /store-api/_mcp no longer returns the full catalogue. Even shopware-store-api-context is deferred behind the store-api toolset. Clients that expected the complete list must either follow the discovery flow or enable the toolset explicitly.

Since Shopware 6.7.15.0, clients can also select toolsets in the connection URL, for example /store-api/_mcp?toolsets=store-api. The tools of the named toolsets are part of the first tools/list, without a shopware-toolset-enable call. See Select toolsets when connecting.

The Store API server keeps its sessions in its own session store, separate from the Admin API server. An Mcp-Session-Id from /api/_mcp is not valid on /store-api/_mcp. See Session store.

The server advertises instructions during initialize that state the same thing:

This MCP server exposes Store API capabilities. All operations run in the current sales-channel context and use Store API authentication headers. The advertised tool list is not the full catalogue: if no advertised tool matches the requested action, call shopware-tool-search first instead of assuming the action is unsupported, then use shopware-toolsets-list and shopware-toolset-enable to make a matched tool callable if your client cannot invoke it inline.

Tools

The discovery tools use the same names and parameters as on the Admin API — see Discovery tools:

• shopware-tool-search
• shopware-toolsets-list
• shopware-toolset-enable

Core ships one domain tool:

shopware-store-api-context

Reads the current sales-channel context for the session. It has no parameters and belongs to the store-api toolset.

{
  "success": true,
  "data": {
    "salesChannelId": "...",
    "token": "...",
    "languageId": "...",
    "currencyId": "...",
    "customerAuthenticated": false,
    "customerId": null
  }
}

If the request carries no resolvable sales-channel context, the tool returns No Store API sales-channel context is available for this MCP request.

Core registers no prompts or resources for the Store API scope.

Sessions and rate limiting

MCP sessions live in the Store API server's own session store. Enabled toolsets are stored in the mcp_toolset_session table, which both endpoints share, including its daily cleanup task. See Session store. Toolset names are not namespaced per endpoint.

Rate limiting uses its own bucket, mcp_store_api: 120 requests per minute and 600 per 10 minutes, keyed on the sales channel and context token, plus an additional per-client-IP limit. The limits are deliberately tighter than the Admin API's, because a context token is cheap to rotate. See Rate limiting.

Advertising the endpoint

Headless and API sales channels can advertise the endpoint through the agentic file family, in /.well-known/ai-catalog.json. Shopware adds the entry only when all of the following are true:

• The agentic file family is enabled for the sales channel in the Administration.
• The sales channel resolves a base URL from one of its domains.
• The sales channel is of type API (headless).

The generated entry looks like this:

{
  "identifier": "urn:air:example.com:server:store-api-mcp",
  "displayName": "Shopware Store API MCP Server",
  "type": "application/mcp-server-card+json",
  "url": "https://example.com/store-api/_mcp",
  "tags": ["shopware", "store-api", "mcp"],
  "capabilities": ["shopware-store-api-context"]
}

The endpoint itself has no toggle: it is reachable for every sales channel with a valid access key, whether or not it is advertised. See Agentic files for how to enable and override the templates.

Extending the Store API server

Registering a Store API capability works like the Admin API equivalent, but with its own service tags:

Tag	Registers
shopware.store_api_mcp.tool	A tool on /store-api/_mcp
shopware.store_api_mcp.prompt	A prompt on /store-api/_mcp
shopware.store_api_mcp.resource	A resource on /store-api/_mcp

Notes for extension developers:

• Use StoreApiMcpContextProvider to obtain the sales-channel context. There is no Admin API context and no requirePrivilege() equivalent.
• Assign a group with #[McpToolGroup] so clients can discover and enable your tools — the same grouping rules apply as for the Admin API. See Assign a tool group.
• Registering the same tool name for both scopes requires two classes. The MCP SDK binds a tool to the class that carries the #[McpTool] attribute, which is why core has separate Admin API and Store API discovery tool classes.
• bin/console debug:mcp lists the tools of both servers. Use bin/console debug:mcp --scope=store-api to show only the Store API server, and bin/console debug:mcp --native for prompts and resources.
• Capabilities are assigned to the Store API server by their shopware.store_api_mcp.* tag. No namespace or directory configuration is required.