> ## Documentation Index
> Fetch the complete documentation index at: https://docs.horizon.prefect.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Compute model

> How Horizon runs deployed Python MCP and FastMCP servers.

export const memoryAllocation = 1024;

export const sessionTTL = 24;

export const requestTimeout = 170;

When you deploy a hosted server, Horizon packages your Python MCP or FastMCP
server and makes it available at a deployment URL. The compute model describes
what happens when MCP clients call that URL: how Horizon starts your server,
handles requests, records logs and metrics, and preserves enough session routing
state for clients to continue a conversation.

<Info>
  The compute model is separate from build behavior. For entrypoint detection,
  Python version selection, dependency installation, and server inspection, see
  [Build system](/platform/build-system). For the request layer in front of
  deployed servers, see [Gateway](/gateway).
</Info>

## Execution contract

Horizon runs hosted servers as Python HTTP MCP servers. Your server entrypoint
is started with FastMCP, bound to an internal HTTP port, and exposed through the
Horizon MCP endpoint for that deployment.

<CardGroup cols={2}>
  <Card title="Python server" icon="python" iconType="brands">
    Horizon runs the Python entrypoint produced by the build system.
  </Card>

  <Card title="HTTP MCP endpoint" icon="route">
    MCP clients connect to the deployment URL, usually ending in `/mcp`.
  </Card>

  <Card title="Request window" icon="timer">
    Hosted server requests have a {requestTimeout}-second timeout.
  </Card>

  <Card title="Memory allocation" icon="memory">
    Hosted servers currently run with {memoryAllocation} MB of memory.
  </Card>

  <Card title="Ephemeral filesystem" icon="hard-drive">
    Local files are not durable across compute instances or redeploys.
  </Card>
</CardGroup>

## Where compute fits

The compute layer is one part of the hosted server lifecycle. This separation
matters when you are debugging: locate which layer a failure came from, then look
at the failures typical of that layer.

| Layer          | Responsibility                                         | Typical failures                                                             |
| -------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
| Build          | Creates deployable artifacts.                          | Dependency installation, entrypoint loading, or server inspection.           |
| Gateway        | Receives MCP traffic.                                  | Routing, access, or unsupported transport methods.                           |
| Server compute | Runs the Python code that handles supported MCP calls. | Python startup, request handlers, memory use, timeouts, or application logs. |

## From artifact to serving

<Steps>
  <Step title="A build artifact is selected">
    A successful build produces a deployable artifact. Horizon serves traffic
    from the artifact selected by the deployment, such as the current live
    deployment or a preview deployment.
  </Step>

  <Step title="Server compute starts on demand">
    Horizon starts server compute when traffic needs to be served. The first
    request to a fresh instance can take longer because Python, dependencies,
    and your server module need to load.
  </Step>

  <Step title="Your server listens for HTTP MCP traffic">
    Horizon starts your FastMCP server over HTTP. MCP clients continue to call
    the Horizon deployment URL; the gateway forwards supported requests to the
    running server.
  </Step>

  <Step title="Your code handles the MCP call">
    Tool, resource, and prompt handlers run in your Python process. Code that
    executes at import time may run during startup, before an individual MCP
    request handler is called.
  </Step>

  <Step title="Horizon records compute data">
    Horizon captures request outcomes, server logs, session activity, duration,
    memory usage, and cold-start metrics so you can debug deployed behavior.
  </Step>
</Steps>

## What runs in compute

The Python version, installed dependencies, source files, and entrypoint come
from the build artifact. Horizon does not reinstall dependencies when a request
arrives.

To change the Python version, dependencies, entrypoint, or packaged source,
update the repository or server settings and create a new build. The deployed
server changes only after a successful build artifact is promoted.

## Environment variables

Deployment environment variables are available to the running server. Treat
environment variables as configuration for startup and request handling.

Changing environment variables requires a new deployment before the running
server sees the new values. Avoid printing secrets to stdout or stderr; those
streams become server logs.

## Request window and long-running work

Hosted server requests time out after {requestTimeout} seconds. This limit applies to the
request from the MCP client through Horizon to your deployed server.

Use request handlers for work that can complete within that window. For longer
or retryable work, return a job ID quickly and continue the work asynchronously
instead of keeping the MCP request open.

### Choose the right execution path

| Use this                                | For                                                                                        | Avoid using it for                                                                        |
| --------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| MCP request handler                     | Interactive tool, resource, or prompt work that can finish within {requestTimeout} seconds | Long-running jobs, polling loops, or work that needs retries after the client disconnects |
| Asynchronous job with a returned handle | Longer, retryable, or asynchronous work that should continue outside the MCP request       | Work that must return an immediate MCP response body                                      |

