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. |
| 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. |
| Memory allocation | MB | Hosted server compute. |
| MCP session routing TTL | hours | Gateway session routing metadata. |
| Local filesystem | Ephemeral | Files created by server runtime. |
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 values scoped to production, preview, or branch overrides. |
| 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
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 build exceeds the timeout
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
Session routing expires
A client may need to initialize a new MCP session before sending follow-up
requests.
Runtime memory is exhausted
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. |
| 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. |
Related failure signals
| 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. |
Related docs
Compute model
Understand runtime constraints.
Build system
Understand build defaults and failure modes.
Gateway
Understand request and session behavior.