# BigCommerce Storefront MCP tool boundary — shopper agent

Mark **Allow** or **Deny** before you register a Gateway target. The adapter you own attaches session-sync headers when a Stencil shopper is logged in. AgentCore Gateway can target an MCP URL. It does not add `X-Bc-Storefront-Sync-Token`.

Storefront MCP is beta. A store owner enables it under Settings, Early access, MCP Integration. The URL can take up to 10 minutes to answer. Each storefront has its own URL. B2C and B2B tool sets share that URL.

| Tool | Surface | Auth | Shopper week one | Check |
| --- | --- | --- | --- | --- |
| `search_products` | B2C Storefront MCP | Guest, or session sync for a logged-in shopper | Allow | `term` is at least 3 characters. `context` carries no PII. Paginate with `cursor`. Stop when `nextCursor` is null. |
| `get_product_details` | B2C Storefront MCP | Same as search | Allow | Pass `option_values` when the product has options. Confirm the variant exists before you recommend it. |
| `related_products` | B2C Storefront MCP | Same as search | Allow | Suggestions only. A related product is not a cart line until the shopper picks it. |
| `add_item_to_cart` | B2C Storefront MCP | Same as search | Allow | `variantEntityId` is required when the product has variants. Claim the add only when the returned cart shows that line. |
| `update_cart_item` | B2C Storefront MCP | Same as search | Allow | Changes one line. Read the returned cart before you tell the shopper the quantity changed. |
| `remove_item_from_cart` | B2C Storefront MCP | Same as search | Allow | Removes the line. Use `update_cart_item` to lower quantity. |
| `create_checkout_url` | B2C Storefront MCP | A cart must already exist. 0 inputs. | Allow only after the shopper asks to pay | Returns `checkoutURL`. Send the shopper to that URL. The tool does not create an order. |
| Shopping lists, quotes | B2B Storefront MCP | Authenticated Buyer Portal user, per buyer permission | Deny on this agent | Same MCP URL, different tools. A guest session does not inherit them. |
| `getOrder` / catalog admin reads | Management API `https://api.bigcommerce.com/stores/{store_hash}/` | `X-Auth-Token` on a dedicated API account | Deny | Different secret. See the [API accounts post](https://www.factualminds.com/blog/bigcommerce-ai-agents-ecommerce-2026/). |
| Refund, order modify, `createHook` | Management API writes | Modify scopes | Deny | A person signs money and stock. Webhooks are deploy-time configuration. |
| GraphQL Storefront `completeCheckout` | Storefront GraphQL, not MCP | Storefront token | Deny | Returns `orderEntityId` and a payment access token. That is a charge path. This agent uses `create_checkout_url`. |

## Credential split

| Secret | Who | Where it lives |
| --- | --- | --- |
| Storefront MCP URL | Public to the team that integrates | Control panel, per storefront. Not a staff password. |
| `X-Bc-Storefront-Sync-Token` | Stencil browser session, short lived | Passed into MCP `initialize` by the adapter. Not the prompt. |
| Management API access token | Merchant tools only | AgentCore Identity or Secrets Manager. A second secret. |

## What the adapter must do on every shopper turn

- Allow-list the tool name. A path the model typed is not a tool.
- On `search_products`, reject a `term` shorter than 3 characters before the call.
- On cart writes, treat the returned cart as the read-back. Speak only when that payload contains the line you claim.
- On `create_checkout_url`, put `checkoutURL` in the reply. Do not say the order exists.
- When Storefront Session Sync is in use, send `X-Bc-Storefront-Sync-Token` on initialize. If a new cart returns `X-Bc-Mcp-Stencil-Sync-Code`, forward that code to the browser.
- On HTTP 429, back off and tell the model the shop is busy. Do not call the Management API instead.

## Explicitly not in this worksheet

B2B Buyer Portal tool schemas, Stencil theme code, a BigCommerce marketplace app, and a measured add-to-cart rate.