MCP servers - Layers

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

The official Layers connector is available in the Claude directory. Add it from Settings > Connectors in Claude, then authorize Layers when prompted. If you are using a different MCP client, configure it 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, recent tasks, a `search_documents` rollup with `ready`, `pending`, and `needs_attention` counts across the catalog, and a `facets` rollup with each facet’s build phase, last refresh time, and any facets currently withheld from the API with the reason
`store-maintenance`	Inspect maintenance status. Admin operators can also run maintenance actions such as feature-flag updates, cache purges, and search-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

Diagnostics

Tool	Description
`product-search-diagnostics`	Inspect what content reaches a product’s search document, what was excluded and why, and the current indexing readiness state. Resolves a product by numeric id, Shopify gid, or handle. Also accepts an optional `collection` and `facet_codes` to explain which requested facets the API serves and which it drops. Use it when search isn’t finding a product or when verifying content-selection behavior

Tool	Description
`search-semantic`	Run the full semantic storefront search pipeline with query understanding, typo tolerance, query expansion, and intent detection. Accepts an optional `filter_group` (same shape as the browse API), `facets`, and a `debug` flag for scoring diagnostics. Empty results with a filter applied may mean the product wasn’t recalled or was filtered out - follow up with `product-search-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, and a `classes` array (`categorical`, `feature`, `price`) that gates query-understanding filters, intent modifiers, and affinity signals
`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
`request_publish`	Request human approval to publish the current shared document for a merchandising rule. Returns a `publish_request_id` and a dashboard review URL
`check_publish_request`	Check whether a pending publish request has been approved, rejected, superseded, or expired

Products

Tool	Description
`product-families`	List, inspect, create, update, publish/unpublish, or delete manual product families. Use `get_config` and `update_config` to read or change which attribute codes and metafield namespace/key pairs generate automatic families. Write actions on non-manual families return 403 and name the actual source (for example, `Attribute-sourced families are read-only`)
`product-sequences`	List, inspect, create, update, publish/unpublish, delete, configure, or re-evaluate ordered product sequence groups. Use `get_config` and `update_config` to read or change sequence metafields, global sequence conditions, and AI ordering settings; call `reevaluate` to re-run condition evaluation across every sequence. Payloads include `source`, `is_published`, `is_active`, and `inactive_reason`; write actions on non-manual sequences return 403 and name the actual source
`variant-breakouts`	List, inspect, create, update, enable, disable, or delete option-based variant breakout rules. Accepts an optional `exclusion_conditions` group (flat `variants.` or `variant_metafields.` rules with `and`/`or`) to keep matching variants from breaking out

Analytics (LayersQL)

Tool	Description
`layersql-schema`	Describe and search the LayersQL schema: datasets, allowed metrics, dimensions, and product attributes. Called without `dataset`, it also returns a compact syntax cheat-sheet (clause order, operators, two examples). Pass `include_reference: true` to include the full LayersQL syntax reference and example queries
`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" }
  ]
}

Explaining edits with `metadata.notes`

metadata accepts an optional notes object that maps an exact patch path in the same call to a one-line reason for the change. Notes appear in the dashboard’s agent activity feed as the caption for that step, so a human co-editor can see why the agent made each change.

{
  "tool": "apply_patch",
  "arguments": {
    "store": "my-store",
    "presence_id": "prs_01j_example",
    "revision": "sha256-document-revision",
    "metadata": {
      "intent": "reorder_pins",
      "notes": {
        "/pins/0/position": "featured jacket leads the launch collection",
        "/fields/facet_value_group_sorts": "in-stock colors first"
      }
    },
    "patches": [
      { "op": "replace", "path": "/pins/0/position", "value": 1 }
    ]
  }
}

Rules for notes:

Each key must match a path present in the same patches list. Notes for unknown paths are dropped.
Values must be non-empty strings. Non-strings and empties are dropped.
Notes are trimmed and capped at 240 characters.
Write a short reason (why this helps the shopper), not a restatement of the operation.

Agents that omit notes behave exactly as before.

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`.

Requesting publish approval

