Security

Practical security guidelines for connecting AI agents to Commerce Layer safely

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.

Security Best Practices - Model Context ProtocolModel Context Protocol

Risk surface by server

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

Server	Transport	Can write?	Abilities	Required auth
Core MCP	HTTP		Create, update, delete	Bearer token or OAuth 2.0
Metrics MCP	HTTP		Read-only analytics	Bearer token or OAuth 2.0
Documentation MCP	HTTP		Read-only docs	None

The Core MCP is the only server that can modify your data. Everything below is primarily relevant to it.

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.

Authentication

We strongly recommend creating a dedicated API credential for MCP use.

You can do it via the Provisioning API 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:

Agent	Scope	Permissions
Read-only agents	Analytics, reporting, Q&A, etc.	Grant read access only
Agents that create content	Draft orders, SKUs, etc.	Add create access for the desired specific resource types.
Agents that need full CRUD	Create, update, or delete resources	Be deliberate and add write and delete access only for the resources you need.

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.

The Metrics MCP is read-only by design — no additional scoping is needed. It supports both OAuth 2.0 and integration token authentication.

Prefer OAuth over static tokens

When using Claude Desktop, ChatGPT, or another client that supports OAuth 2.0, use that flow instead of pasting a bearer token 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.

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.

Review tool calls before approving

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

Do not enable auto-approval for MCP. Always carefully review what the tool is about to perform.

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.

If you're exploring or testing, point the Core MCP at a staging or test organization. Commerce Layer's API supports test mode — use it.

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.