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

# Security

Connecting an AI agent to Commerce Layer through MCP gives it the ability to read your commerce data and — depending on the token you use — create, update, and delete resources. Read below to learn more about the practical steps you need to follow to keep that surface area under control.

{% embed url="<https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices>" %}

## Risk surface by server

Not all three MCP servers carry the same risk. Understanding what each one can do is the starting point.

<table><thead><tr><th width="194.87109375">Server</th><th width="132.36328125">Transport<select><option value="6ZobaFFPgl5Y" label="HTTP" color="blue"></option><option value="0JKJiqblSR2Q" label="SSE" color="blue"></option><option value="pApgIcNQXoJf" label="STDIO" color="blue"></option></select></th><th width="121.78515625" data-type="checkbox">Can write?</th><th>Abilities</th><th>Required auth</th></tr></thead><tbody><tr><td><strong>Core MCP</strong></td><td><span data-option="6ZobaFFPgl5Y">HTTP</span></td><td>true</td><td>Create, update, delete</td><td>Bearer token or OAuth 2.0</td></tr><tr><td><strong>Metrics MCP</strong></td><td><span data-option="6ZobaFFPgl5Y">HTTP</span></td><td>false</td><td>Read-only analytics</td><td>Bearer token or OAuth 2.0</td></tr><tr><td><strong>Documentation MCP</strong></td><td><span data-option="6ZobaFFPgl5Y">HTTP</span></td><td>false</td><td>Read-only docs</td><td>None</td></tr></tbody></table>

{% hint style="info" %}
The [Core MCP](/ai/mcp/servers/core.md) is the only server that can modify your data. Everything below is primarily relevant to it.
{% endhint %}

## Use a scoped token

The Core MCP inherits whatever permissions the token you supply carries. An integration token scoped to admin access can delete orders, wipe SKUs, or update pricing — and so can any agent using it.

{% content-ref url="/spaces/-LgByaSP8eKjad-MIuHE/pages/-LgCGPTjMSTg9sVBpFDk" %}
[Authentication](/core/authentication.md)
{% endcontent-ref %}

{% hint style="warning" %}
We strongly recommend creating a dedicated API credential for MCP use.
{% endhint %}

You can do it via the [Provisioning API](/provisioning/api-reference/api_credentials.md) or directly in the Commerce Layer Dashboard from the dedicate section — *Developers > API Credentials*. For more granular access control you can also set up specific Roles in *Settings > API Roles*. Some examples:

<table><thead><tr><th>Agent</th><th width="230.51171875">Scope</th><th>Permissions</th></tr></thead><tbody><tr><td><strong>Read-only agents</strong></td><td>Analytics, reporting, Q&#x26;A, etc.</td><td>Grant read access only</td></tr><tr><td><strong>Agents that create content</strong></td><td>Draft orders, SKUs, etc.</td><td>Add create access for the desired specific resource types.</td></tr><tr><td><strong>Agents that need full CRUD</strong></td><td>Create, update, or delete resources</td><td>Be deliberate and add write and delete access only for the resources you need.</td></tr></tbody></table>

{% hint style="danger" %}
Never use your personal admin token or broad integration credentials as the MCP token. If the agent misbehaves or the token is exposed, you want to be able to revoke it without taking down anything else.
{% endhint %}

{% hint style="info" %}
The [Metrics MCP](/ai/mcp/servers/metrics.md) is read-only by design — no additional scoping is needed. It supports both OAuth 2.0 and integration token authentication.
{% endhint %}

## Prefer OAuth over static tokens

When using Claude Desktop, ChatGPT, or another client that supports [OAuth 2.0](https://oauth.net/2/), use that flow instead of pasting a [bearer token](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/) into the config. Both the Core MCP and the Metrics MCP support OAuth 2.0 discovery natively:

1. The client requests authorization through a browser.
2. You approve it from the Commerce Layer Dashboard.

{% hint style="warning" %}
OAuth tokens are short-lived and tied to an authorization session. A static Bearer token can sit in a config file indefinitely and be accidentally committed to a repository or shared in a screenshot.
{% endhint %}

## Review tool calls before approving

Most AI clients show you a tool call before it executes and ask for confirmation.

{% hint style="warning" %}
Do not enable auto-approval for MCP. Always carefully review what the tool is about to perform.
{% endhint %}

This is especially important for tools that can create, update, or delete resources — these are real API writes that take effect immediately.

Before approving a tool call, check:

* **The resource type and ID** — Is this the right record?
* **The attributes being changed** — Is the payload what you expect?
* **The type of operation** — A delete is irreversible, make sure the agent isn't over-reaching.

{% hint style="info" %}
If you're exploring or testing, point the Core MCP at a staging or test organization. Commerce Layer's API supports [test mode](/core/api-specification.md#environments) — use it.
{% endhint %}

## Conversation data and prompt injection

Two risks apply any time you use an AI client connected to the Core MCP:

1. **Data leakage** — When the agent fetches order data, customer emails, or pricing, that information enters the conversation context. If you share the conversation link or if your AI provider uses conversations for model training, that data travels with it. Check your provider's privacy settings and disable conversation training for sessions where you're working with production data.
2. **Prompt injection** — If you ask the agent to read external content (a webpage, a document, a support ticket) malicious instructions embedded in that content can redirect the agent's next action. This is a real and documented attack class. Be cautious when combining MCP tool use with browsing or document reading in the same session.


---

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