# CartBridge Agent Runtime Setup

This is the fastest path for testing CartBridge from an LLM runtime such as Claude Code, Codex, or any local tool host that can run a stdio MCP server. CartBridge is now positioned as the merchant AI Checkout Control Center; agent tools remain the controlled execution surface.

## What The Runtime Needs

- `CARTBRIDGE_AGENT_KEY`: an active CartBridge agent key for the merchant.
- `CARTBRIDGE_BUYER_IP`: the real buyer IP for Shopify Storefront calls.
- `CARTBRIDGE_BASE_URL`: usually `https://cartbridge.ai`.
- A target Shopify shop, such as `cb-test-store-x5l812hm.myshopify.com`.

Do not give the runtime card data. CartBridge returns a Shopify checkout URL fallback and reads Shopify order confirmation after webhooks sync. Use UCP / Shop Pay direct checkout only when the merchant readiness report says that path is ready.

## MCP Server

Download or reference:

```text
https://cartbridge.ai/examples/cartbridge-mcp-server.mjs
```

The server exposes these tools:

- `cartbridge_search_products`
- `cartbridge_prepare_checkout`
- `cartbridge_create_cart`
- `cartbridge_approve_checkout`
- `cartbridge_cart_status`
- `cartbridge_purchase_result`
- `cartbridge_ucp_checkout`
- `cartbridge_wait_for_order`

## Generic Stdio MCP Config

```json
{
  "mcpServers": {
    "cartbridge": {
      "command": "node",
      "args": ["/absolute/path/to/cartbridge-mcp-server.mjs"],
      "env": {
        "CARTBRIDGE_BASE_URL": "https://cartbridge.ai",
        "CARTBRIDGE_AGENT_KEY": "ac_...",
        "CARTBRIDGE_BUYER_IP": "203.0.113.8"
      }
    }
  }
}
```

If your runtime supports remote file execution poorly, put `cartbridge-mcp-server.mjs` and `cartbridge-agent-client.mjs` in the same local folder. The MCP server imports the client with a relative import.

## Shortest Customer Test

Ask the LLM:

```text
Use CartBridge to find an affordable wax product on cb-test-store-x5l812hm.myshopify.com, prepare checkout under $100, and show me the purchase result.
```

The LLM should call `cartbridge_prepare_checkout` with:

```json
{
  "shop": "cb-test-store-x5l812hm.myshopify.com",
  "query": "wax",
  "userRequest": "Find an affordable wax product and prepare checkout under $100.",
  "authorityId": "manual-test-authority",
  "approvedBy": "manual-test-buyer",
  "country": "US",
  "maxTotal": 100
}
```

Expected result before payment:

- A selected Shopify variant.
- A CartBridge cart ID and quote ID.
- A native Shopify checkout URL.
- `purchaseResult.state = "checkout_started"`.
- `purchaseResult.nextAction = "wait_for_shopify_order_webhook"`.
- `purchaseResult.checkoutPath.mode = "shopify_checkout_url"` unless Shopify UCP / Shop Pay is ready.

Expected result after the buyer completes Shopify checkout:

- `cartbridge_purchase_result` returns `confirmed` or `order_synced`.
- The result includes order name, payment status, fulfillment status, final totals, and line items.

## Future No-Browser Test

After `cartbridge_prepare_checkout`, call `cartbridge_ucp_checkout`.

Today, the production test store can return a structured blocker:

```json
{
  "ok": false,
  "status": 302,
  "location": "https://cb-test-store-x5l812hm.myshopify.com/password"
}
```

That means Shopify UCP / Checkout MCP is blocked by the storefront password gate, not that native CartBridge checkout failed.