Get started

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, physical-store lookup, carts and checkout work without an account. Once the shopper connects their Shop account, the agent can also read their saved addresses, spend permissions and saved payment methods with get_account, search their Shop-tracked order history with search_orders, and use the spend request 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.

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 and revokes it at Shop. When no other sign-in for the same client remains, the connection leaves the shopper’s account too. Otherwise the connection stays until the last sign-in ends or the shopper removes it, 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

For an app you distribute, use your own application client, not the CLI’s public client. The server-side flow below uses your registered private OAuth client to connect the shopper’s Shop account. Your backend manages sign-in, token refresh and sign-out, and supplies the access token to the CLI as SHOP_ACCESS_TOKEN.

The authorization server metadata lists the endpoints and supported client authentication methods.

Authenticate token and revocation requests with your client ID and secret using client_secret_basic or client_secret_post (RFC 6749 §2.3.1). Keep the client secret and refresh token on your backend.

The standard authorization code flow with PKCE (S256) replaces shop account login. Request the openid personal_agent scopes and resource=https://mcp.shop.com, with no trailing slash.

Example authorization URL:

Text

https://accounts.shop.app/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2F2.zoppoz.workers.dev%3A443%2Fhttps%2Fyour-app.example%2Foauth%2Fcallback&scope=openid%20personal_agent&resource=https%3A%2F%2F2.zoppoz.workers.dev%3A443%2Fhttps%2Fmcp.shop.com&state=YOUR_STATE&code_challenge=YOUR_PKCE_CHALLENGE&code_challenge_method=S256

Exchange the authorization code at POST https://accounts.shop.app/oauth/token:

Text

grant_type=authorization_code
code=CODE_FROM_CALLBACK
redirect_uri=https://your-app.example/oauth/callback
code_verifier=YOUR_STORED_PKCE_VERIFIER

Supply your client ID and secret to the token endpoint to receive a refresh token.

Supply access_token to the CLI process as SHOP_ACCESS_TOKEN. The CLI uses it instead of a stored sign-in and never stores or refreshes it.

Shell

# SHOP_ACCESS_TOKEN is supplied by your backend in the process environment.
shop account

For direct MCP calls, use the Bearer header. See Authentication errors for failed requests.

Refresh an access token

Use the standard refresh-token exchange at POST https://accounts.shop.app/oauth/token:

Text

grant_type=refresh_token
refresh_token=YOUR_STORED_REFRESH_TOKEN

Save the returned tokens on your backend and supply the new access_token as SHOP_ACCESS_TOKEN.

Sign out

Standard token revocation replaces shop account logout. Send the refresh token to POST https://accounts.shop.app/oauth/revoke:

Text

token=YOUR_STORED_REFRESH_TOKEN
token_type_hint=refresh_token

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.
`spend_permissions`	Permissions the shopper granted the agent: `id`, `status`, optional label, currency, limit, per-purchase limit and period, plus `allowance.status` and `allowance.remaining` when available
`selectable_instruments`, `preferred_instrument_id`	Saved cards the shopper can choose for a spend request, and the pointer to their preferred saved card; separate from spend permissions
`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 no result was returned for that part of the account. Use messages when present to distinguish skipped, unavailable or withheld reads; not every omission has a warning. An empty list means Shop checked and found nothing available.

Client permissions and runtime availability apply separately; the latest checkout’s status and offered instruments determine payment eligibility.

Spend permissions

get_account returns the shopper’s spend permissions in spend_permissions. Each permission describes spending limits the shopper has set for the agent. It can include a currency, a per-purchase limit, a limit for a period, and the remaining allowance. Remaining allowance is how much is left under that permission—not the balance of a saved card or bank account. Amounts use the currency’s minor units.

Spend permissions are separate from spend requests: a permission describes the shopper’s configured spending limits; a spend request represents a particular purchase. See Spend requests for that flow.