ShopMCP docs

Reference

Troubleshooting

Most issues fall into one of five buckets. Find yours below — if none of them help, email support and we'll dig into the trace.

My chat client doesn't see ShopMCP

  • Did you restart the client? Claude Desktop, Cursor, and ChatGPT cache the MCP server list — a full restart (not just closing the window) is required after adding the config.
  • JSON syntax error? Open the config file in VS Code; the red squiggle tells you which line. The most common mistake is a trailing comma after the last key.
  • Wrong file path? Each client looks at a specific path — check the client setup pages for the exact location on your OS.

Authentication failed

  • The bearer token is wrong, expired, or revoked. Generate a new key in Settings → API keys and update your client config.
  • You added an extra space or quote when pasting. The header should look exactly like Bearer smcp_xxxxxxxx — no quotes, single space after Bearer.
  • You're hitting a stale local DNS cache. nslookup mcp.shop-mcp.app should resolve cleanly.

Tools list is empty

  • No modules connected for this workspace yet. Open Settings → Integrations and connect at least one.
  • All your subscriptions are paused or cancelled — check Settings → Billing.
  • You're on the wrong workspace. The bearer token is workspace-scoped; if you have several workspaces, make sure you generated the key from the right one.

Rate limited

  • Free tier: 100 calls/day workspace-wide, 10 rpm. The error message includes tenant_action: upgrade. Upgrade in Settings → Billing.
  • Pro/Team: 60 rpm burst is per workspace. If you're calling fast in a loop, slow down or batch with playbooks.
  • Upstream rate limit: Shopify, GA4, and Neto have their own per-account limits. We pass them through with retryable: true so the assistant knows to retry.

Tool returns weird data or no data

  • Date range too wide: GA4 and GSC throttle very large windows. Try narrowing to 28 days.
  • Empty Shopify result: the assistant may have filtered too aggressively. Re-ask with explicit dates.
  • "Not found" on a known SKU: the SKU exists in a different store than the one tied to this connection. Disambiguate by passing the store domain.

Still stuck?

Email support@shop-mcp.app with:

  • Your workspace name
  • The exact error message (and the tool name if there is one)
  • The chat client you're using
  • Roughly when it happened (so we can find the trace)

We respond inside one business day, usually faster.