> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/ai/mcp/servers/core.md).

# Core MCP server

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:

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

{% hint style="warning" %}
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.
{% endhint %}

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](https://docs.commercelayer.io/core/) covers a large surface area: JSON:API [resources](https://docs.commercelayer.io/core-api-reference/), [relationships](/core/fetching-relationships.md), [filter](/core/filtering-data.md) predicates, [sparse fieldsets](/core/sparse-fieldsets.md), [includes](/core/including-associations.md), 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](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http). There is no binary to install or build step required. Just register the endpoint URL in your MCP client's configuration.

{% tabs %}
{% tab title="Claude Desktop" %}
{% stepper %}
{% step %}

#### 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).
{% endstep %}

{% step %}

#### Add the Core MCP server

You have two options:

<details>

<summary><strong>Connect via the Claude Desktop UI (OAuth)</strong></summary>

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:

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

</details>

<details>

<summary><strong>Connect via the config file (bearer token)</strong></summary>

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`:

<pre class="language-json"><code class="lang-json">{
  "mcpServers": {
    "commercelayer-core": {
      "command": "npx",
      "args": [
        "mcp-remote",
<strong>        "https://core-mcp.commercelayer.io/mcp",
</strong>        "--header",
<strong>        "Authorization: Bearer {{your_access_token}}"
</strong>      ]
    }
  }
}
</code></pre>

</details>
{% endstep %}

{% step %}

#### Restart Claude Desktop

Save the file and restart Claude Desktop. The Core MCP server will be available in your next conversation.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
For the full setup reference, see the [Claude Desktop MCP guide](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop).
{% endhint %}
{% endtab %}

{% tab title="Cursor" %}
{% stepper %}
{% step %}

#### Open MCP settings

In Cursor, go to *Settings > Cursor Settings > MCP* and click *Add new MCP server*.
{% endstep %}

{% step %}

#### Configure the server

You have two options:

<details>

<summary><strong>Connect via OAuth</strong></summary>

In the editor that opens, paste the following snippet and give the server a name — e.g. `commercelayer-core`. Cursor will prompt you to authorize via OAuth 2.0 when it first connects to the server:

```json
{
  "mcpServers": {
    "Commerce Layer Core MCP": {
      "url": "https://core-mcp.commercelayer.io/mcp"
    }
  }
}
```

</details>

<details>

<summary><strong>Connect via bearer token</strong></summary>

In the editor that opens, paste the following snippet and give the server a name — e.g. `commercelayer-core`:

```json
{
  "mcpServers": {
    "Commerce Layer Core MCP": {
      "url": "https://core-mcp.commercelayer.io/mcp",
      "headers": {
        "Authorization": "Bearer {{your_access_token}}"
      }
    }
  }
}
```

</details>
{% endstep %}

{% step %}

#### Save the configuration

Click *Save*. The server will appear in your MCP tools list and will be available to the Cursor AI assistant.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
For the full setup reference, see the [Cursor MCP documentation](https://cursor.com/docs/context/mcp).
{% endhint %}
{% endtab %}

{% tab title="VS Code" %}
{% stepper %}
{% step %}

#### Configure the server

You have two options:

<details>

<summary><strong>Command palette</strong></summary>

Open the [Command Palette](https://code.visualstudio.com/docs/editing/userinterface#_command-palette) by pressing:

* **MacOS** — `Cmd+Shift+P`
* **Windows** — `Ctrl+Shift+P`

Run *MCP: Add Server*, select *Command (stdio)* as the transport type, then run:

```
npx mcp-remote https://core-mcp.commercelayer.io/mcp --header "Authorization: Bearer {{your_access_token}}"
```

</details>

<details>

<summary><strong>Configuration file</strong></summary>

Add the server directly to your `.vscode/mcp.json` file:

<pre class="language-json"><code class="lang-json">{
  "servers": {
    "commercelayer-core": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "mcp-remote",
<strong>        "https://core-mcp.commercelayer.io/mcp",
</strong>        "--header",
<strong>        "Authorization: Bearer {{your_access_token}}"
</strong>      ]
    }
  }
}
</code></pre>

</details>
{% endstep %}

{% step %}

#### Verify the connection

Once registered, GitHub Copilot in agent mode can use the Core MCP as a tool. Open a Copilot chat and confirm the server appears in the available tools list.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
For the full setup reference, see the [VS Code MCP guide](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
{% endhint %}
{% endtab %}
{% endtabs %}

### Authentication and permissions

Every request to the Core MCP requires a valid Commerce Layer access token. Commerce Layer supports [three token types](/core/api-credentials.md), 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](/core/api-credentials.md#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](/core/authentication.md#authorization-scopes) 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](/core/api-credentials.md#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](/core/api-credentials.md#webapp) 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.

{% hint style="info" %}
You can generate an access token from a set of API credentials as explained in the [Commerce Layer authentication guide](/core/authentication.md). You can create a set of API credentials in the Commerce Layer Dashboard under *Settings > API credentials*, or programmatically via the [Provisioning API](/provisioning/api-reference/api_credentials.md).
{% endhint %}

## 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.

<table><thead><tr><th width="251.22265625">Tool</th><th width="120.20703125" data-type="checkbox">Can write?</th><th>Description</th></tr></thead><tbody><tr><td><code>load_core_mcp_setup</code></td><td>false</td><td>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.</td></tr><tr><td><code>list_resource_types</code></td><td>false</td><td>Lists all resource types in the organization, with collection path segments.</td></tr><tr><td><code>get_resource_schema</code></td><td>false</td><td>Returns the full schema for a specific resource type.</td></tr><tr><td><code>list_resources</code></td><td>false</td><td>Returns a paginated list of resources with filter, sort, include, and fieldset support.</td></tr><tr><td><code>get_resource</code></td><td>false</td><td>Fetches a single resource by ID.</td></tr><tr><td><code>list_related_resources</code></td><td>false</td><td>Fetches related resources via a relationship link.</td></tr><tr><td><code>create_resource</code></td><td>true</td><td>Creates a resource after schema and docs validation.</td></tr><tr><td><code>update_resource</code></td><td>true</td><td>Updates a resource after schema and docs validation.</td></tr><tr><td><code>delete_resource</code></td><td>true</td><td>Deletes a resource by ID.</td></tr><tr><td><code>search_documentation</code></td><td>false</td><td>Searches Commerce Layer documentation, scoped to Core API content.</td></tr><tr><td><code>get_doc_page</code></td><td>false</td><td>Fetches a specific documentation page by URL.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.commercelayer.io/ai/mcp/servers/core.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.