Shop MCP

Reference

API keys

OAuth is the preferred client setup. Static API-key URLs remain available for MCP clients that cannot complete the browser flow.

How they work

When you create a key in Settings → Connections, we generate a high-entropy random token, hash it, and show the plaintext exactly once in the create dialog.

Standard additional keys are hash-only. OAuth-capable client-profile keys, such as Microsoft Copilot, also keep an envelope-encrypted copy of the token so the OAuth token endpoint can return the dedicated scoped bearer after sign-in.

Static MCP URLs include ?token=smcp_.... The runtime hashes the incoming token, resolves its workspace and access scope, and runs the request inside that tenant boundary. OAuth clients use https://my.shop-mcp.app/api/mcp without a query token; ShopMCP returns the appropriate workspace bearer only after browser consent.

One static key per client

If a client requires a static URL, create one key for that client and name it after its location or purpose. That way you can revoke one machine or automation without breaking other clients. OAuth-capable clients should use their own login flow instead of sharing a copied URL.

Keys are workspace-scoped, not automatically created when you invite a user. Owners and admins create dedicated MCP URLs for teammates, then choose all access or custom access to specific integrations and connections.

Rotation

To rotate a key:

  • Create a new MCP URL with a similar name (e.g. add a date suffix).
  • Update the chat client config to use the new URL.
  • Restart the client and confirm tools still load.
  • Delete the old URL.

We recommend rotating every 90 days for any key that lives on a shared machine. Keys on your personal devices can rotate yearly.

If a key leaks

Revoke immediately

A leaked MCP URL can read every connected module in its access scope. Delete it from Settings → Connections right away — revocation is instant, the next call from that key returns a 401.

Then check Usage for any tool calls in the window between leak and revocation. If you see anything you don't recognize, email security@shop-mcp.app and we'll help you trace what was accessed.

Concurrent sessions

Every connection to your MCP URL is tracked as a “session”. A session is identified by a stable hash of api_key + IP + user-agent — the same Claude Desktop install on the same network reuses the same session across restarts; a second laptop on the same key shows up as a distinct session.

  • Solo: 2 devices (laptop + desktop). A 3rd concurrent device evicts the oldest — the evicted client gets a clear error pointing to an upgrade.
  • Brand: 6 devices per workspace (3 included people × laptop + desktop headroom). Adding a teammate does not create an MCP URL automatically.
  • Portfolio: 14 devices per workspace (7 included people × 2).
  • Agency: 24 devices per workspace (12 included people × 2).
  • Agency Scale: device count is contract-driven — your rep sets the cap.

Each additional paid seat on Brand or higher adds two concurrent device slots per workspace. Named people are counted once across the billing account. Existing customers retain their previous device allowance until they opt into account seat pricing.

Active devices, including ones pending approval, are listed at Settings → Devices. You can revoke a device there to force it to reconnect.

Device approval (Solo only)

Solo is a single-user plan, so the first time a new device fingerprint connects we block tools/call until you approve the device in Settings → Devices. The client can still list tools, but running them returns a device_pending_approval error with a link to approve.

Human-device approvals are valid for 30 days — after that, a re-prompt. A verified Google Apps Script project is approved once and stays trusted until you revoke it or rotate its API key; each new script project still needs its own first approval. Brand, Portfolio, Agency, and Agency Scale skip this step (seat-based eviction handles device turnover).

Anomaly alerts

We watch for two patterns and email the workspace owner when either trips:

  • Impossible travel: the same key used from two different countries within 24 hours.
  • Instance sharing: too many distinct client fingerprints on one key in 7 days. Threshold scales with tier — 2 for Solo, 5 for Brand, 10 for Portfolio, 20 for Agency, and whatever your contract specifies for Agency Scale.

First alert is email-only. A second alert within 30 days evicts every active session (clients must reconnect). A third alert revokes the key entirely and you need to rotate from Settings → Connections. This is the anti-sharing escalation ladder; legitimate single-user usage never reaches level 2.

OAuth and client profiles

ShopMCP supports OAuth with PKCE, protected-resource discovery, authorization-server metadata, and dynamic client registration. Existing static URL tokens continue to work. Claude Directory uses the same owner primary key or member-scoped key as a manually added ShopMCP connection, so ShopMCP's integration and account toggles remain authoritative. Microsoft Copilot keeps its dedicated read-only client profile.