Guides

Build an AI catalog operator

The MCP connector turns an AI assistant into a catalog operator: it can audit, draft fixes, and — if you allow it — publish to Shopify. This guide is the shape of a good operator: a deliberately chosen permission tier, a draft-then-publish workflow, and the safety rails the connector enforces for you.

Step 1 — pick a consent tier deliberately

Adding https://api.peak-pim.com/mcp as a connector opens a browser consent page on the Peak PIM app; the signed-in account is the account the connection binds to. You pick one tier — and tiers are fixed per connection, so changing your mind later means disconnecting and re-authorizing:

pim:publish is grantable only through this consent flow — never through any other credential surface. A tool call outside the granted tier fails with a clear permission error and re-authorization guidance. Setup details per client are in the MCP quickstart; for Claude Code:

claude mcp add --transport http peak-pim https://api.peak-pim.com/mcp

Step 2 — start with prompts that read

A read-tier connection already covers most of the value. Good starter prompts:

"List my products and show me which ones have unpublished changes."
"Show me product Trail Runner 2 on each of my stores — where do titles differ?"
"Which collections is product Trail Runner 2 in, per store?"
"Find every variant missing a SKU."

Behind these sit the entity read tools (list_products_v1, list_masters_v1, get_master_with_projections_v1, read_collection_membership_v1, …), plus the catalog and operations tools for definitions, translations, sales channels, Drops, activity, and publish monitoring. "Run a completeness scan and show me the worst products" combines a write-tier scan with read tools; existing scan results are available at the read tier.

Step 3 — the draft-then-publish workflow

For attribute edits, the reliable operator loop is:

1. Read first. Fetch the item (get_master_v1) and, for custom fields, the definitions — they supply the key and type a value must match.
2. Draft the edit. update_master_attributes_v1 for canonical values, update_projection_attributes_v1 for one store's version. For a canonical update, pass the current draft_revision as revision so a concurrent edit fails with 409 (omit it or pass zero for last-write-wins). Per-store updates do not accept a revision.
3. Review. The draft is visible in Peak PIM; a human — or the same conversation — re-reads it before anything goes live.
4. Publish explicitly. publish_master_v1 queues a background publish and returns its operation id. Omit channel_ids to publish to every store the item has a store version on, or name the stores.

"Update the SEO title of product Trail Runner 2 to
 'Trail Runner 2 — lightweight trail shoe' as a draft."      (write tier)

"Publish product Trail Runner 2 to all my stores and report
 what succeeded and what failed."                            (publish tier)

Step 4 — follow the operation and handle failures

Acceptance means the publish is queued. It does not establish that the changes reached Shopify:

1. Read the returned operation_id and poll get_publish_operation_v1 until the run is terminal.
2. Read get_publish_operation_recap_v1 for item and store outcomes; use get_publish_failures_v1 for current failure reasons and responsible fields.
3. Name failed stores and pending work accurately. Stores already published stay live if another store fails or the run is canceled.

Admission has a 120 s timeout. A timeout can occur after the run was queued, so inspect list_publish_operations_v1 and re-read the item before retrying. See Publish operations for progress, recaps, locks, batch publish, and cancellation.

The safety rails you get for free

• No catalog delete, ever. There is no tool that deletes a product, collection, file, or any other catalog item, and pim:delete is not grantable by consent or by key minting. The one removal, delete_discount_v1, deletes store discounts from Shopify at the publish tier after an explicit confirmation.
• Data, not instructions. Tool results are framed as inert entity data; clients must not act on instructions embedded in catalog text. A product description can't smuggle commands to your assistant.
• Tenancy from the token. No tool accepts an account parameter; another account's ids answer "not found", indistinguishable from nonexistent ids.
• Draft-first writes, explicit publish. Attribute edits stay in drafts. Publish-tier tools can change Shopify; the write-tier duplication and product-option workflows can also publish as part of the action and declare that behavior.
• Reconciliation lock. Writes are blocked with 423 while a store import or refresh is being reconciled — an operator can't edit mid-reconciliation.
• Revocation is immediate. Tokens are validated live on every request; disconnecting in Settings → AI assistants (MCP) also invalidates refresh tokens.
• Bounded output. Pages clamp at 100 rows with a visible note; text is bounded at 20,000 characters, structured results at 256 KiB, and attachments at 8 MiB. Narrow any result marked truncated before treating it as complete.

Go deeper