API keys

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.

Every MCP URL includes ?token=smcp_.... The MCP runtime hashes the incoming token, looks it up, and resolves the workspace. From that point on, the request runs scoped to your workspace's data only.

We strongly recommend creating one key per machine or client, named after where you'll use it (e.g. Claude Desktop on my laptop, Cursor on the office iMac). That way if you lose a laptop or rotate a machine you can revoke just that key without breaking the others.

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.

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.

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 (3 users × laptop + desktop headroom). Adding a teammate does not create an MCP URL automatically.
• Portfolio: 10 devices per workspace (5 users × 2), shared across every brand workspace on the account.
• Agency: 20 devices per workspace (10 users × 2), shared across all branched client workspaces.
• Agency Scale: device count is contract-driven — your rep sets the cap.

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

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.

Approvals are valid for 30 days per device — after that, a re-prompt. Brand, Portfolio, Agency, and Agency Scale skip this step (seat-based eviction handles device turnover).

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.

ShopMCP supports OAuth 2.1 + PKCE for MCP clients that require a sign-in flow. Existing URL tokens continue to work. Microsoft Copilot OAuth uses a dedicated scoped Copilot key; older non-Microsoft OAuth clients keep their current behaviour while we migrate them to client-specific scoped profiles.