Saleor MCP Server

Quickstart

1. Grant access

   Saleor MCP is available only to Saleor Cloud users. It may be preinstalled in new environments. If it isn't installed, go to Dashboard → Extensions → Explore and install it. Then open Saleor MCP in Dashboard. Choosing the app's permission ceiling requires MANAGE_APPS; assigning MCP permissions to Dashboard permission groups requires MANAGE_STAFF. A group with no assignment gets no data access.

2. Connect a client

   Open Saleor MCP in Dashboard and go to the app's Connection page. Copy the setup instructions for your client from there.

   The client opens a browser to sign in with your Saleor Cloud account and approve the permissions it may use.

3. Try it

   Ask the assistant to call connection_info, or start from the explore_saleor prompt, which walks it through the discover-then-run loop.

Authentication

There are two ways to connect. The server tells them apart by the bearer token it receives; a request without a valid token is rejected.

MCP clients never receive a Saleor token.

App token setup

{
  "mcpServers": {
    "saleor": {
      "type": "http",
      "url": "https://mcp-preview.saleor.app/mcp",
      "headers": {
        "Authorization": "Bearer <credential from Dashboard>"
      }
    }
  }
}

Calling the server directly

The transport is stateless Streamable HTTP: every request is a self-contained POST answered with JSON. There is no session to initialize and no server-initiated stream.

curl -X POST 'https://mcp-preview.saleor.app/mcp' \
  -H 'Authorization: Bearer <credential>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tools

GraphQL tools return Saleor's response untouched, as { data, errors }, both as text and as structuredContent.

Example call

{
  "query": "query Products($first: Int!) { products(first: $first) { edges { node { id name } } } }",
  "variables": {
    "first": 5
  }
}

Also exposed

• Resource saleor://schema/graphql: the full schema of the connected environment as SDL.
• Prompt explore_saleor: instructions for the discover-then-run loop.

Permissions

The app and user permissions limit which data MCP can access. Group policy controls where queries can start.

For example, a user holds MANAGE_ORDERS and MANAGE_PRODUCTS, the app is granted both, but the group policy gives their group only MANAGE_PRODUCTS. Through MCP they can start product queries. Results may also include related order data if Saleor allows it, even though Orders is not selected.

When connecting, the user can approve fewer query categories. This limits where queries can start, but does not block related data from other categories. All three levels are checked on every request. Removing access takes effect immediately; adding a category makes it available for new consent, without expanding an existing connection's approval. App-token connections act as the app, so only level 1 applies to them.

Permissions use Saleor's own permission codes, such as MANAGE_PRODUCTS. MCP checks the query’s starting fields before sending it to Saleor. Saleor checks access to related data using the permissions shared by the user and app. For what each permission covers, see Permissions in the Saleor documentation.

After a permission change

Ask the assistant to call connection_info. For user OAuth connections, permissions lists effective access, availablePermissionslists access allowed by the current user, app, and group policy, and permissionsRequiringConsent lists categories that still need your approval. Your staff account's permissions alone do not establish MCP access.

1. When your request needs a category listed in permissionsRequiringConsent, the assistant should ask, "Should I initiate the permission upgrade?"
2. After you agree, the assistant calls connection_info withupgradePermissions containing only the additional permissions needed and gives you the returned browser approval link. The link expires after ten minutes and can be used once. Creating or opening it does not grant access.
3. Open the link, sign in as the owner of the connected account, and review the additional access before approving. Approval updates this existing connection; you do not need to log the MCP client in again. Existing approved access is kept while it remains allowed by your current Saleor permissions and group policy.
4. Return to the assistant after approval. It should call connection_infoto confirm access and continue your original request. If you decline, it should stop without creating another upgrade request.
5. If the category is absent from availablePermissions, ask an administrator to check the app permissions, your staff permissions, and group policy. A permission upgrade cannot unlock unavailable access.

This browser approval flow updates the server-side grant for the current connection; it does not rely on the MCP client automatically handling an OAuth scope challenge. Standard OAuth reauthorization remains available through your client's Authenticate or OAuth login action. For Codex CLI, use codex mcp login <server-name>. Refreshing a token or repeating a denied query does not add permissions. User OAuth remains read-only.

Safety and limits

Writes are controlled by the server, not by the client. It runs in one of two modes:

Every GraphQL document is parsed and checked before it is sent to Saleor:

• A document holds queries or mutations, never both. Subscriptions are not supported.
• At most 100,000 characters, 10,000 tokens, and 500 root fields per operation.
• The credential fields accessToken and authToken cannot be selected.

Each tool call is recorded for 14 days and shown to users with MANAGE_APPS on the app's Activity page: the actor, the tool, the root operation names, and the outcome. Documents, variables, and responses are not stored.

Errors

Endpoints

All paths are relative to https://mcp-preview.saleor.app.