Skip to main content

Customer Accounts MCP server

Early access

The Customer accounts MCP server is currently available in early access only as part of Shopify's Next-Gen Dev Platform. To get started:

  1. Visit the Next-Gen Dev Platform page and submit a request to join the invitation-only early access program.
  2. Once you have submitted your Next-Gen Dev Platform application, you can request access to the Customer accounts MCP server by completing the early access request form.

Our team will review your requests and follow up with next steps. Early access features are subject to change.

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.


https://{customAccountDomain}/customer/api/mcp

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. Set up authentication by following these steps:

  1. Update your app's toml file with the required customer authentication configuration and redirect URIs:

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

    [mcp.customer_authentication]
    redirect_uris = [
    "https://your-app-domain.com/callback"
    ]
  2. Deploy your application.

  3. Request Level 2 protected customer data (PII) access from your Shopify Partner dashboard.

  4. Install your app on the development store.

  5. Get the customer accounts domain via a Storefront GraphQL request.

  6. Implement the OAuth 2.0 authorization code flow with PKCE, using the OAuth discovery endpoint to get access tokens.

  7. Authenticate your Customer Accounts MCP requests with the access token.


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

Anchor to Step 1: Check for unauthorized accessStep 1: Check for unauthorized access

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:

  • Get the Customer Accounts domain using a Storefront GraphQL request:

    query shop {
    shop {
    customerAccountUrl
    }
    }
  • Create and fetch the OAuth 2.0 discovery endpoint URL from the MCP endpoint:

    https://{customAccountUrl}/.well-known/oauth-authorization-server

Anchor to Step 2: Construct the authorization requestStep 2: Construct the authorization request

Build an OAuth 2.0 authorization request using the PKCE authorization code flow:

// 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 disovery endpoint
// authorization_endpoint value including the params
const authUrl = `${authorizationEndpoint}?${params}`;

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

Anchor to Step 3: Handle the callbackStep 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 discovery request.
  3. Storing the access token securely for future API requests.

Anchor to Step 4: Retry the original requestStep 4: Retry the original request

Use the access token to retry your original MCP request:

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

// Retry the original MCP request with the token
const mcp_url = 'YOUR_MCP_ENDPOINT';
const request_data = {
// Request parameters here
};

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

Anchor to Step 5: Deploy your app and restart the serverStep 5: Deploy your app and restart the server

After configuring customer accounts authentication, deploy your app and restart the server to apply the changes:

shopify app deploy
shopify app dev --use-localhost

The Customer 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.

Anchor to Understanding tool schemasUnderstanding 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.


All MCP Customer Accounts API 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}).

These tools follow standard API rate limiting policies. Make sure you handle rate limit responses appropriately.


Was this page helpful?