> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP servers
> Connect AI assistants like Claude or ChatGPT to Layers with Model Context Protocol servers for store management and storefront search.
Layers exposes two [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers that let AI assistants interact directly with your stores. Use them to manage merchandising, search tuning, catalog operations, and storefront queries through any MCP-compatible client.
| Server | Endpoint | Auth | Purpose |
| --------------------- | --------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
| Layers MCP server | `https://app.uselayers.com/mcp/v1` | OAuth (`mcp:use` scope) | Full store management — catalog, merchandising, search tuning, analytics, and more |
| Storefront MCP server | `https://app.uselayers.com/mcp/storefront/v1` | Storefront API token | Read-only storefront operations — search, browse, recommendations |
## Layers MCP server
The main MCP server exposes tools for managing your Layers stores. It uses OAuth authentication and requires the `mcp:use` scope.
### Connecting
Configure your MCP client with the following endpoint:
```
https://app.uselayers.com/mcp/v1
```
When you connect for the first time, you're redirected to the Layers dashboard to authorize the connection. After authorization, your MCP client stores the OAuth tokens and reconnects automatically.
MCP connections are scoped to specific stores **and** specific permissions. On the authorization screen, you choose which stores the connection can access and which of your own permissions it may use. A connection can never exceed your own access — and if your access is later reduced, the connection's access is reduced immediately to match.
Because connections are store-scoped, `store-list` returns only the stores granted to the connection. If a tool is called for a store that wasn't granted the permission it needs, the tool returns a permission error.
### Available tools
Most write tools are consolidated into a single `*-manage` tool per resource. Pass an `action` (for example `list`, `create`, `update`, `delete`) to control what the tool does, so listing and mutation share one tool per resource.
| Tool | Description |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `store-list` | List all stores you have access to |
| `store-details` | Get detailed information about a store, including resource counts |
| `store-search-configuration` | Get or update the dashboard-visible search configuration — brand and search prompts, image-search mode, excluded tags, text/image result balance, ranking signal weights, reranking strength, and diversity strength |
| `store-operational-status` | Inspect permission failures, sync blockers, and recent tasks for a store |
| `store-maintenance` | Inspect maintenance status. Admin operators can also run maintenance actions such as feature-flag updates, cache purges, and vector index rebuilds |
| `store-evaluations` | List, inspect, compare, start, and rerun search-quality evaluation runs |
| Tool | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query_catalog` | Query catalog listings for products, variants, or collections with filtering, sorting, field selection, and pagination. Returns compact rows plus resource URIs for deeper reads |
| Tool | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `search-semantic` | Run the full semantic storefront search pipeline with query understanding, typo tolerance, query expansion, and intent detection. Accepts an optional `debug` flag for scoring diagnostics |
| `browse` | Browse products within a collection using the storefront browse pipeline, including merchandising rules, sort orders, filtering, and facets |
| `search-autocomplete` | Get autocomplete suggestions for a search query |
| Tool | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `attributes-manage` | List attributes, fetch selectable values for a single attribute, create, update, delete, or manage drafts for document attributes. Actions include `list`, `values`, `create`, `update`, `delete`, `draft_update`, and `draft_clear`. Supports `keyword_search_weight` (1–10) to tune how strongly a searchable attribute contributes to keyword recall and ranking |
| `facet-values-manage` | List facet-eligible attributes, read a single facet's sorting, grouping, and hidden-value config, or publish the collaborative draft. Writes to the draft are handled through the [collaborative editor tools](#collaborative-editor) using RFC 6902 patches. Actions are `list` and `publish` |
| Tool | Description |
| --------------------------------- | ---------------------------------------------------------------- |
| `request-transforms-manage` | List, create, update, or delete request transforms |
| `semantic-redirects-manage` | List, create, update, or delete semantic redirects |
| `ranking-rules-manage` | List, create, update, delete, or toggle ranking rules |
| `query-expansion-examples-manage` | List, create, update, or delete curated query expansion examples |
| Tool | Description |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchandise-rules-manage` | List merchandising rules. Writes are handled through the [collaborative editor tools](#collaborative-editor) using RFC 6902 patches |
| `blocks-manage` | List, create, update, delete, publish, unpublish, duplicate, or bulk manage recommendation blocks with strategies, safeguards, and fallback chains. Supports `bulk_publish`, `bulk_unpublish`, `bulk_duplicate`, and `bulk_delete` |
| Tool | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `sort-orders-manage` | List sort orders. Writes are handled through the [collaborative editor tools](#collaborative-editor) using RFC 6902 patches |
| `sort-orders-preview` | Preview products sorted by a specific sort order, optionally within a collection |
| Tool | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `set_presence` | Announce an agent's activity on a merchandising rule, sort order, or facet values room, and read the current shared document and revision |
| `validate_document` | Validate the current document or proposed RFC 6902 patches without applying changes |
| `apply_patch` | Apply an atomic RFC 6902 JSON Patch to a shared document using a presence session and observed revision |
| Tool | Description |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `product-families` | List, inspect, create, update, publish/unpublish, or delete manual product families |
| `product-sequences` | List, inspect, create, update, publish/unpublish, or delete ordered product sequence groups |
| `variant-breakouts` | List, inspect, create, update, enable, disable, or delete option-based variant breakout rules |
| Tool | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `layersql-schema` | Describe and search the LayersQL schema: datasets, allowed metrics, dimensions, and product attributes |
| `layersql-validate-query` | Fast parser and semantic validation for a LayersQL query. Returns validation errors or the parsed structure |
| `layersql-query` | Run a read-only LayersQL query and return rows. Invalid queries fail validation and are never executed |
| Tool | Description |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledge-manage` | Search, list, get, propose, create, update, approve, or archive store knowledge documents. Knowledge documents are Markdown with YAML frontmatter and live in `pending`, `active`, or `archived` states. Search is powered by Cloudflare AI Search over the active set, and accepts an optional `scope` metadata filter |
| Tool | Description |
| ------------- | ------------------------------- |
| `docs-search` | Search the Layers documentation |
| Tool | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mcp-feedback` | Send feedback about the MCP itself — friction points, tooling gaps, bugs, or suggestions — directly to the Layers team. Available to admin MCP connections |
### Submitting feedback about MCP tooling
Admin MCP connections can call `mcp-feedback` to report friction with the MCP itself. Use it when an assistant hits a rough edge you want the platform to fix. Examples include a missing capability, a schema field that isn't exposed, an action that takes too many calls, or a tool description that led an agent astray.
The tool accepts a short set of fields:
| Field | Required | Description |
| ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `message` | Yes | Detailed description of the friction point, gap, or suggestion. Be specific about what you were trying to do and what went wrong or is missing |
| `category` | Yes | One of `friction`, `gap`, `bug`, or `other` |
| `tool` | No | Name of the MCP tool the feedback relates to, as it appears in the tool list (for example, `store-maintenance`) |
| `severity` | No | `low`, `medium`, or `high`. Defaults to `low` |
| `store` | No | Store slug or domain for context |
Example call:
```json theme={null}
{
"tool": "mcp-feedback",
"arguments": {
"message": "blocks-manage doesn't expose the fallback chain order, so I can't reorder fallbacks without recreating the block.",
"category": "gap",
"tool": "blocks-manage",
"severity": "medium",
"store": "my-store"
}
}
```
The response confirms the submission:
```json theme={null}
{
"sent": true,
"delivered": true
}
```
`delivered` is `false` when feedback routing isn't configured for the environment. The submission is still recorded.
### Usage pattern
Call `store-list` to see all stores you have access to. Note the store slug for each store you want to work with.
Include the store slug in all subsequent tool calls. For example, if your store is `my-store.myshopify.com`, the slug is `my-store`.
Tools ending in `-manage` accept an `action` parameter — commonly `list`, `create`, `update`, or `delete`, plus tool-specific actions such as `toggle_status` or the bulk variants below. Read-only actions like `list` are safe to call freely.
### Example: create a merchandising rule
Ask your AI assistant:
> "Pin the product 'Classic White Tee' to position 1 in the Summer Sale collection, and boost all products where brand is 'Nike' using a soft boost expression."
The assistant calls `merchandise-rules-manage` with `action: "create"` and the appropriate parameters — handling pin positions, collection targeting, and expression configuration automatically.
### Bulk actions
Several `-manage` tools accept bulk variants so an assistant can apply the same change to many records in one call:
* `blocks-manage` — `bulk_publish`, `bulk_unpublish`, `bulk_duplicate`, `bulk_delete` (pass `block_ids`)
* `merchandise-rules-manage` — `bulk_enable`, `bulk_disable`, `bulk_delete` (pass `rule_ids`)
Use bulk actions to act on many records at once — for example, unpublishing all draft blocks after a seasonal campaign, or disabling a batch of merchandising rules outside their window.
```json theme={null}
{
"store": "my-store",
"action": "bulk_unpublish",
"block_ids": ["blk_123", "blk_456", "blk_789"]
}
```
The response includes an `affected_count` so the assistant can confirm how many records changed.
### Collaborative editor
Assistants edit merchandising rules, sort orders, and facet values through a collaborative editing flow instead of direct writes. An assistant announces presence on a resource, reads the current shared document and its revision, then applies small RFC 6902 JSON Patch operations. This lets multiple humans and agents work on the same resource without overwriting each other. It also powers the same [real-time collaboration](/platform/real-time-collaboration) experience that shows other editors in the dashboard.
When an agent calls `set_presence` or `apply_patch`, humans on the same page see the agent live in the dashboard. The agent gets its own presence avatar with a distinct color, and its focused field or selected rows are tinted and locked like any other collaborator's. On the facet-values editor, a compact **agent activity** popover also surfaces the `intent` and `message` your agent supplies.
Provide a short, human-readable `activity.intent` and `activity.message` on `set_presence`, and a concise `metadata.intent` on `apply_patch`. This lets a human co-editor tell at a glance what your agent is doing.
Use the collaborative editor tools when your assistant needs to change:
* Merchandising rule fields, pins, or banners
* Sort order fields (referenced by id or handle)
* Facet value sorting, grouping, and hidden values (referenced by attribute id or code)
For read-only inspection or listing, keep using `merchandise-rules-manage`, `sort-orders-manage`, and `facet-values-manage` with `action: "list"`.
Direct write actions on `merchandise-rules-manage` and `sort-orders-manage` (`create`, `update`, `delete`, `bulk_*`, `toggle_status`, and so on) now return a compatibility error that points to the collaborative editor tools. Update your prompts and agents to use `set_presence` + `apply_patch` for writes.
#### Editing flow
Call `set_presence` with the store, `resource_type`, and `resource_id`. The first call for an agent run creates a new `presence_id`. The response includes the `presence_id`, current `document`, `revision`, `active_editors`, and an `expires_at` timestamp.
Build small RFC 6902 patches against the public roots `/fields`, `/pins`, and `/banners`. Prefer granular list operations like `add /pins/-`, `replace /pins/5`, `remove /pins/3`, and `move` over replacing the entire `/pins` or `/banners` collection. Call `validate_document` first when it would reduce risk — for example, before a large or unusual patch.
Call `apply_patch` with the same `presence_id`, the observed `revision`, and the RFC 6902 patch list. Patches are applied atomically: if any operation fails, no changes are committed and the revision is unchanged. On success, the response returns the new `revision` and `document`.
Presence expires at `expires_at` unless refreshed. Calling `set_presence` again with the same `presence_id` refreshes it, and successful `apply_patch` calls also refresh presence for that run. If a patch fails with a stale revision or a failed `test` operation, refresh presence to re-read the document and re-plan.
#### `set_presence`
Declares an agent's activity state and returns the shared document. Supported `activity_state` values are `viewing`, `editing`, `thinking`, and `validating`.
```json theme={null}
{
"tool": "set_presence",
"arguments": {
"store": "my-store",
"resource_type": "merchandising_rule",
"resource_id": "rule_123",
"activity_state": "viewing",
"activity": {
"intent": "inspect_rule",
"message": "Reviewing current pins and fields"
}
}
}
```
Example response:
```json theme={null}
{
"success": true,
"presence_id": "prs_01j_example",
"resource_type": "merchandising_rule",
"resource_id": "rule_123",
"activity_state": "viewing",
"active_editors": [],
"expires_at": "2026-07-07T16:21:44Z",
"revision": "sha256-document-revision",
"document": {
"fields": { "name": "Summer collection" },
"pins": [],
"banners": []
}
}
```
Pass a sort order handle or id as `resource_id` when `resource_type` is `sort_order`. Concurrent runs from the same OAuth client each receive their own `presence_id` so they can expire independently.
#### `validate_document`
Validates the current document or a proposed set of patches without applying changes. Whole-collection replacements return warnings so agents prefer granular list operations.
```json theme={null}
{
"tool": "validate_document",
"arguments": {
"store": "my-store",
"resource_type": "merchandising_rule",
"resource_id": "rule_123",
"revision": "sha256-document-revision",
"patches": [
{
"op": "add",
"path": "/pins/-",
"value": {
"id": "gid://shopify/Product/222",
"position": 2,
"pin_type": "product"
}
}
]
}
}
```
#### `apply_patch`
Applies an atomic RFC 6902 patch. Requires an active `presence_id` from `set_presence` and the latest observed `revision`. Supported operations are `add`, `remove`, `replace`, `move`, `copy`, and `test`. Patch paths must be under `/fields`, `/pins`, or `/banners`.
```json theme={null}
{
"tool": "apply_patch",
"arguments": {
"store": "my-store",
"presence_id": "prs_01j_example",
"revision": "sha256-document-revision",
"metadata": {
"intent": "move_pins",
"client": "mcp-agent"
},
"patches": [
{
"op": "add",
"path": "/pins/-",
"value": {
"id": "gid://shopify/Product/222",
"position": 2,
"pin_type": "product"
}
}
]
}
}
```
Use `test` before `replace` to catch concurrent edits:
```json theme={null}
{
"patches": [
{ "op": "test", "path": "/fields/name", "value": "Summer collection" },
{ "op": "replace", "path": "/fields/name", "value": "Summer collection hero merchandising" }
]
}
```
#### Error handling
`apply_patch` returns deterministic errors so agents can recover automatically:
| Status | Error | Recovery |
| ------ | ------------------ | -------------------------------------------------------------------------------------------- |
| 403 | `PermissionDenied` | Ask for an editor with the required store permission. |
| 404 | `ResourceNotFound` | Re-check the resource id or sort order handle. |
| 409 | `PresenceRequired` | Call `set_presence` to create or refresh a `presence_id`, then retry. |
| 409 | `RevisionConflict` | Refresh presence, re-read `document` + `revision`, and retry only if the edit still applies. |
| 409 | `TestFailed` | Another editor changed the tested value — re-read the document and re-plan. |
| 422 | `InvalidPatch` | Fix the RFC 6902 operation shape, or restrict paths to `/fields`, `/pins`, or `/banners`. |
#### `collaborative-merchandising-editor` prompt
The Layers MCP server exposes a `collaborative-merchandising-editor` prompt that describes the full safe-edit workflow. MCP clients that surface prompts (for example, Claude Desktop) can select it to prime an assistant with the correct presence-then-patch sequence before making changes.
#### Editing facet values
Facet value sorting, grouping, and hidden values live inside a filterable attribute's configuration. Assistants co-edit them through the same collaborative editor tools by passing `resource_type: "facet_values"` and the attribute id or code as `resource_id`. The shared document exposes two keys under `/fields`:
* `facet_value_group_sorts` — an ordered list of `{ facet_value, position, facet_value_group_filter }` entries. `position` controls the manual storefront order, and `facet_value_group_filter` is `{ name }` when the value belongs to a named group (all values sharing one `facet_value_group_filter.name` render as one group), or `null` when ungrouped.
* `hidden_values` — a list of facet value strings that are hidden on the storefront.
Rows in `facet_value_group_sorts` carry **no ids**. The server keys sorts by `facet_value` and groups by `name` (both distinct per attribute) and owns the underlying UUIDs. Never send an `id` on a sort entry or on `facet_value_group_filter` — it will be rejected.
Facet value sorting, grouping, and hidden values can only be written through this shared editor plus `facet-values-manage` `publish`. `attributes-manage` `create` and `update` reject `facet_value_group_sorts` and `hidden_values` with a 422 that points back to the shared editor — don't try to set them alongside other attribute fields.
Facets don't have `/pins` or `/banners`, so patches must target `/fields/facet_value_group_sorts` or `/fields/hidden_values`. The `attributes.view` permission is required to read a facet's document and `attributes.edit` is required to apply patches or publish.
Reorder a value:
```json theme={null}
{
"tool": "apply_patch",
"arguments": {
"store": "my-store",
"presence_id": "prs_01j_example",
"revision": "sha256-document-revision",
"patches": [
{ "op": "test", "path": "/fields/facet_value_group_sorts/0/facet_value", "value": "Red" },
{ "op": "replace", "path": "/fields/facet_value_group_sorts/0/position", "value": 3 }
]
}
}
```
Group two values under a shared display name by giving both entries the same `facet_value_group_filter.name`:
```json theme={null}
{
"patches": [
{ "op": "replace", "path": "/fields/facet_value_group_sorts/1/facet_value_group_filter", "value": { "name": "Warm tones" } },
{ "op": "replace", "path": "/fields/facet_value_group_sorts/2/facet_value_group_filter", "value": { "name": "Warm tones" } }
]
}
```
Hide a value from the storefront:
```json theme={null}
{
"patches": [
{ "op": "add", "path": "/fields/hidden_values/-", "value": "Discontinued" }
]
}
```
##### Publishing the draft
`apply_patch` only updates the shared draft. In the dashboard, a human presses **Save** to commit that draft. When an agent is running on its own with no human editing the room, call `facet-values-manage` with `action: "publish"` and the target `attribute` to commit the draft to the store.
* Publish is refused while a human is co-editing the room. In that case the response is `{ "published": false, "reason": "human_editing" }` — keep co-editing with `apply_patch` and let the human press Save, or retry publish after they leave.
* Publish is refused if you have not seeded or edited the draft in this session, to prevent an empty draft from wiping existing config.
* Successful publishes write to the store via the same code path as the dashboard Save action and appear in the [MCP audit log](#mcp-audit-log).
```json theme={null}
{
"tool": "facet-values-manage",
"arguments": {
"store": "my-store",
"action": "publish",
"attribute": "color"
}
}
```
#### `collaborative-facet-editor` prompt
The Layers MCP server also exposes a `collaborative-facet-editor` prompt covering the presence-patch-publish flow, `/fields` patch boundaries, and the human-in-the-loop rule for publishing. Select it before asking an assistant to reorder, group, or hide facet values.
### Working with grouped attributes
Some attributes are containers that hold other attributes rather than a single filterable value — for example, a "dimensions" attribute that wraps `length`, `width`, and `height`. MCP tools treat these differently:
* **Groups are listed but not selectable.** `attributes-manage` with `action: "list"` returns grouped attributes as read-only entries with their child attributes nested under `children`. Only the scalar children are marked `selectable`.
* **Search, browse, facets, and sort orders reject group codes.** Passing a group, object, or otherwise non-selectable attribute code to `filter_group`, `facets`, or a sort order returns a validation error. When the parent has scalar children, the error lists them so your assistant can retry with a valid code.
Use `attributes-manage` with `action: "list"` to discover which attributes are selectable before building filters or sort orders.
### Fetching attribute values
Call `attributes-manage` with `action: "values"` to enumerate the values available for a single scalar attribute. Use it before building `filter_group` conditions when your assistant needs to know what values a facet actually contains. For example, list every vendor or size before choosing one to filter on.
The response depends on the attribute's type:
* **Categorical attributes** return a cursor-paginated `values` array. Pass the returned `next_cursor` back in a follow-up call to fetch the next page.
* **Numeric attributes** return a `range` object with the minimum and maximum values in the catalog.
Both responses can be scoped to a collection with `collection_handle` so the values reflect only products in that collection.
```json theme={null}
{
"store": "my-store",
"action": "values",
"attribute_code": "vendor",
"collection_handle": "summer-sale",
"limit": 50
}
```
### Example: run an analytics query
Analytics is exposed through LayersQL. Ask your assistant to inspect the schema first, then run a query:
```json theme={null}
{
"store": "my-store",
"query": "FROM search_text SHOW COUNT(requests) WHERE num_results = 0 GROUP BY term SINCE -7d"
}
```
Call `layersql-schema` to discover available datasets, metrics, and dimensions, and `layersql-validate-query` to check a query before you run it.
### MCP audit log
Every write action your assistant performs through the Layers MCP server is recorded alongside dashboard configuration changes in the store's Activity Log. Each MCP entry captures the tool, action, user, store, and timestamp.
Review activity in the dashboard under `Configure → Access & Security → Activity Log`. MCP actions appear in the same feed as configuration edits, so you can see everything that changed in a store in one place.
Filter by event, action, or free-text search, and open any entry to inspect its details. The operational context attached to an MCP call is only visible to users with API key management permissions. Lower-privilege users still see that an MCP action happened, but not its raw context.
## Storefront MCP server
The Storefront MCP server exposes read-only storefront operations as MCP tools. It uses the same access token as the [Storefront REST API](/help/configuration/manage-api-access), so you can integrate AI assistants into customer-facing experiences.
### Connecting
Configure your MCP client with the storefront endpoint and your API token:
```
https://app.uselayers.com/mcp/storefront/v1
```
Authentication uses the same storefront access token you use for the REST API. Pass it as a bearer token in the authorization header.
### Available tools
| Tool | Description |
| ------------------------ | -------------------------------------------------------------------------- |
| `search-text` | Semantic text search with query understanding and typo tolerance |
| `browse` | Browse a collection with sort orders, merchandising, and faceted filtering |
| `search-similar` | Find visually and semantically similar products |
| `search-autocomplete` | Get predictive search query suggestions |
| `facets-get` | Retrieve available filter facets for a collection |
| `sort-orders-list` | List available sort orders |
| `blocks-recommendations` | Get product recommendations from a configured block |
| `search-content` | Search non-product content (pages, articles, blogs) |
### Common parameters
Most search and browse tools accept these optional parameters:
| Parameter | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filter_group` | Nested filter conditions (AND/OR with operators like `eq`, `in`, `gt`, `lt`, `between`, and the geo operators `geoRadius`, `geoPolygon`, `geoBoundingBox` — see [Geospatial filtering](/engine/geospatial-filtering)) |
| `facets` | Array of attribute codes to retrieve facet values for |
| `pagination` | `{ page, limit }` for paginated results |
| `sort_order_code` | Sort order to apply (use `sort-orders-list` to see available codes) |
| `attributes` | Array of attribute codes to include in the response |
| `context` | Contextual data for personalization (geo, customer, cart, marketing channel) |
| `identity` | Session, customer, and device identifiers for behavioral tracking |
| `debug` | When `true`, includes the full `_meta` payload (scores, tuning, ranking signals, timings) on the response and each result. Defaults to `false`. Supported on `search-text` and `browse`. |
By default, `search-text` and `browse` strip the `_meta` payload from responses to keep results compact. Pass `debug: true` when you need scoring diagnostics — for example, when debugging why a product ranked where it did.
`filter_group`, `facets`, and sort orders only accept scalar attribute codes. Group or container attribute codes are rejected with a validation error that lists the selectable child attributes when they're available.
### Example: text search with debug
```json theme={null}
{
"query": "running shoes",
"attributes": ["title", "handle", "featured_image", "price"],
"pagination": { "page": 1, "limit": 20 },
"debug": true
}
```
## When to use each server
* Use the **Layers MCP server** when you want an AI assistant to help manage your store — creating merchandising rules, tuning search behavior, building sort orders, or exploring analytics.
* Use the **Storefront MCP server** when you want to integrate AI-powered product discovery into a customer-facing experience. It's also useful when building AI agents that need to search and browse your catalog.
## Next steps
* [Manage API access](/help/configuration/manage-api-access) to create storefront tokens
* Learn about [request transforms](/platform/request-transforms) and [merchandising](/platform/merchandising) to understand what you can configure through MCP
* Explore the [API reference](/api-reference/search) for the underlying REST endpoints