> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # B2C Storefront The B2C storefront MCP server supports both guest and authenticated shopping flows. AI agents can search your product catalog, build a cart, and generate a checkout link on behalf of any shopper. When paired with [Storefront Session Sync](/developer/api-reference/mcp/storefront-session-sync), the agent operates in the shopper's existing browser session — carrying their login state, cart, and personalized pricing. ## Example prompts * "Find Nike running shoes size 10 that are under \$120." * "Show me the top 5 bestsellers in 'Hoodies'." * "What goes well with this jacket?" * "I'm ready to check out." ## Tools #### search\_products Search the storefront product catalog by keyword. Supports cursor-based pagination for browsing large result sets. | Input | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------- | | `term` | string | Yes | Search keyword. Must be at least 3 characters. | | `cursor` | string | No | Pagination cursor from a previous response's `nextCursor` field. Omit for the first page. | | `context` | string | No | Additional context about the request (demographics, mood, location) to help tailor results. Must not contain PII. | Returns a list of matching products including name, description, and available options. When `nextCursor` is `null`, there are no more results. #### get\_product\_details Fetch variants and images for a specific product by ID. Use this after `search_products` to retrieve the information needed before adding an item to the cart. | Input | Type | Required | Description | | --------------- | ------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer | Yes | Product entity ID from `search_products`. | | `option_values` | array | Yes (when product has options) | Option selections. Each entry requires `optionEntityId` and `valueEntityId`. If the product has options, prompt the shopper to choose before calling this tool. | Returns product images and available variants with SKUs. #### related\_products Retrieve products that are related to a specific product. Use this after `search_products` to help shoppers discover complementary or similar items. | Input | Type | Required | Description | | ------------ | ------- | -------- | ------------------------------------------------------------------------------ | | `product_id` | integer | Yes | The unique identifier of the product whose related items you want to retrieve. | Returns a list of related products including name, description, available options, and price. #### add\_item\_to\_cart Add a product to the cart. If no cart exists in the current session, one is created automatically. | Input | Type | Required | Description | | ---------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------- | | `item.quantity` | integer | Yes | Number of units to add. | | `item.productEntityId` | integer | Yes | Product entity ID. | | `item.variantEntityId` | integer | No | Variant entity ID. Required when the product has variants. | | `item.selectedOptions` | object | No | Option selections for checkboxes, date fields, text fields, multiple choice, and number fields. | Returns the updated cart. #### update\_cart\_item Change the quantity, variant, or options for an existing line item in the cart. | Input | Type | Required | Description | | ---------------------- | ------- | -------- | ------------------------------------------ | | `line_item_id` | string | Yes | Entity ID of the cart line item to update. | | `item.quantity` | integer | Yes | Updated quantity. | | `item.productEntityId` | integer | Yes | Product entity ID. | | `item.variantEntityId` | integer | No | Updated variant entity ID. | | `item.selectedOptions` | object | No | Updated option selections. | Returns the updated cart. #### remove\_item\_from\_cart Remove a line item completely from the cart. To reduce quantity without removing the item, use `update_cart_item` instead. | Input | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------ | | `item_id` | string | Yes | Entity ID of the cart line item to remove. | Returns the updated cart. #### create\_checkout\_url Generate a checkout URL for the cart in the current session. Requires a cart to exist. No inputs required. Returns `checkoutURL` — redirect the shopper to this URL to complete their purchase. ## Typical flow #### Search for products Call `search_products` with a keyword to find matching items. Use `cursor` to paginate through large result sets. #### Get product details Call `get_product_details` with the product ID. If the product has options (size, color, etc.), prompt the shopper to choose before proceeding. #### Suggest related products (optional) Call `related_products` with the product ID to surface complementary or similar items the shopper might also want. #### Add to cart Call `add_item_to_cart` with the selected product, variant, and quantity. A cart is created automatically if one does not already exist. #### Adjust the cart Use `update_cart_item` to change quantities or variants, or `remove_item_from_cart` to remove items the shopper no longer wants. #### Go to checkout Call `create_checkout_url` and redirect the shopper to the returned URL to complete their purchase. ## Typical flow — authenticated shopper For storefronts using [Storefront Session Sync](/developer/api-reference/mcp/storefront-session-sync), the agent can operate in the shopper's existing logged-in session. #### Sync the session Before initializing the MCP connection, call `generateSessionSyncToken` from the Stencil storefront and pass the token to your agent. The agent includes it as `X-Bc-Storefront-Sync-Token` on the MCP `initialize` request. See [Storefront Session Sync](/developer/api-reference/mcp/storefront-session-sync) for the full flow. #### Search and browse Call `search_products` and `get_product_details`. For logged-in customers, results reflect customer-specific pricing and catalog availability configured via customer group access rules on the store. #### Add to cart Call `add_item_to_cart`. If this creates a new cart, the MCP server returns an `X-Bc-Mcp-Stencil-Sync-Code` header in the response. Forward this code to the browser and call `applySessionSyncCode` to keep the browser session in sync. #### Adjust the cart Use `update_cart_item` and `remove_item_from_cart` as needed. #### Go to checkout Call `create_checkout_url`. The returned URL is a plain `/checkout` link — it doesn't carry the session itself. Since the shopper's browser already holds the authenticated cookies from the synced session, opening that URL in their browser lands them in checkout with their account, saved addresses, and any account-level pricing already applied. ## Example Here is `search_products` in action inside Claude, searching a sample store for products related to coffee. ![Claude's response showing search\_products was called with the term espresso](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/bigcommerce.docs.buildwithfern.com/844efba4cc42fd97d9e67eee48a636b4530ca6227295a57ed1f750770ca1504a/assets/mcp/mcp-tool-call.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260925%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260925T114353Z&X-Amz-Expires=604800&X-Amz-Signature=a96d81e70501d8def50b2e1529943cb6d16b38973b2a111a7ba83d3a2d29b151&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)![Expanded view showing the search\_products request body and matching product results](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/bigcommerce.docs.buildwithfern.com/36754e0048c4e81e7eb21323588b741c8f390da1393a8ee142318c900958aa87/assets/mcp/mcp-tool-call-expanded.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260925%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260925T114353Z&X-Amz-Expires=604800&X-Amz-Signature=c9f018952377cb5bd0b06c3d16f18adcd60e7ca1aa05648d43118f3f8323fda6&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)