Skip to main content

​
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 (@betterdata/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:

​
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-hostedBetter Data hosted
Setupgateway-console (free operator UI) + your stackNo gateway infrastructure to run
Multi-tenantSingle-tenant OSS defaultMulti-tenant org isolation
RegistryOptional (Commerce Registry Protocol)Included in platform discovery flows
AnalyticsLocal / self-managedFull dashboard (hosted product)
SLASelf-managedTarget enterprise SLA — see agreement
Self-hosted docs: commercegateway.io
Hosted: gateway.betterdata.co · hello@betterdata.co

​
Resources