> 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/metrics.md).

# Metrics MCP server

The Commerce Layer Metrics MCP Server connects AI agents to the Metrics API, giving them access to aggregated analytics over your organization's order, cart, and returns history. You interact with it in natural language — the agent picks the right query type, applies the correct filters, and returns the data.

## What is the Metrics MCP?

The Commerce Layer Metrics MCP Server is an HTTP MCP server that gives AI agents access to the Metrics API — aggregated analytics over your organization's data history, queried in natural language.

The server is available at the following URL:

```http
https://metrics-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 [Metrics API](https://docs.commercelayer.io/metrics/) is powerful but requires knowing which [query type](/metrics/getting-started/queries.md) to use, which [resource](/metrics-api-reference/resources/orders.md) to target , and how to structure [filters](/metrics/getting-started/filters.md) and groupings in the correct format.

Queries are organized into four types, each suited to a different kind of analytical question:

<table><thead><tr><th width="205.56640625">Query type</th><th>What it answers</th></tr></thead><tbody><tr><td><a href="/spaces/ASSiAvbL4nFnkl8plQy2/pages/JOA5KNnkuGOwyZK46kbP">Breakdown</a></td><td><em>"How many orders per market?"</em><br><em>"Revenue by currency?"</em></td></tr><tr><td><a href="/spaces/ASSiAvbL4nFnkl8plQy2/pages/cSmyA6B5kKaFRTzhe90S">Date breakdown</a></td><td><p><em>"Orders per month this year?"</em></p><p><em>"Weekly cart creation trend?"</em></p></td></tr><tr><td><a href="/spaces/ASSiAvbL4nFnkl8plQy2/pages/F8buZfBDrykBmdY2Niw8">Stats</a></td><td><p><em>"Average order value?"</em></p><p><em>"Total revenue in Q1?"</em></p></td></tr><tr><td><a href="/spaces/ASSiAvbL4nFnkl8plQy2/pages/3CLOdU7Id2oRvD2ZCUGf">Search</a></td><td><em>"Show me recent orders from Germany with status placed"</em></td></tr></tbody></table>

All four query types are available across three resources — [orders](/metrics-api-reference/resources/orders.md), [carts](/metrics-api-reference/resources/carts.md), and [returns](/metrics-api-reference/resources/returns.md) — giving you a flexible surface for reporting and analysis.

Without a layer of abstraction, answering an analytics question means knowing the API's exact shape before asking it. The Metrics MCP removes that overhead. The server's tool definitions embed the full filter and field schema, so the agent reasons over them at inference time and selects the right tool automatically — you ask a question in natural language, the server handles the translation.

## What can you ask it?

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

* *"What are the best-selling products in each of our markets this quarter?"*
* *"How many customers bought \[SKU name] in the last 90 days?"*
* *"Which products are most frequently bought together with our hero SKU?"*
* *"Show me the most recent carts containing \[product] from the US market."*
* *"How many orders were placed each day this week, and how does that compare to last week?"*
* *"What's our total revenue broken down by currency for this month?"*
* *"Who are our top 10 spenders in EUR?"*
* *"How many returns were requested in 2025, grouped by country?"*

The agent picks the right query type based on what you're asking, combining filters, groupings, and time ranges as needed.

## How to connect

The Metrics 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 Metrics 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 Metrics MCP` — and the endpoint URL. Follow the OAuth 2.0 authorization prompts to grant access to your Commerce Layer account:

```http
https://metrics-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-metrics": {
      "command": "npx",
      "args": [
        "mcp-remote",
<strong>        "https://metrics-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 Metrics 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-metrics`. Cursor will prompt you to authorize via OAuth 2.0 when it first connects to the server:

```json
{
  "mcpServers": {
    "Commerce Layer Metrics MCP": {
      "url": "https://metrics-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-metrics`:

```json
{
  "mcpServers": {
    "Commerce Layer Metrics MCP": {
      "url": "https://metrics-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://metrics-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-metrics": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "mcp-remote",
<strong>        "https://metrics-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 Metrics 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 Metrics MCP requires a valid Commerce Layer access token. Both OAuth tokens and integration tokens are supported:

* **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.
* **OAuth 2.0 tokens** are obtained via the [authorization code](/core/api-credentials.md#webapp) flow — Claude Desktop handles this automatically when you connect via the *Customize* UI. No manual token management needed.

{% hint style="info" icon="pen-nib-slash" %}
The Metrics API is read-only by design. There are no write operations — there is no risk of an agent modifying your data through this server.
{% endhint %}

To restrict what an agent can do:

1. Create a dedicated role in the Dashboard (*Settings > Roles*) with permissions limited to the markets, resources, or scopes your analytics use case requires.
2. Assign that role to the integration you use for the Metrics 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 server exposes two categories of tools:

* Multiple [query tools](#query-tools) covering all combinations of query type and resource.
* An [analysis tool](#analysis-tools) for product recommendation use cases.

### Query tools

These tools include the full query matrix across orders, carts, and returns:

<table><thead><tr><th width="260.3984375">Tool</th><th width="129.5625" data-type="checkbox">Can write?</th><th>Description</th></tr></thead><tbody><tr><td><code>orders-breakdown</code></td><td>false</td><td>Aggregate orders by a field with a selected operator.</td></tr><tr><td><code>orders-date_breakdown</code></td><td>false</td><td>Aggregate orders by date over a time interval.</td></tr><tr><td><code>orders-stats</code></td><td>false</td><td>Compute numeric stats over an orders field.</td></tr><tr><td><code>orders-search</code></td><td>false</td><td>Search and paginate actual order records.</td></tr><tr><td><code>carts-breakdown</code></td><td>false</td><td>Aggregate carts by a field with a selected operator.</td></tr><tr><td><code>carts-date_breakdown</code></td><td>false</td><td>Aggregate carts by date over a time interval.</td></tr><tr><td><code>carts-stats</code></td><td>false</td><td>Compute numeric stats over a carts field.</td></tr><tr><td><code>carts-search</code></td><td>false</td><td>Search and paginate cart records.</td></tr><tr><td><code>returns-breakdown</code></td><td>false</td><td>Aggregate returns by a field with a selected operator.</td></tr><tr><td><code>returns-date_breakdown</code></td><td>false</td><td>Aggregate returns by date over a time interval.</td></tr><tr><td><code>returns-stats</code></td><td>false</td><td>Compute numeric stats over a returns field.</td></tr><tr><td><code>returns-search</code></td><td>false</td><td>Search and paginate return records.</td></tr></tbody></table>

### Analysis tools

Use this tool when you want product affinity insights from historical order behavior:

<table><thead><tr><th width="260.2890625">Tool</th><th width="130.01171875" data-type="checkbox">Can write?</th><th>Description</th></tr></thead><tbody><tr><td><code>fbt</code></td><td>false</td><td><em>Frequently Bought Together</em> — based on your entire order history, retrieves items most frequently purchased alongside a given SKU, bundle, or array of items.</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/metrics.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.