Core MCP server

Connect any MCP-compatible AI client to the Core API for validated reads, writes, and operational workflows

The Commerce Layer Core MCP Server connects AI agents to the Core API with built-in schema discovery, preflight validation, and documentation retrieval. It is the supported integration path for bringing AI agents into your Commerce Layer environment.

What is the Core MCP?

The Commerce Layer Core MCP is an HTTP MCP server that gives AI agents structured, validated access to the Core API. It exposes a set of typed tools — for discovering resources, reading data, and writing records — that AI clients can call directly.

The server is available at the following URL:

https://core-mcp.commercelayer.io/mcp

Opening this URL in a browser returns an error. It is an MCP endpoint, not a web page — use it only inside an MCP client configuration.

It's compatible with Claude, ChatGPT, Cursor, VS Code with GitHub Copilot, and any other client that implements the Model Context Protocol.

Why does it exist?

The Core API covers a large surface area: JSON:API resources, relationships, filter predicates, sparse fieldsets, includes, and custom triggers. Without additional context, an AI agent interacting with it directly would face recurring failure modes: invalid filter shapes, confused identifiers (order number vs. order ID, SKU code vs. SKU ID), and writes that fail silently or produce unexpected results.

The Core MCP addresses this by embedding schema discovery, preflight validation, and Commerce Layer-specific conventions directly into the agent's tool loop. The agent understands the data model at inference time, invalid queries are caught before they reach the API, and platform-specific rules — like when to use the list_related_resources tool or how identifiers map to path segments — are encoded into the server instructions rather than left to chance.

What can you ask it?

Once connected, you can ask your AI assistant things like:

• "Create an order for customer X with SKUs A and B in US market."
• "Are there any orders with an abnormal number of line item errors?"
• "Show me all orders placed in the last 24 hours that are authorized but not fulfilled."
• "Who are the top 10 customers by order count this month?"
• "What fields can I filter orders by?"
• "What does the Create SKU endpoint require?"

The agent uses the get_resource_schema tool to understand the data model, validates its query, calls the Core API, and interprets the response — all within the same session.

How to connect

The Core MCP uses HTTP transport. There is no binary to install or build step required. Just register the endpoint URL in your MCP client's configuration.

Claude Desktop

1

Get your access token

You'll need a Commerce Layer access token. Generate one from the Dashboard under Settings > API credentials, or use the OAuth 2.0 flow when connecting via the Claude Desktop UI (see the next step).

2

Add the Core MCP server

You have two options:

Connect via the Claude Desktop UI (OAuth)

Open Claude Desktop, click Customize in the compose area, and select Add connector. Enter a service name — e.g. Commerce Layer Core MCP — and the endpoint URL. Follow the OAuth 2.0 authorization prompts to grant access to your Commerce Layer account:

https://core-mcp.commercelayer.io/mcp

Connect via the config file (bearer token)

Open your claude_desktop_config.json file:

• MacOS — ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows — %APPDATA%\Claude\claude_desktop_config.json.

Add the following entry under mcpServers:

{
  "mcpServers": {
    "commercelayer-core": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://core-mcp.commercelayer.io/mcp",
        "--header",
        "Authorization: Bearer {{your_access_token}}"
      ]
    }
  }
}

3

Restart Claude Desktop

Save the file and restart Claude Desktop. The Core MCP server will be available in your next conversation.

For the full setup reference, see the Claude Desktop MCP guide.

Cursor

VS Code

Authentication and permissions

Every request to the Core MCP requires a valid Commerce Layer access token. Commerce Layer supports three token types, each with a different scope of permissions:

• Sales channel tokens are obtained via the client credentials flow using the client ID of a set of sales channel API credentials. They carry the permissions defined for that sales channel — typically limited to storefront operations such as browsing catalogs, creating carts, and placing orders. The exact scope depends on the sales channel configuration.
• Integration tokens are obtained via the OAuth 2.0 client credentials flow using a client ID and client secret from a set of integration API credentials. They are the recommended choice for automated or server-side agent setups. The integration's role determines what resources the token can read and write.
• OAuth 2.0 tokens are obtained via the authorization code flow — the user authorizes the AI client through a browser and the client receives a short-lived token scoped to that user's permissions. Clients that support OAuth 2.0 discovery natively can use this flow without any manual token management.

To restrict what an agent can do:

1. Create a dedicated role in the Dashboard (Settings > Roles) with only the permissions it needs — specific resources, specific operations (read, create, update, destroy).
2. Assign that role to the integration you use for the Core MCP.

This limits the blast radius if a token is misused or exposed.

You can generate an access token from a set of API credentials as explained in the Commerce Layer authentication guide. You can create a set of API credentials in the Commerce Layer Dashboard under Settings > API credentials, or programmatically via the Provisioning API.

List of tools

The following tools are available. Discovery tools are safe to call at any time. Write tools (i.e. the ones that can create, update, or delete resources) require a token with the appropriate permissions for your organization.

Can write?

Tool	Can write?	Description
load_core_mcp_setup		Loads server rules for AI clients that hide system prompts. Call this at the start of each session if your client does not expose system prompt instructions.
list_resource_types		Lists all resource types in the organization, with collection path segments.
get_resource_schema		Returns the full schema for a specific resource type.
list_resources		Returns a paginated list of resources with filter, sort, include, and fieldset support.
get_resource		Fetches a single resource by ID.
list_related_resources		Fetches related resources via a relationship link.
create_resource		Creates a resource after schema and docs validation.
update_resource		Updates a resource after schema and docs validation.
delete_resource		Deletes a resource by ID.
search_documentation		Searches Commerce Layer documentation, scoped to Core API content.
get_doc_page		Fetches a specific documentation page by URL.