# 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.

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](approvals.md) 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](https://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](authentication.md#how-the-server-asks-for-a-token) 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:

```sh
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:

```sh
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](cli.md#sign-in-and-credentials) covers where the CLI keeps the credential.

## In your own code

Run the [device flow](authentication.md#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](checkout.md#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](approvals.md) |
| `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.