Builds

Builds package hosted Python MCP and FastMCP servers into deployable artifacts. A build belongs to one server and one source revision. Successful builds can be served as live deployments or preview deployments. For the hosted-server contract across source, builds, deployments, gateway access, and runtime behavior, start with Hosted servers. For the full lifecycle, defaults, and failure modes, see Build system.

Build contract

A build is an immutable attempt to turn one repository commit and one set of server settings into one deployable artifact. After the build starts, changing a branch, editing an environment variable, or updating server settings does not change that build. Those changes apply to the next build that uses them.

Property	Contract
Source revision	Resolved to an exact commit before build work begins.
Server configuration	Entrypoint, dependency file, build-relevant settings, and environment scope are captured at build start.
Output	A successful build produces a new artifact and manifest. A failed build does not modify the live deployment.
Mutability	Build records and artifacts are historical. Rebuild instead of editing an existing build.
Promotion	Build success makes an artifact eligible for deployment; it does not always change live traffic.

Debug build problems from the build record, not from the current branch tip. The current branch may have moved since the failed build started.

Build states

State	Meaning
`queued`	Horizon has accepted the build request and is waiting to start work.
`building`	Horizon is installing dependencies, packaging the server, inspecting the manifest, or publishing the artifact.
`succeeded`	The artifact is ready to deploy.
`failed`	The build did not produce a deployable artifact. Open build logs for the failing step.
`canceled`	The build was stopped before completion.

What starts a build

Default branch push

A push to the configured default branch can create a production build.

Pull request

A pull request can create a preview build with preview-scoped environment variables.

Manual build

A user with server edit access can start a build from the dashboard.

Configuration change

Changes to build-relevant settings, such as the entrypoint or dependency file, take effect on the next build.

What does not start a build

Not every server change produces a new artifact. Some changes affect gateway or dashboard state without rebuilding Python code.

Change	Usually requires a new build?	Why
Source code change	Yes	The artifact must include the new code.
Entrypoint or dependency file change	Yes	Horizon must package and inspect with the new build configuration.
Environment variable value change	Yes, for hosted server runtime behavior	Existing artifacts keep the values they were built with.
Server access grant change	No	Access metadata is evaluated by Horizon and can update without changing Python code.
Server display name or description	No	Dashboard metadata does not affect the artifact.
Capability policy change	Redeploy may be required for hosted capability enforcement	The deployed endpoint must use the updated policy metadata.

Build inputs

Input	Contract
Repository revision	Horizon builds from the selected commit. Builds are immutable once started.
Entrypoint	Defaults to `main.py` unless the server is configured with another entrypoint.
Dependencies	Horizon installs dependencies from the configured dependency file or discovered Python project files.
Environment variables	Production builds use production variables. Preview builds use preview variables.
Access settings	Authentication and authorization metadata are packaged with the deployment path used by the gateway.

Source resolution

Horizon records the repository, branch context, and exact commit for every hosted build. Branch names are useful for starting builds, previews, and promotion workflows, but the artifact is tied to the commit that was resolved at build start. This matters when a pull request receives several pushes quickly. Preview builds run concurrently, so an older build may finish after a newer one. Use the deployment page to confirm which artifact is selected before assuming the latest completed build is live.

Build output

A successful build produces:

A deployable artifact.
A discovered MCP manifest for tools, resources, prompts, and templates.
Build logs for audit and debugging.
Metadata that Horizon uses for deployment, routing, and observability.

Do not put required setup work behind a code path that only runs after a tool call. Horizon inspects the server during the build, so import-time and startup failures can prevent deployment.

Concurrency and ordering

Default-branch deploys to the same server run one at a time. When you push several commits in quick succession, their builds run in parallel but deploy serially, so the newest commit is the last one applied and owns live traffic. Preview builds still run concurrently across branches.

Scenario	Expected behavior
Several commits pushed to the default branch in quick succession	Each commit builds, and the deploys apply in order. The newest commit ends up live.
Two preview builds run for different branches	Previews deploy concurrently; each branch serves its own artifact.
A default-branch build succeeds while a preview build fails	The production artifact can still be healthy; preview failure is scoped to its branch context.
A build fails after a previous build succeeded	The previous successful artifact remains available for deployment or rollback.

Manifest inspection

Build inspection loads the server entrypoint and records the MCP capabilities Horizon can see. The dashboard, ChatMCP, remix composition, and capability policies depend on that manifest. Playground lists live capabilities from the selected target instead. If a capability is missing after a successful build, check whether the server registers the tool, resource, prompt, or template during import or startup. Conditional registration can make local behavior differ from build inspection, especially when it depends on environment variables.

Troubleshooting

Dependency installation fails

Check the dependency file path, Python version requirements, private package credentials, and any build-time environment variables.

The entrypoint cannot be loaded

Confirm the configured file exists in the repository revision and can be imported without running interactive code.

The manifest is empty or incomplete

Make sure tools, resources, and prompts are registered before the server is inspected. Build logs usually show whether inspection succeeded.

A new environment variable is missing

Start a new build after saving the variable. Existing artifacts keep the environment available when they were built.

A successful build did not change production traffic

Confirm whether the build was for a preview deployment, whether automatic promotion is enabled, and which artifact the live deployment currently selects.

A tool disappeared after a build

Compare the manifest on the previous successful build with the new build. Then check registration code and environment-dependent imports.

Hosted servers

Start with the hosted-server contract across source, deployments, access, runtime, and observability.

Deployments

Serve successful builds as live or preview deployments.

Environment variables

Manage production and preview environment variables.

Compute model

Understand how artifacts run after deployment.

Get Started

Platform

MCP Servers

Access

Administration

Security & Compliance

Plans & Billing

Reference

Build contract

Build states

What starts a build

Default branch push

Pull request

Manual build

Configuration change

What does not start a build

Build inputs

Source resolution

Build output

Concurrency and ordering

Manifest inspection

Troubleshooting

Hosted servers

Deployments

Environment variables

Compute model

​Build contract

​Build states

​What starts a build

Default branch push

Pull request

Manual build

Configuration change

​What does not start a build

​Build inputs

​Source resolution

​Build output

​Concurrency and ordering

​Manifest inspection

​Troubleshooting

​Related docs

Hosted servers

Deployments

Environment variables

Compute model

Build contract

Build states

What starts a build

What does not start a build

Build inputs

Source resolution

Build output

Concurrency and ordering

Manifest inspection

Troubleshooting

Related docs