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, get_master_related_v1, …) plus the 16 operations tools: markets, definitions, translations, sales channels, drops, and the data-health loop. "Run a completeness scan and show me the worst products" is a read-plus-scan workflow an operator can run end to end.

Step 3 — the draft-then-publish workflow

Writes on the connector are drafts by design. 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. Pass the current draft revision so a concurrent edit fails with 409 instead of being silently overwritten (omit it and the write is last-write-wins).
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 pushes the item live through the server-side orchestration (variant cascade, media sync, collection-membership sync). 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 — handle publish partial failure

A multi-store publish can half-succeed, and the connector reports it honestly:

• A completed orchestration can report ok: false with per-store errors[] and per-variant variant_results[], prefixed with a [partial failure] note. Already-published stores are live; failed ones are not.
• The publish timeout is 120 s. On timeout, the server-side publish may still complete — re-read the item and check its publish state before retrying.

Build the operator to relay this verbatim: name the stores that failed, and never report a partial failure as success. The publish-monitoring fields are the cross-check.

The safety rails you get for free

• No delete, ever. There is no delete tool and no delete permission at all — pim:delete is not grantable by consent or by key minting.
• 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. Shopify changes happen solely through publish_master_v1 on the publish tier.
• 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, tool text truncates at 20,000 characters with a marker, and results are minimized projections — internal bookkeeping is never returned.

Go deeper