---
title: Customer Accounts MCP server
description: >-
  Learn how to use the Customer Accounts MCP server tools to help customers
  manage their orders, returns, and account preferences.
source_url:
  html: 'https://shopify.dev/docs/apps/build/customer-accounts-mcp'
  md: 'https://shopify.dev/docs/apps/build/customer-accounts-mcp.md'
---

# Customer Accounts MCP server

The Customer Accounts MCP server provides tools for customer-specific actions, including order management and account details. Use this server when your AI assistant needs to handle authenticated customer requests, such as checking order status, retrieving order details, or managing account preferences.

**Building a commerce agent?:**

Catalog, cart, and checkout MCP tools are now documented as part of [Agentic commerce](https://shopify.dev/docs/agents). See [Storefront Catalog MCP](https://shopify.dev/docs/agents/catalog/storefront-catalog), [Cart MCP](https://shopify.dev/docs/agents/carts-and-checkout/cart-mcp), and [Checkout MCP](https://shopify.dev/docs/agents/carts-and-checkout/checkout-mcp).

***

## Requirements

* Your store must have a custom domain configured.
* Your app must meet [Shopify's protected customer data requirements](https://shopify.dev/docs/apps/launch/protected-customer-data).
* You must [set up your app](#set-up-your-app) for customer accounts authentication.

***

## Set up your app

To use the Customer Accounts MCP server, configure your app and request the required customer data access.

1. [Scaffold an app](https://shopify.dev/docs/apps/build/scaffold-app) with Shopify CLI. If you already created the app in the Dev Dashboard, then run `shopify app config link` in your local project to connect it. For details, refer to [Manage app configuration files](https://shopify.dev/docs/apps/build/cli-for-apps/manage-app-config-files).

2. Create a [dev store](https://shopify.dev/docs/apps/build/stores/development-stores). Make sure to add some sample products to test the AI agent functionality.

3. Log in to your [Shopify Partners dashboard](https://partners.shopify.com/), navigate to **Apps**, and select your app under the Dev Dashboard apps tab.

4. Click **API access requests**.

5. Click **Request access** under the Protected customer data section.

6. Click **Select** on **Protected customer data**, and then provide a clear reason for requesting this data.

7. Click **Select** for each data field: `name`, `email`, `phone`, and `address`. Provide a clear reason for requesting each field.

8. Add the access scopes and customer authentication redirect URIs to your `shopify.app.toml` file:

   ## shopify.app.toml

   ```toml
   [access_scopes]
   scopes = "customer_read_customers, customer_read_orders..."


   [customer_authentication]
   redirect_uris = [
     "https://your-app-domain.com/callback"
   ]
   ```

   Replace `your-app-domain.com` with your actual app domain.

***

## Endpoint

The MCP server endpoint is dynamically discovered from the shop's storefront domain. Use the discovery endpoint to get the correct MCP URL:

```javascript
// Discover the MCP endpoint from the shop's storefront domain
const discoveryResponse = await fetch(`https://${shopDomain}/.well-known/customer-account-api`);
const apiConfig = await discoveryResponse.json();


// Use the discovered MCP endpoint
const mcpEndpoint = apiConfig.mcp_api;
// Result: "https://{shopDomain}/customer/api/mcp"
```

***

## Authentication

The Customer Accounts MCP server requires authentication via an OAuth 2.0 access token. You'll need to get this token using the authorization code grant flow with PKCE. After you [set up your app](#set-up-your-app), authenticate requests by following these steps:

1. Deploy your application.
2. Install your app on the dev store.
3. Get the OAuth 2.0 authentication URLs using the [storefront discovery endpoint.](#step-1-discover-the-authentication-endpoints-from-the-shops-storefront-domain)
4. Using the OAuth 2.0 discovery endpoints, implement the authorization code flow with PKCE to get an access token.
5. Authenticate your Customer Accounts MCP server requests with the access token.

***

## Implementation

Integrate the Customer Accounts MCP server with your AI shopping assistant by following these steps.

The authentication flow begins when your app attempts to access customer data without a valid access token. When the Customer Accounts MCP server returns a `401 Unauthorized` response, you need to initiate the OAuth flow. Your app should perform the following steps.

### Step 1: Discover the authentication endpoints from the shop's storefront domain

```javascript
// Discover OAuth endpoints from the storefront domain
const oauthDiscoveryResponse = await fetch(`https://${shopDomain}/.well-known/openid-configuration`);
const oauthConfig = await oauthDiscoveryResponse.json();


// oauthConfig contains:
// {
//   "authorization_endpoint": "https://{shopDomain}/authentication/{shop_id}/oauth/authorize",
//   "token_endpoint": "https://{shopDomain}/authentication/{shop_id}/oauth/token",
//   ...
// }
```

### Step 2: Construct the authorization request

Build an OAuth 2.0 authorization request using the [PKCE authorization code flow](https://datatracker.ietf.org/doc/html/rfc7636):

```javascript
// Authorization URL format
const params = new URLSearchParams({
  // Your AppID serves as the OAuth client_id
  client_id: 'YOUR_APP_ID',
  // Must match the one in your TOML unless local development where
  // you can use localhost in the request
  redirect_uri: 'YOUR_REDIRECT_URI',
  response_type: 'code',
  // The scopes from your TOML file
  scope: 'customer-account-mcp-api:full',
  // 16-byte hex for CSRF protection
  state: 'RANDOM_HEX',
  // SHA256 hashed and base64URL encoded
  code_challenge: 'PKCE_CHALLENGE',
  code_challenge_method: 'S256'
});


// Build the full authorization URL using the discovered endpoint
const authUrl = `${oauthConfig.authorization_endpoint}?${params}`;


// Redirect the user to start the OAuth flow
window.location.href = authUrl;
```

### Step 3: Handle the callback

After the user authenticates, handle the callback by:

1. Receiving the authorization code at your registered redirect URI.
2. Exchanging this code (with the original `code_verifier`) for an access token using the `token_endpoint` value from the OAuth discovery response (`oauthConfig.token_endpoint`).
3. Storing the access token securely for future API requests.

### Step 4: Retry the original request

Use the access token to retry your original MCP request:

```javascript
const headers = {
  'Authorization': 'YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};


// Use the discovered MCP endpoint
const mcp_url = apiConfig.mcp_api;
const request_data = {
  // Request parameters here
};


fetch(mcp_url, {
  method: 'POST',
  headers,
  body: JSON.stringify(request_data)
});
```

### Step 5: Deploy your app and restart the server

After configuring customer accounts authentication, restart the server, if it's not already running:

```terminal
shopify app dev --use-localhost
```

***

## Available tools

The Customer Accounts MCP server provides a set of tools for managing customer accounts and orders. Use the `tools/list` command to discover available tools and their capabilities. Each tool is documented with a complete schema that defines its parameters, requirements, and response format.

### Understanding tool schemas

Each tool provides a JSON schema that defines:

* Required and optional parameters
* Data types and formats
* Validation rules and constraints
* Enumerated values where applicable
* Response schema

Tools follow these common patterns:

* IDs follow the format `gid://shopify/<Type>/<id>`
* Order numbers may include an optional `#` prefix
* Quantities are positive integers
* Dates are in ISO 8601 format
* Monetary amounts include currency codes

You can introspect the tools schema with the `tools/list` command.

***

## Error handling

All Customer Accounts MCP server tools use consistent error-handling patterns:

* Validation errors: Return specific, descriptive error messages.
* Processing errors: Return `Unable to process the request, try again`.
* Resource not found errors: Return clear messages about the missing resource (such as `Order not found with number: {order_number}`).

***

## Rate limits

These tools follow [standard API rate limiting](https://shopify.dev/docs/api/customer#rate-limits) policies. Make sure you handle rate limit responses appropriately.

***