Better Data

Reference

MCP surfaces

Edit this page

MCP surfaces

Compact comparison of gateway-console, registry-mcp-server (Registry MCP), and hosted-gateway-mcp. These surfaces slot into the Infrastructure and Protocol layers of the canonical five-layer model — see Core Concepts — Layered ecosystem. For the broader four-layer product map, see Platform architecture.

This page is the canonical reference for MCP-related surfaces. Tool-by-tool listings live under MCP Tool Reference.

At a glance

| | gateway-console | registry-mcp-server | hosted-gateway-mcp | | --- | --- | --- | --- | | Role | Browser operator UI for a self-hosted gateway | HTTP MCP server for registry discovery (@commercegateway/registry-mcp) | Node MCP-style HTTP for hosted commerce tools (multi-tenant intent) | | Primary user | Operator configuring their own gateway | Remote MCP clients (e.g. Grok) resolving merchants via registry | Hosted tenants / internal stack (gated tools) | | Stack | Not found under apps/ in the primary platform tree. Verify repo/layout per release — do not assume port 3012 here; 3012 is hosted-loops local dev. | Next.js; pnpm dev → port 3015; MCP entry POST /mcp | Plain Node http server (default PORT 8081) | | Core package | commerce-gateway, commerce-gateway-mcp, registry-mcp (for UI/config) — surface location may vary by repo | @commercegateway/registry-mcp + MCP SDK | @commercegateway/commerce-gateway (/mcp tool defs + capabilities) | | @repo/database | Varies by packaging | Yes — when DATABASE_URL is set, Bearer MCP keys can resolve via org/key lookup (see registry-mcp-server deploy notes) | No — no Prisma/database import in hosted-gateway-mcp today | | OSS vs proprietary | OSS-style operator story (verify repo) | App is monorepo-only; uses OSS registry-mcp | Proprietary skeleton |

One line each

  • gateway-console — A dashboard: providers, connectors, keys, status, registry link, telemetry preview; writes local gateway.config.json. It is not an MCP endpoint.
  • registry-mcp-server — The deployed Registry MCP: JSON-RPC over streamable HTTP for discovery tools (registry protocol). Do not use legacy Registry MCP hostnames retired per Decision 7 (see Surface contract (C8) and Commerce Registry Protocol). The public URL is per deployment via REGISTRY_URL and deploy notes (e.g. apps/registry-mcp-server/DEPLOY.md in the monorepo). Tenant commerce tool execution uses Commerce Gateway Cloud at canonical path /api/mcp, not deprecated MCP ingress.
  • hosted-gateway-mcp — HTTP service exposing commerce MCP tool definitions gated by CapabilitySet from @commercegateway/commerce-gateway. Documented routes: GET / (HTML summary), GET /health (JSON), GET /tools/list?org= — demo auth via Authorization: Bearer demo-key or x-api-key: demo-key for the demo org, or org slug fallback as implemented. Not registry discovery.

Relationship to packages

  • @commercegateway/registry-mcp — Library used by registry-mcp-server (and by gateway-console for registry-related UI).
  • @commercegateway/commerce-gateway (including /mcp exports) — What hosted-gateway-mcp uses for commerce execution tools, not registry discovery.

Where these surfaces appear

Product

  • Better Data SCM (/welcome and workspace modules): operators use Gateway and Commerce Registry in-product; Remote MCP URLs and protocol docs are after workspace setup, not a separate external product signup.
  • Gateway Console (self-host story) is documented as a developer/operator path alongside hosted gateway flows — same module narrative, not a competing administration stack.

OSS

  • @commercegateway/registry-mcp — npm package; discovery tools for @shop resolution. See the package README in the repo.
  • @commercegateway/commerce-gateway — MCP tool execution surface for commerce backends.
  • Monorepo apps gateway-console, registry-mcp-server, hosted-gateway-mcp map to the three columns in At a glance.

Web

  • Marketing and product pages on betterdata.co link here as the system reference for “which MCP surface is which.”
  • Developer Accelerators (Gateway Demo / Commerce Demo) are reference experiences only — not MCP endpoints; see Commerce Gateway integration and introduction.

Messaging alignment

  • Commerce Registry is native to the platform. Do not frame it as a separate external “registration product” that users must sign up for outside Better Data. Protocol docs and Remote MCP URLs are after in-product setup and configuration.
  • Demos — reference experiences and developer accelerators. They are not live administration consoles and not standalone products.

Commerce Agent pattern (canonical)

Commerce Agent is not a module or product — it is the composition pattern that ties MCP surfaces together: discover (Registry MCP) → execute (Commerce Gateway) → govern (Loop Engine) → recorded outcome / state; reference Gateway Demo / Commerce Demo illustrate the stack for humans only.

Full definition, diagram, and rules: Commerce Agent pattern (C9).