Shop MCP

Connect a module

BigCommerce

ShopMCP talks to your BigCommerce store via a store-level API token that you mint and scope yourself in the store admin. The token's OAuth scopes are the primary security gate — ShopMCP cannot touch anything you don't explicitly grant.

Read this before connecting a production store. An LLM reading a malicious support email or product review could be tricked into taking destructive actions on your store if given broad write scopes. ShopMCP mitigates this with allowlist-only tools, field-level input whitelists, read-only defaults, and by leaning on BigCommerce's OAuth scope system as the final gate — but scopes are only as narrow as you make them. Start read-only and audit /settings/connections and the usage log regularly.

1. Create a Store-level API account

In BigCommerce admin, go to Settings → API → Store-level API accounts → Create API account. Give it a descriptive name like ShopMCP, and leave the Type as V2/V3 API token (the default). We do not recommend the Universal token — its scope is broader than necessary for this integration.

2. Set the OAuth scopes (this is the security gate)

The scope picker is the only thing standing between ShopMCP and your entire store. Take a minute to scope it properly. Below is the recommended read-only scope set that activates every v1 BigCommerce tool ShopMCP ships:

  • Information & Settings — read-only (required for verification and for bigcommerce_get_store_info)
  • Products — read-only
  • Orders — read-only
  • Customers — read-only
  • Carts — read-only
  • Checkouts — read-only
  • Marketing — read-only (promotions, coupons, gift certificates)
  • Content — read-only (pages, scripts, redirects, blog posts)
  • Channel settings — read-only (channels, sites)
  • Themes — read-only (optional; only if you want theme-related tools later)

Do not tick any "modify" scopes for a read-only deployment. Writes are off by default in v1 — granting modify scopes widens your blast radius without unlocking a single feature until writes are turned on for your workspace.

3. Save and grab the token

Click Save. BigCommerce displays the token and a download link once — copy both of the following immediately:

  • Access Token — the long alphanumeric string. This is secret.
  • Store Hash — visible in the API path URL shown on the same screen, e.g. https://api.bigcommerce.com/stores/abc123def/v3/. The bold part is your store hash.

If you close the dialog without copying, you'll need to delete the API account and create a new one — BigCommerce does not expose the token again.

4. Paste the details into ShopMCP

Open Settings → Integrations → BigCommerce and fill in:

  • Store hash — e.g. abc123def.
  • Access token — the token from step 3.
  • Client ID — leave blank. Only required if you've installed a private BigCommerce App that issued you an OAuth app token (different flow).
  • Label — optional friendly name shown in the multi-store picker.

On submit, ShopMCP calls GET /stores/{hash}/v2/store to confirm the token is valid and has at least minimal read scope. A successful verification persists the credentials encrypted-at-rest (KMS envelope) and flips the BigCommerce module to Connected for every API key in the workspace.

Write tools are off by default

ShopMCP's BigCommerce package includes a full set of write tools — product / category / brand CRUD, order create and update, customer CRUD, cart operations, inventory adjustments, price list mutations, promotion and coupon CRUD, page CRUD, webhook management. These are compiled in but never registered in v1. The runtime calls registerBigCommerceTools({ allowWrites: false }) regardless of plan tier.

When writes are turned on for your workspace (later), you'll also need to widen the token's OAuth scopes to grant matching modify scopes. Start with only the scopes you actually need and expand incrementally.

Rotation and revocation

  • Rotate every ~90 days. Create a new API account in BigCommerce with the same scopes, reconnect in ShopMCP with the new token, then delete the old API account. The connections row is rebuilt in place — no data loss.
  • Revoke instantly. Delete the API account in BigCommerce admin. ShopMCP's next tool call will receive HTTP 401 and surface "BigCommerce rejected the token" to the user.
  • Disconnect from ShopMCP. Click Disconnect on the BigCommerce connect page. This removes the connections row and disables the workspace_modules toggle but does not touch the BigCommerce-side API account — delete it there as well if you want a full revoke.

Troubleshooting

  • "BigCommerce rejected the token" (401) — either the token was deleted / rotated, or the store hash doesn't match the token's store. Double-check both.
  • "Token accepted but it lacks the minimum scope" (403) — the API account is missing Information & Settings read. Update scopes in BigCommerce admin and retry — no reconnect needed.
  • "BigCommerce returned 404 for the store hash" — the hash is typo'd. It's the short alphanumeric in the API path URL on your store's API account screen, not the store domain.
  • "BigCommerce is rate-limiting" (429) — rate limits are per-store, not per-token. ShopMCP reads X-Rate-Limit-Time-Reset-Ms on 429 responses and retries once after waiting. Persistent 429s suggest your store is genuinely at its quota.