/mcp, and
Horizon routes that request to the artifact selected by the relevant deployment.
Production traffic uses the stable server URL. Pull requests and non-default
branches can use preview deployment URLs so you can test changes before they
become production.
For the build step before deployment, see Build system.
For request routing after deployment, see Gateway.
Open a server in Horizon, then select Deployments in the server sidebar.
The page shows the stable MCP URL, current status, recent build activity, and
a history of builds and deployments for that server.
Deployment model
Production URL
The server’s stable MCP URL always points clients at the artifact currently
selected for production.
Preview URL
A pull request or branch build can expose an isolated preview URL for
testing that branch’s artifact.
Build record
Every deployment is tied to the build, commit SHA, branch, and pull request
metadata that produced it.
Promotion
Promotion changes which default-branch deployment receives production
traffic without asking clients to change URLs.
What starts a deployment
A deployment starts after Horizon has a build request and a deployment target. The target determines whether the result is production-ready or preview-only.Default branch push
A push to the server’s default branch creates a production build. If
auto-promotion is enabled and the build succeeds, Horizon selects the new
deployment for the stable production URL.
Pull request update
A pull request toward the default branch creates a preview build and preview
deployment URL. The preview uses preview-scoped environment variables and
can be tested without changing production traffic.
Manual redeploy
From a build row, you can start a new build from that row’s commit. Use
this when current server settings, environment variables, access policy, or
deployment metadata need to be applied to that commit again.
A successful build does not always mean production traffic changed. Preview
builds stay preview. Default-branch builds can also remain ready-but-not-live
when auto-promotion is disabled or when a newer deployment has already been
selected.
Production and preview URLs
Production clients should use the stable server URL shown at the top of the Deployments page. That URL is based on the server name and remains the client configuration target through future promotions and rollbacks. Preview deployments use branch-scoped URLs. Horizon derives a deployment slug from the server name and branch name, lowercases it, replaces unsupported characters with hyphens, and truncates long values to fit URL and runtime naming limits. Pushes to the same preview branch reuse the branch deployment slug, so the preview URL can stay stable while its selected artifact changes.| URL type | Typical use | What changes |
|---|---|---|
| Stable production URL | Client, automation, and production traffic | The selected production artifact changes on promotion or rollback. |
| Preview deployment URL | Pull request review and branch testing | The preview artifact changes when that branch receives a new successful deployment. |
| Custom domain | Client-facing hostname owned by your organization | It routes to the same Horizon-served endpoint as the default URL. |
Status labels
The Deployments page combines build and deployment state into labels that are meant to answer one question quickly: what is this row doing for traffic?| Label | Meaning |
|---|---|
Production | This successful default-branch deployment is selected for the stable production URL. |
Preview | This successful non-default branch or pull request deployment has a preview URL and is not production. |
Ready | This successful default-branch deployment can be promoted, but it is not currently production. |
Building | The build is queued or running. The selected production artifact has not changed yet. |
Failed | The build did not produce a deployable artifact. Existing live traffic remains on the previously selected artifact, if one exists. |
Livemeans the server has a live production deployment.Buildingmeans at least one build is queued or running.Failedmeans the latest build failed.No deploymentsmeans Horizon has not created a deployment for the server yet.
Auto-promotion
Hosted servers have an Auto-promote Deployments setting. When it is enabled, successful default-branch deployments become production automatically. Horizon demotes the previous production deployment for the same server and points the stable URL at the new successful artifact. When auto-promotion is disabled, successful default-branch builds appear asReady. Review the commit, build logs, server logs, and preview behavior, then
promote the deployment manually when it should receive production traffic.
Repeat deployments and rollback
Starting another deployment from a commit and rolling back production create different operational outcomes.Create another deployment from a commit
Create another deployment from a commit
Use a build row’s action menu to create a new build and deployment from
that row’s commit. The new build captures current server settings that
affect deployment, such as entrypoint, dependency file, environment values,
authentication mode, and capability policy metadata.
Roll back production
Roll back production
To roll back, find an earlier successful default-branch deployment and
promote it to live. The stable production URL stays the same, but Horizon
selects the earlier artifact behind it.
Keep preview separate
Keep preview separate
Promoting to production is only available for successful default-branch
deployments. Preview deployments are for branch testing and do not become
production directly.
What changes when
Deployment behavior depends on which boundary owns the change.| Change | What to do | When clients see it |
|---|---|---|
| Source code changes | Create a new build from the changed commit. | After the resulting deployment is selected for the URL the client uses. |
| Environment variables change | Create a new build for the relevant environment. | After a new deployment uses the updated values. |
| Entrypoint or dependency file changes | Create a new build or wait for the next build trigger. | After a successful deployment built with the new settings is selected. |
| Authentication mode changes | Create a new deployment for the hosted server. | After a deployment uses the updated setting. |
| Server grants or default role changes | Save the access change. | After Horizon updates live access metadata. A code build is not required. |
| Capability policy changes | Save the policy, then redeploy. | After the deployed endpoint uses the updated policy metadata. |
| Custom domain changes | Complete domain setup or migration. | After DNS, activation, and client configuration all point to the intended endpoint. |
Debug deployment behavior
Start from the row that matches the commit and URL you are testing. The Deployments page gives each row actions for build logs, server logs, copying the deployment URL, redeploying, and promoting when promotion is available.A build succeeded but production did not change
A build succeeded but production did not change
Check whether the row is labeled
Preview, Ready, or Production.
Preview deployments do not change production. Ready deployments need manual
promotion when auto-promotion is disabled.A client still sees old tools
A client still sees old tools
Confirm the production row has the expected commit and manifest. Then
reconnect the client or list capabilities again because some clients cache
server metadata.
A preview URL shows unexpected behavior
A preview URL shows unexpected behavior
Confirm the branch and commit SHA on the deployment row. Branch names start
builds, but each build is tied to the exact commit Horizon resolved when the
build started.
Promotion fails
Promotion fails
Confirm the deployment belongs to the default branch, succeeded, and is not
already production. If the row should be promotable but promotion fails,
open build logs and server logs, then retry from the deployments table.
A deployment URL returns an access error
A deployment URL returns an access error
The request reached Horizon but did not pass the server’s access settings.
Check Authentication,
Authorization, server access, API keys, and
request logs.
A request reaches the server and then fails
A request reaches the server and then fails
Gateway routing succeeded. Check your server logs for stdout, stderr,
startup failures, handler errors, or upstream failures from the running
Python server.
Operational checklist
Before sharing or promoting a deployment, confirm:- The row has the expected branch, pull request, commit SHA, and status.
- The stable production URL or preview URL is the URL you are testing.
- Build logs show a successful package and inspection step.
- Server logs do not show startup or request-time failures for representative calls.
- Environment variables are scoped correctly for production or preview.
- Authentication mode, server access, and capability policy match the intended audience.
- Clients have reconnected or refreshed capabilities after a manifest-changing deployment.
Related docs
Hosted servers
Understand the hosted-server lifecycle across source, deployments, access,
runtime, and observability.
Build system
Learn how Horizon produces deployable artifacts from Python MCP and FastMCP
source code.
Environment variables
Configure production, preview, and branch-scoped values.