Gateway

The Horizon gateway is the request layer in front of deployed MCP servers. It is the part of Horizon that receives client traffic, identifies the deployment, applies the server’s access settings, preserves MCP session routing, and sends the request to the currently promoted deployment artifact.

The gateway runs before your server code. Server compute starts after the gateway has accepted and routed a request. For the Python execution contract, see Compute model.

Request flow

Every request follows the same broad path.

A client calls the deployment URL

The client sends an MCP request to a Horizon server URL. Hosted servers usually expose an endpoint ending in /mcp.

Horizon identifies the deployment

Horizon uses the hostname and path to identify which deployment should receive the request. Deployment slugs are stable for a branch or live server, so repeated requests route to the same deployment until promotion or rollback changes what is live.

Horizon checks access

Horizon applies the server’s configured authentication and authorization mode before your server receives the request. If access is denied, the request stops at the gateway.

Horizon preserves MCP session routing

For initialized MCP sessions, Horizon keeps enough routing state to send follow-up requests in the same session to the right backend path.

Horizon routes to the live artifact

Horizon forwards the request to the deployment artifact currently selected for that server. Your Python MCP or FastMCP server handles the tool, resource, or prompt call.

What the gateway controls

Endpoint routing

Maps incoming deployment URLs to the currently live deployment artifact.

Access enforcement

Applies server access settings before requests reach server code.

MCP sessions

Issues and preserves MCP session IDs for follow-up requests.

Request observability

Records request-level metadata used for logs, analytics, and debugging.

Limits

Request, session, rate, and payload limits enforced at the gateway.

Deployment routing

Deployments are addressed by deployment slugs. The gateway uses that slug to decide which deployed artifact should receive a request. For slug stability semantics and how promotion changes what is live, see Deployments. Changing source code does not change gateway routing by itself. A new build must succeed, and the resulting artifact must be promoted, before the gateway routes traffic to the new version.

If a client is still seeing old behavior, check the deployment page to confirm which artifact is currently live before debugging server code.

Access checks

The gateway enforces the server’s configured access mode before forwarding the request. Authentication and authorization decisions happen at the gateway, before your server code runs. Your server can still implement its own application-level checks, but gateway access settings determine whether the request reaches your server at all. When the gateway authenticates a caller, it attaches the verified caller identity to the request so your server code and downstream access-aware features can make their own authorization decisions against the same identity. For access mode options and how caller identity is verified, see Authentication and Authorization.

Actor context

When Horizon authentication succeeds, the gateway removes any client-supplied horizon-* identity headers and adds trusted actor context before invoking a hosted server. Server code can use this context for application behavior that needs the same identity Horizon used for its access decision.

Header	Value
`horizon-actor`	The Horizon ID of the authenticated user or service account.
`horizon-actor-type`	`user` or `service_account`.
`horizon-actor-email`	The user’s email address when the actor has one.
`horizon-user-role`	The actor’s organization role.
`horizon-server-roles`	The actor’s resolved server roles as a comma-separated set.

A request can resolve more than one server role through explicit and Team grants, so use horizon-server-roles for authorization-aware application code. Requests to a hosted server with Horizon authentication disabled do not receive verified Horizon actor context. FastMCP exposes these headers from the active request through get_http_headers():

from fastmcp import FastMCP
from fastmcp.server.dependencies import get_http_headers

mcp = FastMCP("Identity-aware server")


@mcp.tool
def current_actor() -> dict[str, str | None]:
    headers = get_http_headers()
    return {
        "id": headers.get("horizon-actor"),
        "type": headers.get("horizon-actor-type"),
        "email": headers.get("horizon-actor-email"),
        "organization_role": headers.get("horizon-user-role"),
        "server_roles": headers.get("horizon-server-roles"),
    }


if __name__ == "__main__":
    mcp.run()

Keep server and capability access at the gateway. Use actor context inside server code for application-specific rules and upstream attribution.

MCP sessions

When a client initializes a session, Horizon returns an mcp-session-id. Clients should send that header on all follow-up requests in the same session. Clients on MCP protocol versions that have no session handshake do not receive the header, and each of their requests stands on its own. Session routing state is retained for hours. This is routing state for MCP traffic, not durable application storage. Store durable application state outside the local filesystem. For session and other product limits, see Limits.

Protocol behavior

Horizon hosted servers use Streamable HTTP as the MCP transport. Clients send MCP requests as HTTP POST requests to the deployment URL.

Operation	Supported	Gateway behavior
`POST /mcp`	Yes	Forwarded to your server.
Long-lived `GET /mcp` SSE stream	No	Returns method-not-allowed without invoking your server.
`DELETE /mcp` session teardown	No	Returns method-not-allowed without invoking your server.

Horizon does not support long-lived GET /mcp server-sent event streams for hosted servers. Use the standard POST-based request flow for MCP calls, and return a job ID quickly for long-running work instead of holding the request open.

Gateway vs compute

The gateway is responsible for getting the request to the right deployed server. Server compute is responsible for running your Python MCP or FastMCP code.

Concern	Gateway	Server compute
Identify deployment	Yes	No
Enforce server access mode	Yes	No
Preserve MCP session routing	Issues and routes by `mcp-session-id` for clients that initialize a session	Receives routed requests and returns MCP headers
Run Python server code	No	Yes
Capture stdout and stderr	No	Yes
Enforce request timeout	Returns an error to the client if the deadline is exceeded	Terminates the Python handler if the deadline is exceeded

Common gateway outcomes

The request is unauthorized

The caller did not provide credentials accepted by the server’s access mode, or the credentials were expired or malformed.

The request is forbidden

The caller is authenticated, but Horizon access settings do not allow that caller to use the server or requested capability.

The deployment is not found

The URL does not map to a known deployment, the deployment was removed, or a custom domain is not pointing at the expected server.

The method is not supported

The client attempted a transport operation Horizon does not support for hosted servers, such as a long-lived GET /mcp stream or DELETE /mcp.

The request reaches the server but fails

Gateway routing succeeded. Check your server logs and the Compute model for errors from your Python server.

Compute model

Learn how Horizon runs deployed Python servers.

Build system

Learn how deployable server artifacts are created.

Authentication

Learn how callers prove identity.

Authorization

Learn how Horizon decides what authenticated callers can do.

Limits

Review request, session, and compute limits.

Get Started

Platform

MCP Servers

Access

Administration

Security & Compliance

Plans & Billing

Reference

Request flow

What the gateway controls

Endpoint routing

Access enforcement

MCP sessions

Request observability

Limits

Deployment routing

Access checks

Actor context

MCP sessions

Protocol behavior

Gateway vs compute

Common gateway outcomes

Compute model

Build system

Authentication

Authorization

Limits

​Request flow

​What the gateway controls

Endpoint routing

Access enforcement

MCP sessions

Request observability

Limits

​Deployment routing

​Access checks

​Actor context

​MCP sessions

​Protocol behavior

​Gateway vs compute

​Common gateway outcomes

​Related docs

Compute model

Build system

Authentication

Authorization

Limits

Request flow

What the gateway controls

Deployment routing

Access checks

Actor context

MCP sessions

Protocol behavior

Gateway vs compute

Common gateway outcomes

Related docs