Skip to main content

MCP gateway overview

Horizon's hosted gateway is the half of the product Byte8 runs. It terminates the Model Context Protocol on the Streamable HTTP transport, authenticates AI agents, and translates MCP tool calls into REST calls into your Magento store using the per-store API key.

Endpoint​

POST https://horizon.byte8.io/mcp
Content-Type: application/json
Authorization: Bearer <store-api-key>

Streamable HTTP is the modern MCP transport — single endpoint, streaming responses, no long-lived WebSocket. Most MCP clients (Claude Desktop, Anthropic SDK, agent frameworks) support it natively.

The gateway is implemented in Rust on top of rmcp (version 1.1+, with the transport-streamable-http-server feature).

Authentication​

Every MCP request must carry the store API key as a bearer token — Authorization: Bearer <key>. The key:

  • Is a per-store secret, not a per-user one.
  • Is generated by the dashboard on store creation or rotation.
  • Is shown to you exactly once — there's no "reveal" later.
  • Is encrypted at rest and never displayed again. A leak means rotate, not panic-revoke-all.

If the key is missing, malformed, or unknown, the gateway returns 401 before the MCP layer even sees the request — so a bad key never appears as a tool error, just a transport failure on the agent side.

See API keys for rotation patterns.

Per-tenant isolation​

Every tool invocation is scoped to a single store:

  1. The bearer key identifies which store is being addressed.
  2. The account that owns the store is the tenant boundary — all subsequent queries (usage logs, rate-limit check, etc.) are scoped to it.
  3. The gateway calls only the Magento at that store's base URL, forwarding the same store key as X-Horizon-Key — the header the Magento extension validates.

There's no shared catalog data between tenants — even product names with the same SKU in two merchants' stores stay completely separate.

What the gateway does on a tool call​

Walk through search_products step-by-step:

  1. MCP request lands at /mcp. The rmcp server deserialises the JSON-RPC envelope.
  2. Auth middleware reads the bearer key, looks up the store, and attaches the store context to the request.
  3. Rate-limit check — during the free trial, an exhausted monthly quota rejects the call here. On paid tiers the call proceeds and the excess is tracked.
  4. Tool dispatcher routes the call to the search_products handler.
  5. The gateway issues GET https://<base_url>/horizon/api/v1/products?... with the store-side X-Horizon-Key.
  6. Response shaping — the extension JSON is mapped to the MCP ProductSummary type with denormalised fields.
  7. Background logging — a usage row is written asynchronously (failures don't block the response).

Latency is dominated by your Magento's response time — the gateway itself adds single-digit milliseconds.

Rate limiting​

Monthly call quotas are checked per account against your plan tier:

TierBehaviour at quota
Free trial (first 14 days)Hard cap — calls are rejected until the trial converts
Starter / Pro / Agency / EnterpriseSoft cap — requests keep serving, the excess is tracked and shown in usage analytics. Automated overage billing is coming soon; until then overage is settled per your plan terms.

We never 429 a paid tier — visibility is what merchants pay for, so the gateway prefers to serve than block.

What the gateway is not​

  • ❌ A model host. The MCP gateway doesn't run a model — agents bring their own. (The on-site assistant is the exception: there Byte8 hosts the AI for you.)
  • ❌ An embeddings or vector store. Catalog search is currently full-text against the extension's flat index.
  • ❌ A cache in front of your store. Every tool call reads live from your Magento — a gateway-side response cache with webhook invalidation is coming soon.
  • ❌ A scraper. The Magento extension explicitly publishes the data; we don't crawl your site.

Next​