Troubleshooting & FAQ

Connection issues

401 Unauthorized The API key is invalid or no longer matches the stored hash. Generate or regenerate the connection key on the dashboard and update your MCP client config. The key is shown only once.

MCP client can't find the server The MCP server address is https://mcp.shopigent.greeknous.com/mcp. Send the connection key as a Bearer token. Do not use https://app.shopigent.greeknous.com/mcp. Cursor and Claude Desktop need a full restart after a config change.

Missing or failing tools

A tool doesn't appear in the tools list The tool's enable switch is off on Curated Tools, the tool is retired (list_themes and the other direct theme tools are rejected and are not listed), or a custom tool is not active. A Theme Pull Request tool can still be listed when no repository is connected. A new GitHub App connection cannot be started on the Theme Pull Requests page. A shop that already has a stored installation can choose a repository that installation can access. Otherwise use the personal access token form. If the GitHub App is not configured, the page says so and the token form remains. Turning an area off on Scopes & Permissions stops the tool from running. It does not, by itself, remove an enabled tool from the list.

Upgrade required The live call is not included in the current plan. The response is an error with upgradeRequired: true. On Free, a curated write can still be previewed with dryRun: true, and that preview is not executed. Custom tools, including their preview, require Pro. get_translations, set_translations, and delete_translations require Pro. See Plans & Billing.

Daily cap or "Rate limit exceeded" Free allows 25 tool calls per day and Growth allows 500. Pro has no daily cap. Every plan, including Pro, also stops at 60 calls per minute. A daily-cap error asks you to upgrade. A per-minute error says "Rate limit exceeded" and includes a retry delay.

Confirmation gate

"Action pending confirmation" — nothing happens The action is waiting for approval in your AI client, or on the Confirmations page in the Shopigent admin. Approving in the AI client re-calls the tool with the signed token and exactly the same arguments. Approving on the Confirmations page asks the MCP server to run that same check. Declining there uses the token and does not run the tool. The page does not show the token. A product media upload cannot be approved on that page because the file payload is not stored.

Can I turn off confirmations? Yes — per tool, except four actions that always confirm: publishing a product to a sales channel, changing a variant's shipping weight, uploading product media, and creating a theme pull request. Destructive tools arrive with confirmation on, and you can turn that off for the others. Use dryRun: true for a preview. The preview is not executed. On the Free plan a write preview is allowed and the write itself is not.

Theme Pull Requests

Why did my PR not change the Shopify storefront? Shopigent stops after creating the pull request. Review and merge it on GitHub. Shopify's native GitHub theme integration then synchronizes the connected branch to the theme you selected. For testing, connect an unpublished theme so the live storefront stays unchanged. Publishing is always a merchant action.

Can Shopigent edit or publish a Shopify theme directly? No. It does not request direct Shopify theme scopes and does not use the Admin Theme API. Theme repository changes are PR-only.

General

Does Shopigent work with any MCP client? Yes — anything that speaks Model Context Protocol: Claude, Cursor, Hermes, custom agents.

Can agents see data in disabled categories? No. Turning an area off stops tools in that area from running, so the call does not return that area's store data. An enabled tool can still be listed.

Where do I see what my agent did? The Audit Log shows each call's tool, read or write, status, time, latency, and client. View stored details shows a redacted copy of the stored input and response summary. The view redacts secret- and token-like fields, names, addresses, and email- or phone-shaped values. Opening it does not change the database row. The dashboard Recent activity card counts successful writes, dry-runs, confirmations waiting, and confirmations declined for the last 24 hours and the last 7 days. Curated Tools shows each tool's stored call count, last status, and last dry-run time.

How do I completely revoke an agent's access? Choose Regenerate connection key on the dashboard, or uninstall the app. Regenerating replaces the stored hash, so the previous key is rejected. Uninstall clears the key immediately, so the old token returns 401. Generating a new key after you reinstall replaces it. Uninstall does not delete the shop row; shop/redact does that about 48 hours later.

Missing scope

MISSING_SCOPE error — what does it mean? Shopify refused the operation because the app's current OAuth token is missing a required permission. This is different from a disabled Shopigent category (which controls tool visibility) — the Shopify installation itself does not include the scope.

How do I read the error? The error response includes a details object with:

missingScopes[] — exact Shopify handles the store still lacks (e.g. ["read_files", "write_files"]). This list is authoritative only when scopeSource is "shopify_error" or "live_grant".
scopeDisclosed — true when Shopify named the required scope, false when it only said "access denied" without a handle.
When scopeDisclosed is false and known prerequisites are available, knownPrerequisites[] lists what the tool needs — check those against your OAuth grant.
deniedField — the Shopify GraphQL field that triggered the denial (e.g. stagedUploadsCreate).

What if requiredScope is null? Shopify refused the operation without naming the specific scope. Open Scopes & Permissions in the embedded app, find the category the tool belongs to, and grant its scopes. The app shows exact missing handles in the banner when they can be determined.

How do I reauthorize?

Open the Scopes & Permissions page in Shopigent's embedded app.
Read the missing scopes listed in the warning banner (e.g. read_files, write_files).
Click Grant missing permissions — this opens the Shopify OAuth install screen with all scopes the app needs.
Approve the permissions. Shopify redirects back to the app.
The app verifies the new live grant. Capabilities refresh automatically; the Curated Tools badge reads Media upload available or Media upload unavailable.
Retry the agent call with the same full payload.

Can I use the Scopes & Permissions checkboxes instead? No. Those checkboxes turn areas on or off for your agent. Turning an area off stops its tools from running. They do not add or remove Shopify's permission. Only the Shopify approval screen can grant a permission the store does not have yet.

Does write_files imply read_files? Not for this app — Shopigent requests read_files and write_files as two separate required scopes, and product media upload needs both. In Shopify's model a write scope carries effective read access for the same resource, but upload_product_media polls file status through the Files API, so the app declares both handles explicitly rather than relying on that implication.

Still stuck? Email shopigent@greeknous.com.