> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Commerce gateway

# Commerce Gateway

The Commerce Gateway exposes Better Data capabilities to MCP-compatible AI agents over remote transport.

<Note>
  **Surfaces:** How gateway-console, Registry MCP, and hosted gateway MCP differ is documented in [MCP surfaces](/reference/mcp-surfaces) (canonical system reference).
</Note>

<Note>
  **Commerce Agent (C9):** In Better Data messaging, **Commerce Agent** names the composition pattern — discover (Registry MCP) → execute (Commerce Gateway) → govern (Loop Engine) → recorded outcome; demos are reference experience only. It is **not** a standalone product. See [Commerce Agent pattern](/reference/commerce-agent-pattern).
</Note>

<Note>
  **C12 — Agent language:** Always say agents use **Registry to discover**, **Gateway to act**, **Loop Engine to govern**. Never describe agents as an autonomous AI platform, agent product, or a system separate from the gateway. [Build a governed commerce agent →](/guides/build-an-agent)
</Note>

## What It Is

Commerce Gateway (`@commercegateway/commerce-gateway`) is the agent-facing layer for product search, availability, cart, and order workflows, with capability-gated tool access.

<Note>
  Read operations are the default posture. Write-capable tool paths require explicit capability and key scope enablement.
</Note>

## Federated Architecture

AI Agent -> MCP Client -> SSE endpoint -> Commerce Gateway -> Domain backends -> Your data

Gateway discovery can be registry-assisted; gateway execution remains org-scoped.

## Getting Started

<Steps>
  <Step title="Enable gateway access">
    Enable your organization gateway and provision API key scopes.
  </Step>

  <Step title="Get your endpoint">
    Endpoint format: `https://api.betterdata.co/gateway/{orgSlug}`.
  </Step>

  <Step title="Connect your MCP client">
    Configure your client with SSE transport and your scoped API key.
  </Step>
</Steps>

## Claude MCP Configuration

```json theme={null}
{
  "mcpServers": {
    "betterdata": {
      "url": "https://api.betterdata.co/gateway/{your-org-slug}",
      "transport": "sse"
    }
  }
}
```

## Available MCP Tools

Verified from `packages/commerce-gateway/src/mcp/tools/index.ts`:

* `shop`
* `search_products`
* `get_product_details`
* `check_availability`
* `check_inventory`
* `get_recommendations`
* `add_to_cart`
* `create_order`
* `get_shipment_status`
* `get_purchase_order_status`
* `get_trace_events`
* `get_demand_forecast`

## Registry Discovery

Use registry discovery to resolve gateways before execution where applicable:

* [registry.betterdata.co](https://registry.betterdata.co)

## Security

* Authenticate with scoped API keys (`x-api-key` or gateway auth middleware path).
* Restrict high-impact scopes to trusted agents and environments.

<Warning>
  Do not provide broad write-capable keys to unattended agents without explicit policy controls and monitoring.
</Warning>

## Hosted vs self-hosted

|              | Self-hosted                                                                                                                     | Better Data hosted                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| Setup        | [gateway-console](https://github.com/betterdataco/bd-forge-main/tree/main/apps/gateway-console) (free operator UI) + your stack | No gateway infrastructure to run      |
| Multi-tenant | Single-tenant OSS default                                                                                                       | Multi-tenant org isolation            |
| Registry     | Optional ([Commerce Registry Protocol](/reference/commerce-registry-protocol))                                                  | Included in platform discovery flows  |
| Analytics    | Local / self-managed                                                                                                            | Full dashboard (hosted product)       |
| SLA          | Self-managed                                                                                                                    | Target enterprise SLA — see agreement |

**Self-hosted docs:** [commercegateway.io](https://commercegateway.io)\
**Hosted:** [gateway.betterdata.co](https://gateway.betterdata.co) · [hello@betterdata.co](mailto:hello@betterdata.co)

## Resources

* [Commerce Agent Pattern on commercegateway.io →](https://commercegateway.io/docs/getting-started/commerce-agent-pattern)