Guides

Connect a Shop account

Let the shopper connect their Shop account, so an agent can use their saved addresses and Shop Pay, track their orders, and ask them to approve card payments.

View as Markdown

Search, carts and checkout work without an account. Once the shopper connects their Shop account, the agent can also read their saved addresses and Shop Pay budget with get_account, find their orders with search_orders, and use the approval tools to have them approve a saved card at a store that doesn’t run on Shopify. Searches can draw on their saved preferences, and checkouts can offer Shop Pay.

When to offer it

Offer to connect Shop when the task would use the account, such as when the shopper asks where an order is, wants delivery to a saved address, or wants to pay with Shop Pay. Search works either way, so don’t hold up a search to ask.

Shoppers without an account can create one at shop.com. If the shopper would rather not connect, keep shopping without it.

In Claude or ChatGPT

The client runs the sign-in, and the shopper approves it on Shop’s own page:

In Claude, choose Connect on the Shop connector in Customize > Connectors.
In ChatGPT, complete the prompt to link Shop when it appears.

Another MCP client may not be able to sign in to Shop, even if it supports MCP authorization. Authentication describes what the server sends. If your client can’t connect the account, use the CLI or the device flow below.

With the CLI

shop account login signs in with a device flow: the shopper opens a link, checks a code, and approves on Shop’s site. An agent runs it in two steps, so it can show the shopper the link before it waits. First:

Shell

shop account login --wait 0 --device-name "Sam's laptop"

This returns right away with signed_in: false and a pending object. Show the shopper its verification_uri_complete, or verification_uri and user_code when there’s no complete link, and ask them to approve. Then wait for their approval:

Shell

shop account login --wait 90

Each run picks up the same pending sign-in, so run it again until it returns signed_in: true. Then retry the command that needed the account. If the shopper denies the request or the code expires, the command exits with code 3. Ask the shopper before you start again.

--device-name names the connection in the shopper’s Shop account, so choose something they’ll recognize. It takes 1 to 64 characters. When the CLI can tell which agent is running it, it adds that agent’s name: under Claude Code, Sam's laptop appears as Sam's laptop (Claude Code). Without --wait, the command waits until the code expires when you run it in a terminal, and returns at once otherwise.

shop account logout deletes the sign-in from this device. The connection stays in the shopper’s account until they remove it there, from the manage_connection link that shop account shows while signed in.

The CLI reference covers where the CLI keeps the credential.

In your own code

Run the device flow against Shop’s authorization server, then send the access token with each call to Shop MCP. Keep the token out of the model’s context, chat transcripts, logs and command lines.

Check the connection

Call get_account, with no arguments. It only answers for a signed-in shopper, so a result means the connection works, and an HTTP 401 means it doesn’t. Search is no test, since it works signed out.

Field	What it holds
`buyer.email`	The account’s email address, possibly masked. It’s for display: don’t put it in a checkout.
`addresses`, `preferred_address_id`	The shopper’s saved addresses, and the one they prefer. Add a delivery address shows how to use one.
`payment.instruments`	The Shop Pay budget the shopper allows this connection: its `limit`, `remaining_amount` and renewal, in minor units of `currency`
`selectable_instruments`, `preferred_instrument_id`	Saved cards the shopper can choose for an approval
`links`	Shop pages for the account, for managing this connection (`manage_connection`), and for adding a card
`messages`	Warnings about parts of the account Shop couldn’t read

A missing field means Shop didn’t read that part of the account, and messages says why. An empty list means Shop checked and found nothing.