MCP servers

Layers exposes two Model Context Protocol (MCP) 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.

Store

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

Catalog

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

Attributes

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 using RFC 6902 patches. Actions are `list` and `publish`

Search tuning

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

Merchandising

Tool	Description
`merchandise-rules-manage`	List merchandising rules. Writes are handled through the collaborative editor tools 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`

Sort orders

Tool	Description
`sort-orders-manage`	List sort orders. Writes are handled through the collaborative editor tools using RFC 6902 patches
`sort-orders-preview`	Preview products sorted by a specific sort order, optionally within a collection

Collaborative editor

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

Products

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

Analytics (LayersQL)

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

Knowledge

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

Documentation

Tool	Description
`docs-search`	Search the Layers documentation

Feedback

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:

{
  "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:

{
  "sent": true,
  "delivered": true
}

delivered is false when feedback routing isn’t configured for the environment. The submission is still recorded.

Usage pattern

List your stores

Call store-list to see all stores you have access to. Note the store slug for each store you want to work with.

Pass the store slug

Include the store slug in all subsequent tool calls. For example, if your store is my-store.myshopify.com, the slug is my-store.

Use manage tools to make changes

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.

{
  "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 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

Announce presence and read the document

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.

Plan and (optionally) validate patches

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.

Apply the 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.

Refresh presence and retry on conflict

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.

{
  "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:

{
  "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.

{
  "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.

{
  "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:

{
  "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. 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:

{
  "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:

{
  "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:

{
  "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.

{
  "tool": "facet-values-manage",
  "arguments": {
    "store": "my-store",
    "action": "publish",
    "attribute": "color"
  }
}

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.

{
  "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:

{
  "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, 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)
`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

{
  "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 to create storefront tokens
Learn about request transforms and merchandising to understand what you can configure through MCP
Explore the API reference for the underlying REST endpoints

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Layers MCP server

Connecting

Available tools

Submitting feedback about MCP tooling

Usage pattern

Example: create a merchandising rule

Bulk actions

Collaborative editor

Editing flow

`set_presence`

`validate_document`

`apply_patch`

Error handling

`collaborative-merchandising-editor` prompt

Editing facet values

Publishing the draft

`collaborative-facet-editor` prompt

Working with grouped attributes

Fetching attribute values

Example: run an analytics query

MCP audit log

Storefront MCP server

Connecting

Available tools

Common parameters

Example: text search with debug

When to use each server

Next steps

​Layers MCP server

​Connecting

​Available tools

​Submitting feedback about MCP tooling

​Usage pattern

​Example: create a merchandising rule

​Bulk actions

​Collaborative editor

​Editing flow

​set_presence

​validate_document

​apply_patch

​Error handling

​collaborative-merchandising-editor prompt

​Editing facet values

Publishing the draft

​collaborative-facet-editor prompt

​Working with grouped attributes

​Fetching attribute values

​Example: run an analytics query

​MCP audit log

​Storefront MCP server

​Connecting

​Available tools

​Common parameters

​Example: text search with debug

​When to use each server

​Next steps

Layers MCP server

Connecting

Available tools

Submitting feedback about MCP tooling

Usage pattern

Example: create a merchandising rule

Bulk actions

Collaborative editor

Editing flow

`set_presence`

`validate_document`

`apply_patch`

Error handling

`collaborative-merchandising-editor` prompt

Editing facet values

`collaborative-facet-editor` prompt

Working with grouped attributes

Fetching attribute values

Example: run an analytics query

MCP audit log

Storefront MCP server

Connecting

Available tools

Common parameters

Example: text search with debug

When to use each server

Next steps