Limits

Limits define the contract for hosted server builds, gateway requests, compute, sessions, and configuration. Some limits protect the interactive MCP request path; others keep deployments predictable and safe to operate.

Limit contract

Limits define what Horizon will attempt to serve, not what every MCP client or upstream system can handle. Design server behavior so clients receive clear errors before a limit becomes a surprise.

Limit type	Design response
Request timeout	Return quickly, stream only where supported, or return a job ID and continue work asynchronously.
Request and response size	Keep tool inputs and outputs small; move large files to external storage and pass a reference instead of inlining bytes.
Memory allocation	Process data in chunks and avoid unbounded in-memory caches.
Build timeout	Keep dependency installation and import-time work lightweight.
Session TTL	Let clients reinitialize sessions and avoid storing durable state in session routing.
Ephemeral filesystem	Store durable files outside the local runtime filesystem.

Runtime limits

Limit	Value	Applies to
Request timeout	seconds	MCP request handlers served through Horizon.
Request and response size	MB each	MCP requests and responses through the gateway.
Memory allocation	MB	Hosted server compute.
MCP session routing TTL	hours	Gateway session routing metadata.
Local filesystem	Ephemeral	Files created by server runtime.

The MB request and response size is a hard ceiling, not a target. It comes from AWS Lambda’s synchronous invocation limit, and JSON and base64 encoding overhead lowers the usable size further, so keep tool inputs and outputs well under MB. There is no streaming; to move a large file, upload it to external object storage out of band and pass a URL or reference through the tool call.

Build limits

Limit	Value
Build timeout	15 minutes
Default Python version	`3.12`
Default entrypoint	`main.py`
Dependency discovery	Configured dependency file, nearest `requirements.txt`, or `pyproject.toml`

Configuration limits

Area	Guidance
Environment variables	Keep keys stable and use separate values for production and preview.
Slugs	Treat server and deployment slugs as client-facing identifiers. Avoid unnecessary renames.
API keys	Create separate keys per integration and rotate them when exposed.
Capability policies	Prefer small, auditable policy changes over broad access exceptions.

Organization-specific quotas, included usage, and contract terms can vary by plan.

What happens at a limit

A request exceeds the timeout

Horizon returns an error to the client and the handler should be treated as failed. Return a job ID quickly and continue long work asynchronously.

A request or response exceeds the size limit

Each MCP request and response is served as a single synchronous AWS Lambda invocation, which caps the payload at MB with no streaming. JSON and base64 encoding overhead lowers the usable size further, so keep tool inputs and outputs comfortably under this ceiling. To move a large file, upload it to external object storage out of band, then pass a URL or reference through the tool call and have your server read from that storage.

A build exceeds the timeout

The build fails and no new deployable artifact is produced. The previous deployment remains available unless you change it separately.

Session routing expires

A client may need to initialize a new MCP session before sending follow-up requests.

Runtime memory is exhausted

The server instance can fail or restart. Reduce memory use, stream work in smaller chunks, or move large jobs out of the request path.

Designing within limits

Workload	Recommended shape
Fast read or lookup	Regular MCP tool handler.
Large export	Return a job ID quickly and continue the work asynchronously.
Large file transfer	Upload to external object storage out of band and pass a URL or reference through the tool call.
Repeated polling	Store polling state durably and expose a status tool or resource.
Expensive startup	Lazy-initialize clients and caches after import when possible.
Large temporary files	Use durable external storage rather than assuming local files persist.

Signal	Check
408 or timeout in request logs	Handler duration and upstream calls.
Missing server logs	Gateway rejected the request before compute or deployment was unavailable.
Build timeout	Dependency install time and import-time work.
Session not found	Client reinitialization and session TTL behavior.
File missing	Ephemeral filesystem assumptions.

Compute model

Understand runtime constraints.

Build system

Understand build defaults and failure modes.

Gateway

Understand request and session behavior.

Get Started

Platform

MCP Servers

Access

Administration

Security & Compliance

Plans & Billing

Reference

Limit contract

Runtime limits

Build limits

Configuration limits

What happens at a limit

Designing within limits

Compute model

Build system

Gateway

​Limit contract

​Runtime limits

​Build limits

​Configuration limits

​What happens at a limit

​Designing within limits

​Related failure signals

​Related docs

Compute model

Build system

Gateway

Limit contract

Runtime limits

Build limits

Configuration limits

What happens at a limit

Designing within limits

Related failure signals

Related docs