<Warning>
  Horizon does not support long-lived `GET /mcp` streams for hosted servers.
  Use the standard HTTP request flow for MCP calls, and move long-running work
  out of the request path.
</Warning>

## Sessions and local state

Horizon manages MCP session routing for deployed servers. When a client
initializes a session, Horizon returns an MCP session ID and uses it to route
later requests in that session. Clients on MCP protocol versions that have no
session handshake do not receive a session ID.

Session routing state is retained for {sessionTTL} hours. Clients should send the
`mcp-session-id` header on follow-up requests when their MCP client supports it.

<Note>
  Session routing helps Horizon keep related MCP requests together. It is not a
  durable application database or a guarantee that every request in a session
  reaches the same Python process. Store durable application state outside the
  local filesystem.
</Note>

## Instances and reuse

Horizon starts server compute as needed to serve traffic. A request may be
handled by a fresh Python process or by one that is already running.

| Behavior              | What it means                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| Fresh instance        | Python, dependencies, and your server module need to load before the request handler runs.       |
| Warm instance         | The Python process is already loaded, so module-level clients or caches may still exist.         |
| No affinity guarantee | A later request may be handled by a different instance, even for the same deployed server.       |
| Ephemeral state       | Memory and local files can disappear at any time and should not store durable application state. |

You can cache reusable clients in memory when that is safe, but in-memory state
is opportunistic. Treat it as a performance optimization, not a source of truth.

## Filesystem

The deployed artifact contains your source code and installed dependencies. You
can use temporary local files while handling a request, but the local filesystem
is ephemeral and should not be used for durable application state.

Do not rely on files written during one request being available to another
request. Do not rely on files written before a redeploy being available after
the redeploy.

## Cold starts and startup work

Horizon can start server compute on demand. The first request to a new instance
may take longer than later requests because Python, dependencies, and your
server module need to load.

Keep import-time work small:

* avoid network calls during module import
* lazy-load large clients or models when possible
* move expensive setup into request handlers or asynchronous work
* cache reusable clients in module-level variables when that is safe

## Defaults and limits

| Setting                 | Default or limit         |
| ----------------------- | ------------------------ |
| Server language         | Python MCP or FastMCP    |
| MCP transport           | HTTP                     |
| Request timeout         | {requestTimeout} seconds |
| Memory allocation       | {memoryAllocation} MB    |
| MCP session routing TTL | {sessionTTL} hours       |
| Local filesystem        | Ephemeral                |
| Server logs             | Stdout and stderr        |

For a broader list of product limits, see [Limits](/limits).

## Common compute failures

<AccordionGroup>
  <Accordion title="Requests time out">
    The handler took longer than {requestTimeout} seconds, or startup work consumed too much
    of the request window. Move long work out of the request path, reduce
    import-time work, or split the operation into smaller calls.
  </Accordion>

  <Accordion title="The first request is slow">
    A fresh compute instance may need to start Python, import dependencies, and
    load your server module. Keep module imports lightweight and defer expensive
    setup until it is needed.
  </Accordion>

  <Accordion title="A file disappeared">
    Local files are temporary. Use local files only as scratch space, and store
    durable state outside the local filesystem.
  </Accordion>

  <Accordion title="The server runs out of memory">
    Reduce per-request memory use, avoid loading large objects at import time,
    stream or page large results when possible, and check memory metrics in the
    server overview.
  </Accordion>

  <Accordion title="A new setting did not take effect">
    Build inputs and deployment environment variables take effect after a new
    successful build and deployment. Check which deployment artifact is live.
  </Accordion>

  <Accordion title="Logs contain sensitive values">
    Stdout and stderr are captured as server logs. Avoid printing secrets,
    tokens, credentials, or full environment dumps.
  </Accordion>
</AccordionGroup>

## Related docs

<CardGroup cols={2}>
  <Card title="Gateway" icon="route" href="/gateway">
    Understand the request layer in front of deployed servers.
  </Card>

  <Card title="Build system" icon="hammer" href="/platform/build-system">
    Learn how Horizon creates the artifact that compute runs.
  </Card>

  <Card title="Deployments" icon="cloud-arrow-up" href="/deployments">
    Learn how successful build artifacts are promoted and rolled back.
  </Card>

  <Card title="Environment variables" icon="lock" href="/environment-variables">
    Configure values available to builds and deployed servers.
  </Card>

  <Card title="Limits" icon="gauge" href="/limits">
    Review compute and product limits.
  </Card>
</CardGroup>