Meet the Commerce Layer Core MCP.
Discover how the Commerce Layer Core MCP server gives AI agents secure, schema-aware access to commerce operations. Learn how discovery, validation, and documentation-aware workflows enable agents to work safely across the entire platform.
AI is rapidly becoming a new interface for commerce.
Teams are building assistants that answer operational questions, agents that automate workflows, and AI-powered experiences that interact directly with customers, orders, inventory, pricing, and fulfillment systems.
But most commerce platforms weren't designed for this shift. They expose APIs, yet their AI integrations often provide access to only a small subset of capabilities through custom connectors, proprietary abstractions, or simplified toolsets.
Commerce Layer takes a different approach.
Because Commerce Layer is 100% API-first, every capability of the platform is available programmatically. And because we believe AI agents are becoming first-class users of commerce systems, we built our platform to be agentic by design.
That means agents can work across 100% of Commerce Layer's resources — orders, customers, markets, pricing, inventory, promotions, shipments, payments, workflows, and more — while remaining grounded in the platform's schema, permissions model, and documentation.
The result is not just API access. It is a way for AI agents to understand, discover, validate, and safely operate a complex commerce system with the same depth and flexibility available to any Commerce Layer integration.
Why AI agents need more than API access
If you already work with Commerce Layer, you know the Core API is not a small surface. JSON:API resources, relationships, filters, sparse fieldsets, includes, custom triggers, and documentation. It is powerful on purpose.
Commerce Layer exposes a rich and flexible API surface. Providing AI agents with clearer guidance around resource structure, endpoint conventions, and field capabilities helps them interact with the platform more reliably and effectively.
We built the Commerce Layer Core MCP so agents can interact with the Core API the way integrators and operators already learn to:
- Discover the resources schema.
- Validate what you can before you call.
- Read the official docs before you mutate.
- Stay inside the same auth and scopes you use everywhere else.
Why MCP and not “just expose the API”?
Model Context Protocol (MCP) is how many assistants today discover tools, call them, and keep context. For Commerce Layer, MCP is the wire format between the client (Claude, ChatGPT, Perplexity, Inspector, your own host) and a server that knows the Core API.
We did not stop at thin wrappers around endpoints.
The Core API already ships public resources: machine metadata about types, filters, sort, includes, and relationships. The MCP’s job is to put that metadata and our official docs directly in the agent’s loop, so each tool call is informed by how the Core API actually behaves, not by whatever the model remembered from training.
In short:
How it works with the Core API
Before an agent can perform meaningful work on a commerce platform, it needs more than an authentication token and a list of endpoints. It needs a way to understand the structure of the system, validate its actions, and access the same guidance that developers rely on every day. The Commerce Layer Core MCP provides these capabilities through a set of mechanisms that work together to make interactions with the Core API safer and more reliable.
Discovery from public resources
The MCP loads and caches: GET /api/public/resources
Tools like list_resource_types and get_resource_schema expose that catalog to the agent:
- filterable and sortable fields
- fetchable attributes
- includable relationships
- collection path segments
- links to create/update reference pages when writes exist
That mirrors what experienced developers already do — check the catalog or API reference before a non-trivial list or write — except the agent can do it every turn without you pasting schema into the prompt.
Preflight validation on reads
The Core API can return a 200 OK while still allowing mistakes that cost you time:
- unknown filter predicates ignored
- invalid includes rejected late
- sort on a non-sortable field
On read tools only — list, retrieve, list related — the MCP validates the query against the public resources document before calling the Core API.
What gets validated
The goal of validation is not to restrict what agents can do, but to catch common mistakes before they reach the API. By checking requests against Commerce Layer’s resource metadata, the MCP can identify invalid parameters early and provide clearer feedback than a failed—or misleading—API response.
- Filter keys
Filter keys must match Commerce Layer predicate shapeattribute_matcher(e.g.status_eq,placed_at_gteq). Invalid filter key formats are detected during validation, allowing the MCP to return an error before executing the API request. The MCP does not prove the attribute itself is filterable on that resource — schema discovery is still required. - Includes and sorting
includeandsortqueries are validated against what public resources allows for that collection. - Sparse fieldsets
In case offields[...]queries, non-fetchable names are automatically removed, the read still proceeds, and the response includes an explicit preflight warning.
Documentation in the same session
Readable fields on a resource are often read-only on create.
The MCP connects to our docs search and page fetch so the agent can open the official Create or Update reference after get_resource_schema surfaces write_docs, instead of guessing required attributes from a list payload.
Rules that match the Core API semantics
Server instructions — and load_core_mcp_setup for clients that hide them — encode Commerce Layer specifics:
- Resource type for schema versus path segment for
/api/.... - Lookup via filters when the user names a record in business terms.
- When to use
list_related_resourcesinstead of a non-includable relationship. - How filtering with
filter[q]differs from sparse fieldsets.
Those rules exist because Commerce Layer’s conventions are not universal JSON:API. Agents need them spelled out.
What this looks like in practice
With discovery, validation, and documentation access working together, agents can move beyond simple API lookups and help answer operational questions about your commerce business. Instead of focusing on individual resources, they can reason across orders, customers, payments, shipments, and other related data.
You might ask:
- Who the latest customer is.
- Who has the most orders.
- Whether a customer’s orders show a pattern.
- If payments are authorized but fulfillment is stuck.
- Which orders have abnormal error counts.
- Whether there are cancellation or test bursts.
The agent should:
- List and sort using schema metadata.
- Pull related data where includes are allowed.
- Interpret statuses and counters from real responses.
That is operational work on your Commerce Layer data, not a single generic GET API call.
Who we built this for
We built it because agents are a new client of the same Core API you already trust — and that client needs:
- Discovery
- Guardrails on reads
- Docs-aware writes
All grounded in Commerce Layer’s catalog and reference.
If you are extending composable commerce with assistants, or debugging production behavior through a model, the MCP is the supported path to make that client behave like someone who has actually read the platform documentation.
Teams already using Commerce Layer
For teams already operating on Commerce Layer, the Core MCP is a natural extension of their existing workflows. It doesn’t introduce a new way of working so much as it removes friction from how people already interact with the platform—whether through support, operations, or development tasks.
- QA teams
Spotting blocked flows or noisy automation without one-off scripts. - Developers and solution engineers
Exploring the Core API, checking include/sort rules, and shaping payloads against the real reference.
Anyone doing quick operational analysis
Not every use case requires deep system knowledge or a dedicated workflow. Many questions are ad-hoc and time-sensitive: checking what’s happening in the system, validating assumptions, or quickly exploring patterns in commerce data. The Core MCP makes these lightweight investigations fast and accessible, without needing to switch tools or build custom queries. For example:
- Top customers
- Error-heavy orders
- Suspicious orders spikes
The Core MCP is where agents meet Commerce Layer properly
Commerce Layer was built for programmatic commerce — precise, composable, and opinionated by design. The Core MCP extends that to a new kind of client: AI agents that need to discover, validate, and act on your data without someone holding their hand through the API reference on every call.
Whether you're tracing a production incident, exploring the Core API for the first time, or building an assistant-powered workflow on top of your commerce stack, the MCP gives agents the same foundation experienced integrators rely on — schema awareness, documentation access, and guardrails that match how the API actually works.
It's available now. If you're already using Commerce Layer, it's the supported way to bring agents into the picture.