mcp-customer

@evolve-platform/mcp-customer is a customer-facing MCP server built on mcp-core. It exposes the tools that an AI assistant needs to help customers browse products, manage their cart, view orders, and handle their account.

Available tools

Authentication

Tool	Description
`customer_login`	Log in with email and password
`customer_logout`	Log out and revert to a guest session
`get_current_user`	Get the currently authenticated customer

Products

Tool	Description
`get_products`	Search products with filters and sorting
`get_product_detail_page`	Get full product details by slug
`get_products_by_skus`	Batch retrieve products by SKU

Cart

Tool	Description
`get_cart`	Get the active cart
`cart_line_items_add`	Add products to the cart
`cart_line_items_remove`	Remove items from the cart
`cart_line_items_update`	Update item quantities
`cart_discount_code_add`	Apply a discount code
`cart_discount_code_remove`	Remove a discount code

Checkout

Tool	Description
`get_cart_checkout_details`	Get cart details for checkout, including available shipping and payment methods
`cart_set_shipping_address`	Set the shipping address on the cart
`cart_set_billing_address`	Set the billing address on the cart
`cart_set_customer_email`	Set the customer email on the cart
`cart_set_shipping_method`	Select a shipping method
`cart_set_payment_method`	Select a payment method
`checkout_complete`	Complete the checkout and create an order
`address_validate`	Validate an address, with correction suggestions

Shopping lists

Tool	Description
`get_customer_shopping_lists`	List all shopping lists (paginated)
`get_customer_shopping_list`	Get a specific shopping list
`add_to_shopping_list`	Add items to a shopping list
`remove_shopping_list_item`	Remove items from a shopping list

Customer account

Tool	Description
`get_customer`	Get customer data with addresses
`customer_address_create`	Create a new address
`customer_address_update`	Update an existing address
`customer_address_delete`	Remove an address from the address book

Orders

Tool	Description
`order_history_query`	Get the customer’s order history
`get_order_detail`	Get detailed information about an order by order number

Example interaction

Here is what a typical AI-assisted shopping session looks like from the tool invocation perspective:

sequenceDiagram
    participant User as Customer
    participant AI as AI Assistant
    participant MCP as mcp-customer

    User->>AI: I'm looking for running shoes
    AI->>MCP: get_products(query: "running shoes")
    MCP-->>AI: Product results
    AI->>User: Here are some options...

    User->>AI: Tell me more about the Nike Air Zoom
    AI->>MCP: get_product_detail_page(slug: "nike-air-zoom")
    MCP-->>AI: Full product details
    AI->>User: Details and pricing...

    User->>AI: Add it to my cart, size 42
    AI->>MCP: cart_line_items_add(sku: "nike-air-zoom-42", quantity: 1)
    MCP-->>AI: Updated cart
    AI->>User: Added to your cart!

    User->>AI: I have a discount code SAVE10
    AI->>MCP: cart_discount_code_add(id: "<cart id>", code: "SAVE10")
    MCP-->>AI: Cart with discount applied
    AI->>User: Discount applied, your new total is...

Running locally

cd backend/services/mcp-customer

# Generate tools from GraphQL operations
pnpm codegen

# Start with HTTP transport (port 4050)
pnpm dev

# Start with stdio transport (for Claude Desktop)
pnpm dev:stdio

Store context

The mcp-customer service supports multi-store configurations. When connecting over HTTP, clients can pass store context via headers:

Header	Description
`X-StoreContext-Locale`	Locale for the session (e.g., `en-US`)
`X-StoreContext-Currency`	Currency code (e.g., `EUR`)
`X-StoreContext-StoreKey`	Store identifier
`X-StoreContext-CustomerGroup`	Customer group for pricing