Commerce gateway

Commerce Gateway

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

Surfaces: How gateway-console, Registry MCP, and hosted gateway MCP differ is documented in MCP surfaces (canonical system reference).

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.

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 →

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.

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

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

1. Enable gateway access

   Enable your organization gateway and provision API key scopes.

2. Get your endpoint

   Endpoint format: https://api.betterdata.co/gateway/{orgSlug}.

3. Connect your MCP client

   Configure your client with SSE transport and your scoped API key.

Claude MCP Configuration

{
  "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

Security

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

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

Hosted vs self-hosted

	Self-hosted	Better Data hosted
Setup	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)	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
Hosted: gateway.betterdata.co · [e-mail]

Resources

• Commerce Agent Pattern on commercegateway.io →