Skip to main content

​
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-consoleregistry-mcp-serverhosted-gateway-mcp
RoleBrowser operator UI for a self-hosted gatewayHTTP MCP server for registry discovery (@commercegateway/registry-mcp)Node MCP-style HTTP for hosted commerce tools (multi-tenant intent)
Primary userOperator configuring their own gatewayRemote MCP clients (e.g. Grok) resolving merchants via registryHosted tenants / internal stack (gated tools)
StackNot found under apps/ in bd-forge-main. Implementation detail pending verification — may live in Commerce Gateway OSS repos or legacy paths. Do not assume port 3012 here; 3012 is hosted-loops (pnpm dev in apps/hosted-loops).Next.js; pnpm dev → port 3015; MCP entry POST /mcp (apps/registry-mcp-server/app/mcp/route.ts)Plain Node http server (default PORT 8081); apps/hosted-gateway-mcp/src/index.ts
Core packagecommerce-gateway, commerce-gateway-mcp, registry-mcp (for UI/config) — surface location pending verification above@commercegateway/registry-mcp + MCP SDK@commercegateway/commerce-gateway (/mcp tool defs + capabilities)
@repo/databaseImplementation detail pending verificationYes — when DATABASE_URL is set, Bearer MCP keys resolve via gatewayApiKey lookup (apps/registry-mcp-server/lib/register-mcp-api-key-resolver.ts; see apps/registry-mcp-server/DEPLOY.md)No — no Prisma/database import in hosted-gateway-mcp today
OSS vs proprietaryOSS-style operator story (verify repo)App is monorepo-only; uses OSS registry-mcpProprietary 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 (e.g. mcp.commercegateway.io): JSON-RPC over streamable HTTP for discovery tools (registry protocol). Deploy notes: apps/registry-mcp-server/DEPLOY.md in the monorepo.
  • hosted-gateway-mcp — HTTP service exposing commerce MCP tool definitions gated by CapabilitySet from @commercegateway/commerce-gateway. Verified routes in apps/hosted-gateway-mcp/src/index.ts: GET / (HTML summary), GET /health (JSON), GET /tools/list?org= — requires Authorization: Bearer demo-key or x-api-key: demo-key for demo org (org_demo), or org slug fallback path as implemented in source. 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 control plane.

​
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 control planes, not operator surfaces, 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).