Build from a commit
Resolve a branch, pull request, or manual selection to an exact Git commit
before packaging the server.
Serve one MCP URL
Give clients a Horizon deployment URL, usually ending in
/mcp,
instead of exposing a process or runtime address.Protect before Python runs
Check Horizon authentication, server access, and capability policy before a
protected request reaches your handlers.
Debug by boundary
Use build logs, request logs, server logs, sessions, clients, and user
activity to see where a request stopped.
When hosted is the right shape
Choose a hosted server when the server code should be built, deployed, and run by Horizon. Hosted works well when:- You are creating a new Python MCP or FastMCP server and want the deployment lifecycle attached from the start.
- The source lives in Git and each deployment should point to a specific commit.
- Pull request previews should test code, manifests, and environment changes before production promotion.
- Clients should use a shared Horizon endpoint with server and capability access checks in front of the code.
- Operators need build logs, request logs, server logs, sessions, clients, and users connected to the same server record.
Client contract
To clients, a hosted server is a Horizon MCP endpoint. Clients call the live or preview deployment URL. Horizon identifies the selected deployment, checks access when the endpoint is protected, and routes accepted MCP requests to the artifact selected for that deployment.| Concern | What clients and operators can expect |
|---|---|
| Source | A build uses a specific Git commit. Moving a branch after the build starts does not change that artifact. |
| Endpoint | Clients call the Horizon deployment URL, not an internal runtime address. |
| Build output | A successful build creates an artifact, a discovered MCP manifest, and build logs. |
| Deployment | A live or preview deployment selects one successful artifact to serve behind a stable URL. |
| Authentication | Hosted servers have Horizon authentication enabled by default. Disabling it is available on . |
| Authorization | Server access and capability policies are evaluated before protected hosted server code runs. |
| Runtime | Python handlers run with a -second request window and MB of memory. |
| State | Local memory and files are ephemeral. Store durable application state outside the local filesystem. |
| Observability | Horizon records hosted traffic across requests, sessions, clients, users, builds, and server logs. |
Most hosted-server debugging starts by locating the boundary. Build failures
happen before an artifact exists. Gateway denials happen before Python code
runs. Runtime failures happen after Horizon has forwarded the request to your
deployed server.
Ownership boundary
Hosted does not make Horizon the owner of every part of the application. It separates platform mechanics from server behavior.| Area | Horizon owns | You own |
|---|---|---|
| Source and builds | Resolving commits, installing dependencies, packaging artifacts, and recording build logs. | Repository content, entrypoint behavior, dependency declarations, and code review. |
| Deployments | Selecting which successful artifact serves live or preview traffic. | Deciding what to promote, test, or roll back. |
| Gateway | Deployment URLs, Horizon authentication, server access, capability policy, and session routing. | Choosing who should have access and which capabilities are sensitive. |
| Runtime | Starting the hosted Python process and enforcing the request window and memory allocation. | Handler behavior, startup work, upstream calls, application errors, and durable storage choices. |
| Observability | Horizon-side request, session, client, user, build, and server log records. | Interpreting application output and adding useful server logs. |
Lifecycle
Connect source
Link the Git repository that contains the Python MCP or FastMCP server.
Choose the entrypoint and dependency file Horizon should use for builds.
Create a build
Horizon resolves the requested branch, pull request, or manual selector to
an exact commit, installs dependencies, packages the server, and inspects
the MCP surface area.
Publish an artifact
A successful build produces an immutable artifact and manifest. A failed
build leaves the currently selected live artifact unchanged.
Serve a deployment
A live or preview deployment selects one successful artifact. Promotion and
rollback change the artifact behind the same deployment URL.
Route client traffic
MCP clients call the deployment URL. Horizon identifies the deployment,
checks access, preserves MCP session routing for up to hours,
and forwards accepted requests to the hosted runtime.
Authentication model
Hosted servers expose one authentication control, Horizon Authentication, which is either enabled or disabled.| Horizon Authentication | User experience | Request behavior |
|---|---|---|
| Enabled | The MCP client completes Horizon sign-in or sends a Horizon API key. | Horizon validates the caller, checks server and capability access, then forwards accepted requests. |
| Disabled | The MCP client sends whatever the server code expects, or no credential if the server is public. | Horizon forwards without validating a Horizon bearer credential; the server owns authentication and authorization. |
What changes when
Builds, deployments, gateway metadata, and client manifests update on different timelines. When a change appears stale, check which boundary owns it.| Change | When clients see it |
|---|---|
| Source code, dependency, entrypoint, or Python version change | After a new build succeeds and that artifact is selected by a deployment. |
| Environment variable change | After a new build and deployment selection for hosted runtime behavior. |
| Authentication mode change | After a new deployment uses the updated server setting. |
| Server explicit grant or default role change | After Horizon updates live access metadata; no code change is required. |
| Capability policy change | After the policy is saved and the hosted server is redeployed with updated policy metadata. |
| Live deployment promotion or rollback | As soon as the deployment selects the new artifact, subject to client-side caching. |
| Client manifest refresh | After the client reconnects or lists capabilities again. Some clients cache tools and prompts. |
Manifest and discovery
Horizon inspects the hosted server during build and stores the discovered MCP manifest for the artifact. The dashboard, Inspector, ChatMCP, remix composition, and capability policy setup use the manifest from the relevant build or deployment. A deployment serves one selected artifact at a time. A new tool, resource, or prompt is not visible to clients until the code that registers it is built and the resulting artifact is selected by the deployment the client is using. Register capabilities during import or startup instead of after a request-time side effect. If a tool is registered only after a handler runs, Horizon may not see it during build inspection. If registration depends on environment variables, preview and production builds can intentionally produce different manifests.Troubleshooting
The build fails before an artifact exists
The build fails before an artifact exists
Check your build logs for dependency installation, entrypoint loading,
import-time, or inspection errors. A failed build does not replace the live
artifact.
A build succeeded, but live traffic did not change
A build succeeded, but live traffic did not change
Check Deployments. The successful artifact may belong to a
preview deployment, may not have been promoted, or may have been superseded
by another selected artifact.
A protected request returns 401 or 403
A protected request returns 401 or 403
The request stopped before Python code ran. Check
Authentication,
Authorization, server access, capability policy,
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, handler code, upstream
calls, and any application errors written to stdout or stderr.
A request times out
A request times out
The handler or startup path exceeded the -second request
window. Move long work out of the request path, reduce startup work, or
return earlier and continue work asynchronously.
A file or in-memory value disappears
A file or in-memory value disappears
The server used ephemeral local state as durable state. Store durable
application state outside the local filesystem.
A tool is missing in the client
A tool is missing in the client
Confirm the live deployment selects the build whose manifest contains the
tool. Then reconnect the client or list capabilities again, because some
clients cache tools and prompts.
Before clients use the server
Before sharing a hosted endpoint, check the parts of the contract clients will depend on:- The live deployment selects the intended successful build artifact.
- Inspector can list capabilities and call representative tools through the Horizon endpoint.
- Authentication matches the audience: Horizon authentication enabled for shared servers, disabled only when server code owns authentication.
- Server access and capability policies cover sensitive actions.
- Environment variables are scoped correctly for production and previews.
- Request logs and server logs make it clear whether failures stop at the gateway or inside Python code.
Related docs
Builds
Understand build inputs, states, artifacts, and manifest inspection.
Deployments
Serve successful artifacts as live or preview deployments.
Compute model
Review request timeouts, memory, startup, sessions, and ephemeral state.
Environment variables
Configure production, preview, and branch-scoped values.
Authentication
Learn how clients and API keys authenticate to hosted endpoints.
Connect a client
Configure an MCP client for a Horizon deployment URL.