apply_patch only updates the shared draft. To publish a merchandising rule, an agent asks a human reviewer to approve the change. The reviewer approves or rejects the request from the dashboard, and Layers records the agent’s identity in the config audit log when it publishes. Use request_publish when the user asks you to save or publish, then poll check_publish_request until the request settles. Do not call apply_patch again on the same rule while a request is pending unless the reviewer rejects it or the user explicitly asks for more edits. Publish requests are supported for resource_type: "merchandising_rule". Facet values and sort orders publish through their own flows (see Editing facet values).

Request approval

Call request_publish with the same presence_id and the latest observed revision. Include an optional message describing what changed so the reviewer has context. The response includes a publish_request_id, a same-origin review_url, and an expires_at timestamp.

Share the review URL and wait

Send the review_url to the user so they (or another grant owner) can open the review modal in the dashboard. While a request is pending, the shared draft is protected from reconciliation, so unrelated dashboard events will not overwrite it.

Poll for the outcome

Call check_publish_request with the publish_request_id until settled is true. The final status is published, rejected, superseded, or expired. Publish requests expire after 72 hours.

Handle the result

On published, the changes are live and config_version_id points at the resulting config version. On rejected or expired, you can edit the rule again and call request_publish again. On superseded, a newer request has replaced this one - switch to the newer publish_request_id.

`request_publish`

Creates a pending publish request for the shared document the agent is currently editing. Requires an active presence_id from set_presence and the revision you last observed. The revision must still match the current room revision, or the tool returns a RevisionMismatch error - refresh presence and try again.

{
  "tool": "request_publish",
  "arguments": {
    "store": "my-store",
    "presence_id": "prs_01j_example",
    "revision": "sha256-document-revision",
    "message": "Pin the featured jacket to position 1 for the launch"
  }
}

Example response:

{
  "success": true,
  "publish_request_id": "pubreq_01j_example",
  "status": "pending",
  "review_url": "https://app.uselayers.com/stores/my-store/merchandise/rule_123?publish_request=pubreq_01j_example",
  "expires_at": "2026-08-17T12:00:00Z",
  "next": "The publish request is pending human review. Poll check_publish_request with the publish_request_id until it is settled."
}

Requesting publish while another request is still pending for the same rule marks the older request as superseded and returns the new publish_request_id.

`check_publish_request`

Returns the current state of a publish request. Safe to call as often as needed.

{
  "tool": "check_publish_request",
  "arguments": {
    "store": "my-store",
    "publish_request_id": "pubreq_01j_example"
  }
}

Example response after approval:

{
  "success": true,
  "settled": true,
  "status": "published",
  "publish_request_id": "pubreq_01j_example",
  "review_url": "https://app.uselayers.com/stores/my-store/merchandise/rule_123?publish_request=pubreq_01j_example",
  "resolved_by": "Jamie Reviewer",
  "resolution_note": null,
  "config_version_id": "cfgv_01j_example",
  "resolved_at": "2026-08-14T15:04:00Z",
  "expires_at": "2026-08-17T12:00:00Z",
  "next": "The publish request was approved and published. The changes are now live."
}

status values:

Status	Meaning
`pending`	Waiting on a reviewer. Keep polling.
`published`	The reviewer approved the request and Layers saved the rule. `config_version_id` identifies the new version.
`rejected`	The reviewer declined the request. `resolution_note` may explain why. You can edit again and request a new publish.
`superseded`	A newer `request_publish` call replaced this request. Use the newer `publish_request_id`.
`expired`	72 hours passed without a decision. You can edit again and request a new publish.

`collaborative-merchandising-editor` prompt

The Layers MCP server exposes a collaborative-merchandising-editor prompt that describes the full safe-edit workflow, including the request_publish handshake. MCP clients that surface prompts (for example, Claude Desktop) can select it to prime an assistant with the correct presence-then-patch-then-request 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
}

Classifying attributes for query understanding

attributes-manage create and update accept a data.classes array that controls how the query-understanding pipeline uses an attribute. Set it separately from is_searchable, keyword_search_weight, and enable_as_storefront_facet - each switch controls a different behavior.

