Metrics MCP server

Connect any MCP-compatible AI client to the Metrics API for analytics queries in natural language

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:

https://metrics-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 Metrics API is powerful but requires knowing which query type to use, which resource to target , and how to structure filters and groupings in the correct format.

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

Query type	What it answers
Breakdown	"How many orders per market?" "Revenue by currency?"
Date breakdown	"Orders per month this year?" "Weekly cart creation trend?"
Stats	"Average order value?" "Total revenue in Q1?"
Search	"Show me recent orders from Germany with status placed"

All four query types are available across three resources — orders, carts, and returns — 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. 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 Metrics 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 Metrics MCP — and the endpoint URL. Follow the OAuth 2.0 authorization prompts to grant access to your Commerce Layer account:

https://metrics-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-metrics": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://metrics-mcp.commercelayer.io/mcp",
        "--header",
        "Authorization: Bearer {{your_access_token}}"
      ]
    }
  }
}

3

Restart Claude Desktop

Save the file and restart Claude Desktop. The Metrics 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 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 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 flow — Claude Desktop handles this automatically when you connect via the Customize UI. No manual token management needed.

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.

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.

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 server exposes two categories of tools:

• Multiple query tools covering all combinations of query type and resource.
• An analysis tool for product recommendation use cases.

Query tools

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

Can write?

Tool	Can write?	Description
orders-breakdown		Aggregate orders by a field with a selected operator.
orders-date_breakdown		Aggregate orders by date over a time interval.
orders-stats		Compute numeric stats over an orders field.
orders-search		Search and paginate actual order records.
carts-breakdown		Aggregate carts by a field with a selected operator.
carts-date_breakdown		Aggregate carts by date over a time interval.
carts-stats		Compute numeric stats over a carts field.
carts-search		Search and paginate cart records.
returns-breakdown		Aggregate returns by a field with a selected operator.
returns-date_breakdown		Aggregate returns by date over a time interval.
returns-stats		Compute numeric stats over a returns field.
returns-search		Search and paginate return records.

Analysis tools

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

Tool	Can write?	Description
fbt		Frequently Bought Together — based on your entire order history, retrieves items most frequently purchased alongside a given SKU, bundle, or array of items.