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, 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, 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.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.Lifecycle
1
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.
2
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.
3
Publish an artifact
A successful build produces an immutable artifact and manifest. A failed
build leaves the currently selected live artifact unchanged.
4
Serve a deployment
A live or preview deployment selects one successful artifact. Promotion and
rollback change the artifact behind the same deployment URL.
5
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.
6
Run your handlers
Tool, resource, and prompt handlers execute in your Python process. Horizon
captures request outcomes and stdout or stderr emitted by the running
server.
Authentication model
Hosted servers expose one authentication control, Horizon Authentication, which is either enabled or disabled.
Horizon authentication is enabled by default for shared and production hosted
servers. When a client supports interactive sign-in, the user completes a Horizon
authorization flow and the client receives a Horizon credential for that hosted
endpoint. Non-interactive clients can send a Horizon API key as a bearer token.
Disabling Horizon authentication is for endpoints that are intentionally public
or for servers whose code implements the full authentication and authorization
model. It is available on , and the change applies after
a new deployment uses the updated setting.
A protected hosted server can optionally use
delegated authorization. You link one OAuth
or API-key auth source from Access and Authentication. For an eligible
user request, Horizon exchanges the identified actor for the saved downstream
credential and injects it into the configured request header before hosted code
runs. This lets code that already expects the upstream credential in that
header call the provider without implementing an OAuth callback or token store.
Delegated authorization is optional. Without a linked auth source, your Python
code chooses how to authenticate upstream calls, such as with deployment
environment variables or an authorization flow implemented by the server.
What changes when
Builds, deployments, gateway metadata, and client manifests update on different timelines. When a change appears stale, check which boundary owns it.Manifest and discovery
Horizon inspects the hosted server during build and stores the discovered MCP manifest for the artifact. The dashboard, remix composition, and capability policy setup use the manifest from the relevant build or deployment. Playground and Chat connect to the selected target and use its live capabilities. 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 selected target serves the build that contains the tool. Then
refresh Playground or reconnect clients that 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.
- Playground 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 and preview environment variables.
Authentication
Learn how clients and API keys authenticate to hosted endpoints.
Connect a client
Configure an MCP client for a Horizon deployment URL.