Class	What it enables
`categorical`	Filters and sorts on exact values (color, size, brand). Required for the attribute to appear in intent detection.
`feature`	Keyword-style modifiers and context priors from descriptive terms (waterproof, slim fit, wireless).
`price`	Price-aware filtering and ranking. Use for price or price-derived signals.

Pass one or more classes; values are lowercased and deduped server-side. To leave the existing classes unchanged on update, omit the classes key. Passing null or any non-array value returns a validation error rather than clearing the field.

{
  "tool": "attributes-manage",
  "arguments": {
    "store": "my-store",
    "action": "update",
    "attribute_code": "color",
    "data": { "classes": ["categorical"] }
  }
}

Toggling is_searchable triggers a catalog reindex, so batch those changes. The attribute-setup prompt walks an assistant through the full workflow - discovering the attribute, sampling values with query_catalog, picking classes, and verifying with product-search-diagnostics. Select it from an MCP client that surfaces prompts (for example, Claude Desktop) before asking an agent to classify attributes.

Diagnosing search coverage

Use product-search-diagnostics when a product is missing from search-semantic results, to verify what content reached its search document, or to confirm an attribute change flowed through. Resolve a product by numeric id, Shopify gid (gid://shopify/Product/...), or handle. Pass include_variant_documents: true on per-variant-indexed products to include the rendered document text for each variant. The response has three sections:

Field	Contents
`document`	The rendered search text plus a structured `toFilteredArray()` view, and per-variant documents when requested
`content`	Per-content-type `included` and `excluded` lists for collections, tags, metafields, variant options, and variant metafields. Exclusions carry a `reason`: `ai_excluded`, `repeatedly_excluded`, `not_descriptive`, or `not_breakout_dimension` (returned for `variant_options` when a variant breakout resolved the split dimension; the option may still reach each variant’s document through `variant_content`)
`indexing`	Readiness status (`ready` or `rebuild_pending`), `indexed_as` (`product` or `per_variant`), `indexed_as_source` (`breakout` when a variant breakout forced per-variant grouping, otherwise `model`), and document and image counts

{
  "tool": "product-search-diagnostics",
  "arguments": {
    "store": "my-store",
    "product": "classic-white-tee",
    "include_variant_documents": false
  }
}

On dev stores that skip LLM content selection, the payload’s content_selection field is "skipped" - the store indexes the full unfiltered catalog instead. product-search-diagnostics also explains facet availability. Pass facet_codes (and optionally a collection handle) to check why a facet you requested from the Facets API is missing from the response:

{
  "tool": "product-search-diagnostics",
  "arguments": {
    "store": "my-store",
    "collection": "shirts",
    "facet_codes": ["color", "brand"]
  }
}

The response’s facet_diagnostics section lists the requested codes, which were included, and which were dropped with a reason: attribute_not_found, not_enabled_as_facet, attribute_not_filterable, facet_still_building, or facet_build_failed. These are the same readiness checks the Facets API applies when serving requests, so a dropped code here explains a missing facet in storefront responses. See When a facet goes live for how facet builds work. For a store-wide rollup, call store-operational-status and read search_documents. It returns aggregate ready, pending, and needs_attention counts across the catalog. The same response includes a facets section with each facet’s build phase and last refresh time under states, plus a withheld list naming any enabled facets the API is currently holding back and why.

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. Omit dataset to get a compact syntax cheat-sheet with clause order, operators, and two example queries. Pass include_reference: true for the full syntax reference. Call 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

​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

Explaining edits with metadata.notes

​Error handling

​Requesting publish approval

request_publish

check_publish_request

​collaborative-merchandising-editor prompt

​Editing facet values

Publishing the draft

​collaborative-facet-editor prompt

​Working with grouped attributes

​Fetching attribute values

​Classifying attributes for query understanding

​Diagnosing search coverage

​Diagnosing missing facets

​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`

Explaining edits with `metadata.notes`

Error handling

Requesting publish approval

`request_publish`

`check_publish_request`

`collaborative-merchandising-editor` prompt

Editing facet values

`collaborative-facet-editor` prompt

Working with grouped attributes

Fetching attribute values

Classifying attributes for query understanding

Diagnosing search coverage

Diagnosing missing facets

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