Shopigent Shopigent

Getting Started with Shopigent

This guide walks you through connecting an AI agent to your Shopify store with Shopigent.

1. Install

Install Shopigent from the Shopify App Store and grant the scopes your store needs.

2. Choose what the agent can run

On Curated Tools, each tool has an enable switch. Enable all and Disable all apply to the tools in the open category that you can toggle. On Scopes & Permissions, each area has its own on/off switch. Turning an area off stops tools in that area from running. It does not, by itself, remove an enabled tool from the MCP tool list.

Optional: Turn on read-only starter set. It enables product and order read tools whose areas Shopify has granted. It does not turn write tools on. If a write tool in an area this turns on was already enabled, that write can run again because the area is on.

3. Issue a connection key

Shopigent is the MCP server. The server address is https://mcp.shopigent.greeknous.com/mcp. On the dashboard, the button is Generate connection key when no key exists, and Regenerate connection key when one does. The key is shown once. Shopigent stores a SHA-256 hash of the key. The hash is not salted. Send the key as a Bearer token. Do not use https://app.shopigent.greeknous.com/mcp.

A downloaded client config for Claude Desktop, Cursor, Hermes, or the generic file uses the placeholder YOUR_API_KEY. The download does not contain the key. Paste the key from the dashboard into the file.

4. Connect your AI agent

Now that you have an API key, choose your tool and follow the dedicated guide:

Or read the Prompts & Best Practices guide for tips and examples.

5. Confirmation, audit log, and dashboard checks

Destructive actions default to requiring your approval. Publishing a product to a sales channel, changing a variant's shipping weight, uploading product media, and creating a theme pull request always pause and cannot be turned off. Other writes follow that tool's confirmation setting.

A paused call returns confirmation_pending and a token. Approve by re-calling with confirmed true and that token, or, when the pause is stored, open Confirmations and choose Approve or Decline. Approve runs the tool only if the server check passes. Decline does not run the tool. The page does not show the token. A product media upload cannot be approved there because the file payload is not stored.

The Audit Log shows the 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.

Recent activity on the dashboard counts successful writes, dry-runs, confirmations waiting, and confirmations declined for the last 24 hours and the last 7 days. A write in that card is a mutation stored as success. Dry-runs were not executed. Setup check is the install health check. It is read-only: it can report a missing connection key, an enabled tool whose scope category is not granted, or an enabled destructive tool with confirmation off. It does not change areas, confirmation settings, or the key. Curated Tools shows usage from the stored audit log for each tool: call count, last status, and last dry-run time. When none are stored, it says "No calls stored."

Reauthorizing after an app update

When Shopigent ships a new scope (e.g. the read_files and write_files pair from a recent update), already-installed stores need to reauthorize the app before the new tool becomes available. Here is the lifecycle:

  1. Deploy. The app update ships with the new scope declared in its configuration.
  2. Detect. The Scopes & Permissions page shows the scope as Not yet granted and lists the exact missing handle.
  3. Grant. Click Grant missing permissions — this redirects to the Shopify install screen. Your store sees the exact new permissions requested.
  4. Approve. Shopify asks you to confirm the new permissions. Approve to complete reauthorization.
  5. Persist. The app stores the updated grant and verifies it against a live Shopify snapshot.
  6. Refresh. Capability caches are invalidated. The Curated Tools page updates to Media upload available or Media upload unavailable.
  7. Verify. The media badge can show Media upload available. A live upload still requires confirmation. Retry the agent call with the same full payload.

Enabled vs. granted: The Enabled checkbox on Curated Tools controls whether that tool is offered to your AI agent. It does not add or remove Shopify OAuth scopes. The Enabled checkbox on Scopes & Permissions is separate: turning an area off stops tools in that area from running, and turning it back on does not ask Shopify for permission again. A tool can be enabled and still fail until the store has granted the underlying permission. The app shows both states independently.

Next steps