Troubleshooting

• Did you finish authentication?OAuth clients need a completed browser consent flow before they can load the ShopMCP tool list. Reopen the client's MCP settings and check its authentication state.
• Does the client need a refresh? Start a new chat, reload MCP, or restart the client after adding the server. The exact action differs by client.
• Is the transport correct? ShopMCP uses Streamable HTTP at https://my.shop-mcp.app/api/mcp. Do not configure it as a local stdio process or the deprecated SSE transport.
• Is the client config valid? For JSON- or YAML-based clients, check syntax and use the exact structure in the relevant client setup guide.

• OAuth client: the URL should be exactly https://my.shop-mcp.app/api/mcp with no query string. Disconnect or log out, reconnect, and verify the workspace on the ShopMCP consent screen.
• Static-key client: copy the full scoped URL from Settings → Connections. It must include /api/mcp?token=smcp_...; revoke and recreate it if the key was lost or exposed.
• Hermes reports unsupported 2025-11-25: see the Hermes guide. That is a valid MCP revision; the error identifies an older ShopMCP compatibility list combined with Hermes' initialization-header bug.

• 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. Static URLs are workspace-scoped. OAuth clients bind to the workspace displayed on the consent screen; disconnect and reconnect to choose a different one.

• Pending (no trial or paid plan yet): tool calls are blocked before they even reach the rate limiter. The error message includes tenant_action: upgrade. Start a 14-day free trial or pick a plan in Settings → Billing.
• Paid plans: 300 rpm is available per workspace. Portfolio pools to 600 rpm account-wide, and Agency pools to 1,200 rpm account-wide. 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.

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

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.