Gateway

The gateway is the request layer in front of deployed MCP servers. It is the part of FastMCP Gateway that receives client traffic, identifies the target and its current deployment, applies the server’s access settings, and sends the request to that deployment’s artifact.

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

Request flow

Every request follows the same broad path.

A client calls the target URL

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

FastMCP Gateway identifies the target

FastMCP Gateway uses the hostname and path to identify which target should receive the request. Target URLs are stable for a branch or production server, so repeated requests use the same URL as successful deployments, redeploys, or rollbacks change the current deployment.

FastMCP Gateway checks access

FastMCP Gateway 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.

FastMCP Gateway routes to the current deployment

FastMCP Gateway forwards the request to the artifact in the target’s current deployment. Your Python MCP or FastMCP server handles the tool, resource, or prompt call.

What the gateway controls

Endpoint routing

Maps an incoming target URL to the artifact in its current deployment.

Access enforcement

Applies server access settings before requests reach server code.

Request observability

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

Limits

Request timeouts and payload limits enforced at the gateway.

Deployment routing

Deployment targets are addressed by stable slugs. The gateway uses the slug to find the target and route requests to its current deployment. For target URL stability and how successful deployments change what is live, see Deployments. Changing source code does not change gateway routing by itself. A build and its deployment must succeed before the target selects the new artifact and the gateway routes traffic to it.

If a client is still seeing old behavior, check the Deployments page to confirm which deployment is current for its target 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 FastMCP Gateway 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 FastMCP Gateway used for its access decision.

Header	Value
`horizon-actor`	The FastMCP Gateway 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 FastMCP Gateway authentication disabled do not receive verified FastMCP Gateway 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

Hosted server requests are stateless, including requests from clients that use an MCP initialization handshake. The gateway does not issue MCP session IDs or maintain session-routing state for hosted servers. Each request can run on a different server instance. Store information needed across requests in durable external storage and use an application-defined key to retrieve it. A backend’s ctx.session_id does not guarantee access to state from an earlier request. For instance reuse and long-running work, see the compute model.

Protocol behavior

FastMCP Gateway 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.

FastMCP Gateway 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 submit long-running work to an external worker or job service 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
Run 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 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 FastMCP Gateway 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 FastMCP Gateway 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 server.

Compute model

Learn how FastMCP Gateway runs deployed MCP servers.

Build system

Learn how deployable server artifacts are created.

Authentication

Learn how callers prove identity.

Authorization

Learn how FastMCP Gateway decides what authenticated callers can do.

Limits

Review request 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

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

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