Storefront Session Sync

The BigCommerce MCP server supports session sync for Stencil storefronts. After syncing, the MCP session is linked to the shopper’s existing browser session — carrying their login state, cart, and identity context into the AI agent without exposing cookies.

How session sync works

Stencil maintains shopper state through HttpOnly browser cookies. Because the AI agent backend runs on a separate host from the storefront, those cookies cannot reach it directly.

Session sync bridges this gap using a short-lived opaque token:

1. Stencil generates a token — The storefront calls the generateSessionSyncToken GraphQL mutation. The token is a one-time opaque token linked to the shopper’s current session, valid for 60 seconds.
2. The token is passed to the agent — Your storefront customization passes the token to the AI agent backend (for example, via a chat widget initialization payload).
3. The agent includes the token at MCP initialization — The agent passes the token in the X-Bc-Storefront-Sync-Token header when initializing the MCP connection.
4. MCP redeems the token — The MCP server validates and atomically consumes the token, retrieves the linked storefront session, and builds an MCP session scoped to that shopper.

From this point on, tool calls run in the context of the shopper’s session — their cart, login state, and (if B2B is enabled) their company and permissions. See B2C Storefront and B2B Storefront for how each uses the synced session. Catalog, cart, and checkout are the base tool set and work the same way for guests, logged-in customers, and company (B2B) buyers; the Buyer Portal–specific tools (shopping lists, quotes) are the extension on top, and always require this session to be active.

Sequence diagram

Generating a sync token

Call the generateSessionSyncToken GraphQL mutation from the Stencil storefront page. This must be called from a browser session — server-to-server calls are blocked.

mutation {
  generateSessionSyncToken {
    token
  }
}

Response:

{
  "data": {
    "generateSessionSyncToken": {
      "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}

The token is valid for 60 seconds and can only be redeemed once. Generate it immediately before passing it to the agent — do not cache or reuse tokens.

Passing the token at MCP initialization

Pass the sync token as the X-Bc-Storefront-Sync-Token request header on the standard MCP initialize request that opens the connection. Nothing about the request body changes — the header is the only addition.

POST /api/mcp
Content-Type: application/json
X-Bc-Storefront-Sync-Token: a1b2c3d4-e5f6-7890-abcd-ef1234567890
{
  "jsonrpc": "2.0",
  "method": "initialize",
  ...
}

On a successful sync, the MCP server returns a Mcp-Session-Id in the response. The agent should include this header on all subsequent requests in the session.

If the token is invalid or expired, the initialize request returns an error. Request a new token from the storefront and retry initialization.

Reverse sync: MCP to Stencil

Some MCP tool calls mutate the storefront session in ways that rotate browser cookies. Cart creation is the primary case: when add_item_to_cart creates a new cart, the storefront rotates session cookies and the browser’s existing cookies become stale.

When MCP detects a cookie rotation, it automatically generates a sync code and returns it to the agent in the X-Bc-Mcp-Stencil-Sync-Code response header. The sync code is one-time use with a 60-second TTL, and is only returned once — on the tool call that triggered the cookie rotation. Your agent must forward this value to the browser so Stencil can apply the updated cookies.

Handling the sync code

mutation ApplySessionSyncCode($code: String!) {
  applySessionSyncCode(code: $code) {
    success
  }
}

The sync code has the same security properties as the initialization token: an opaque, single-use token with a 60-second TTL, returned only once.

When to expect a sync code

Session termination and re-sync on auth state change

When a shopper logs in or logs out in the browser while an MCP session is active, the MCP session is terminated. This ensures the agent always operates with the correct principal and tool set — logging in may grant a shopper access to more tools, while logging out takes some away.

What happens

On each tool call, the MCP server compares the shopper’s auth state against what was present at session creation:

When the session is terminated, the MCP server returns HTTP 404 on the tool call. This signals the agent that re-initialization is required.

Handling a 404 session termination

Token reference

Initialization token (X-Bc-Storefront-Sync-Token)

Reverse sync code (X-Bc-Mcp-Stencil-Sync-Code)