Skip to main content
Environment variables are encrypted configuration values for hosted servers. They are attached to a server, scoped to the deployment environment that will use them, and provided to your Python process when Horizon builds and runs a deployment artifact. Use environment variables for values your server code needs at startup, during manifest inspection, or while handling MCP requests: upstream API keys, database URLs, feature toggles, model names, and similar configuration.
Environment variables are available to hosted servers. External and remix servers use their own connection and authorization settings instead of hosted build-time environment variables.

​
Variable contract

Horizon treats an environment variable as part of the build and deployment input. When Horizon prepares a build or deployment, it decrypts the variables for the target environment. Deployment values take precedence for that deployment. That timing matters. Changing a variable does not alter work already in progress, and changing a variable after an artifact is live does not update the running server by itself. Create a new build and make sure the deployment selects that artifact before expecting server code to see the new value.
Avoid printing secret values to stdout or stderr. Horizon captures those streams as server logs.

​
Environments

Environment variables belong to the environment where a deployment will run.
Keep production and preview credentials separate when the upstream system has separate projects, databases, accounts, or rate limits. Preview builds should be safe to test without touching production data.

​
Manage variables

Open the hosted server, then go to Settings > Environment Variables.
1

Add a variable

Choose Add variable, then enter the key, value, and an optional description. Check the environments that should receive the value. Checking both Production and Preview creates one variable record in each environment with the same initial value.
2

Choose whether the value is sensitive

New variables are sensitive by default. Sensitive variables are write-only after creation. Users who can manage server settings can copy a non-sensitive value to the clipboard; the dashboard does not display stored values. To make an existing non-sensitive variable write-only, open its actions menu and choose Mark as sensitive. This change cannot be reversed.
3

Update or delete values per environment

Production and Preview values are separate records. Updating one does not update the other unless you edit both.
4

Redeploy

Create a new build and deploy or promote it so server code receives the changed values.

​
Key rules

Variable names must:
  • Be 255 characters or fewer.
  • Start with an uppercase letter or underscore.
  • Use only uppercase letters, numbers, and underscores.
  • Not start with FASTMCP_CLOUD_ or HORIZON_, which are reserved by Horizon.
The dashboard uppercases keys as you type. Values must not be empty and can contain multiline content such as JSON.

​
Build-time and runtime behavior

Environment variables can affect both the build and the deployed server. During a build, variables may be available while Horizon installs dependencies, loads the entrypoint, and inspects the server manifest. If your server registers tools conditionally based on an environment variable, preview and production builds can produce different manifests. At runtime, the deployed Python process receives the variables that were included in the selected artifact. Horizon does not reinstall dependencies or refresh environment variables when a request arrives. For the full build lifecycle, see Build system. For runtime behavior, see Compute model.

​
Deployment overrides

The env values supplied when creating a deployment take precedence over the variables configured for its target environment. For example, a preview deployment can use MODEL_NAME from Preview settings while overriding DATABASE_URL. Other preview deployments continue to use the saved Preview value. Use deployment overrides for branch-specific configuration and other values that apply to one deployment. Use Production and Preview settings for values shared by every deployment in an environment. See the generated API reference for the deployment request contract.

​
Rotation

Rotate a variable in the environment where the credential is used.
1

Create the replacement upstream credential

Keep the old credential active until Horizon has deployed the new value.
2

Update Horizon

Update the Production or Preview value. For a deployment override, update the deployment input instead.
3

Build and verify

Start a new build, deploy it to the relevant preview or production deployment, and confirm representative tool calls succeed.
4

Revoke the old credential

Revoke the old value only after the deployment using the new value is live.

​
Troubleshooting

Confirm a new build started after the variable was saved, then confirm the deployment selects that build artifact. Existing artifacts keep the values they were built with.
Confirm that the deployment uses a preview target, then check whether its env input overrides the saved Preview value.
Check the key name. Keys must start with an uppercase letter or underscore, use only uppercase letters, numbers, and underscores, and avoid reserved prefixes.
If tool registration depends on environment variables, compare the manifest for the build that is live with the values available during that build.
Rotate the credential, update the matching environment, rebuild and redeploy, then remove or mask the logging statement in server code.

Hosted servers

Understand the hosted-server lifecycle and ownership boundary.

Builds

See how build inputs become immutable artifacts.

Deployments

Confirm which artifact is live for production or preview traffic.

Encryption and data protection

How values are encrypted at rest and kept out of logs and responses.