> ## 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.

# Hosted platform apps

> Explainer for hosted-gateway-mcp, registry-mcp-server, hosted-loops, and registry-loop — roles, stacks, and how they connect.

# Hosted platform apps

These four **`apps/`** services are **proprietary, monorepo-hosted** surfaces in the Better Data stack. They sit next to — but are not the same as — the OSS packages published from **Commerce Gateway** and **Loop Engine**.

<Note>
  For **gateway-console** and a focused comparison of **Registry MCP** vs **hosted commerce MCP**, see **[MCP surfaces](/reference/mcp-surfaces)** first. This page adds the **Loop Engine** pair (**hosted-loops**, **registry-loop**) and places all four on one map.
</Note>

## At a glance

|                     | **hosted-gateway-mcp**                                                                   | **registry-mcp-server**                                                                     | **hosted-loops**                                                                                  | **registry-loop**                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Role**            | Multi-tenant MCP HTTP endpoint for **commerce tool execution** (gated by capability set) | Deployed **Registry MCP** — discovery tools (`@shop`, merchants, GTIN) over streamable HTTP | **Hosted Loop Engine** — owns the loops database; loop instances, transitions, events, JWT API    | **Loop Registry** — catalogs **published** loop definitions and **versioned** manifests (integrity, stability) |
| **Protocol plane**  | Commerce **execution** (MCP)                                                             | Registry **discovery** (MCP)                                                                | Loop **runtime** (HTTP + DB)                                                                      | Loop **catalog** (HTTP + DB)                                                                                   |
| **Typical caller**  | Hosted tenants / agents with org-scoped keys                                             | Remote MCP clients (IDEs, hosted AI) calling the public registry MCP URL                    | SCM, admin, and internal services emitting or advancing loops                                     | Runtimes and tooling resolving **which** definition version to run                                             |
| **Local dev stack** | Node `http` server; default `PORT` **8081**                                              | Next.js; **`pnpm dev` → port 3015**, `POST /mcp`                                            | Next.js; port **3012** (`apps/hosted-loops/package.json`)                                         | Next.js; port **3011** (`apps/registry-loop/package.json`)                                                     |
| **Core packages**   | `@commercegateway/commerce-gateway` (`/mcp`, `/capabilities`)                            | `@commercegateway/registry-mcp` + MCP SDK                                                   | `@loop-engine/*`, `@betterdata/database-loops`, `@loop-engine/events`, `@loop-engine/definitions` | `@loop-engine/core`, Prisma (MySQL catalog)                                                                    |

## One line each

* **`hosted-gateway-mcp`** — Serves **tenant-scoped** commerce MCP tools built from `@commercegateway/commerce-gateway`; org resolution and tooling are still **evolving** (e.g. `demo-key` stub paths in source). **Not** registry discovery.

* **`registry-mcp-server`** — The **hosted Registry MCP** app: same **discovery** story as the OSS **`@commercegateway/registry-mcp`** package, delivered as a deployable Next.js route. Operators wire **`REGISTRY_URL`** / keys per deploy notes (e.g. `apps/registry-mcp-server/DEPLOY.md` in the monorepo).

* **`hosted-loops`** — The **service boundary** for governed workflows: **starts**, **transitions**, **cancellations**, and **audit-loop events** for tenant workloads; external callers use **signed JWTs** and must not write the loops DB except through this API. Aligns with **[Hosted Loop Engine](/hosted/loops)** and [Loops](/platform/loops) product narrative.

* **`registry-loop`** — **Catalog only**: stores loop IDs, **semver-style** versions, JSON definitions, manifests, and integrity metadata (see `registry_loops` / `registry_loop_versions` in Prisma). Consumed when a runtime needs a **pinned, published** definition — distinct from **executing** an instance in **hosted-loops**.

## How the four fit together

```text theme={null}
registry-mcp-server          hosted-gateway-mcp
   (discover @shop)    →        (execute commerce tools)
         │                              │
         └──────── Commerce Agent / SCM / agents ────────┘
                                │
                    registry-loop          hosted-loops
              (published definitions)   (running instances + audit)
```

* **Discovery vs execution (MCP):** **registry-mcp-server** answers “**which** gateway / merchant?”; **hosted-gateway-mcp** answers “**run** the tool session for **this** tenant.” Same split as in [MCP surfaces](/reference/mcp-surfaces#relationship-to-packages).

* **Catalog vs runtime (loops):** **registry-loop** is the **definition store** (what shipped, which version, integrity). **hosted-loops** is the **runtime plane** (state, guards, evidence, events). Product-level context: [Loops](/platform/loops).

## HTTP surface (hosted-gateway-mcp)

From **`apps/hosted-gateway-mcp/src/index.ts`** (monorepo truth):

| Method / path          | Purpose                                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /`                | Minimal HTML landing (links `/health`, documents `/tools/list`)                                                                               |
| `GET /health`          | JSON **`{ "status": "ok" }`**                                                                                                                 |
| `GET /tools/list?org=` | Tool list filtered by **`getMCPToolDefinitions`**; auth via **`Bearer demo-key`** / **`x-api-key: demo-key`** or org slug branch (see source) |

**Implementation detail pending verification:** mapping from **`demo-key`** to production org resolution / non-demo keys.

## Monorepo paths

| App                   | Path (bd-forge-main)        |
| --------------------- | --------------------------- |
| `hosted-gateway-mcp`  | `apps/hosted-gateway-mcp/`  |
| `registry-mcp-server` | `apps/registry-mcp-server/` |
| `hosted-loops`        | `apps/hosted-loops/`        |
| `registry-loop`       | `apps/registry-loop/`       |

## Related

* [SCM workspace (apps/scm)](/reference/scm-workspace-app) — tenant CCO app; SCM vs DCM split and billing
* [MCP surfaces](/reference/mcp-surfaces) — gateway-console, Registry MCP, hosted gateway MCP (canonical MCP comparison)
* [Commerce Agent pattern (C9)](/reference/commerce-agent-pattern) — discover → execute → govern
* [Loops](/platform/loops) — governed workflows and hosted runtime overview
* [MCP Tool Reference](/integrations/mcp-reference)