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 server process when FastMCP Gateway runs a deployment. Use environment variables for values your server code needs at startup 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 environment variables.

​
Variable contract

FastMCP Gateway treats an environment variable as part of the deployment input. When FastMCP Gateway prepares a 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 a deployment is live does not update the running server by itself. Redeploy the current version to apply the new value. You do not need a new build.
Avoid printing secret values to stdout or stderr. FastMCP Gateway 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

Redeploy the current version so runtime code receives the changed values. If the values affect the build, create a new build and deployment instead.

​
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 FastMCP Gateway.
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

Builds do not receive your environment variables. FastMCP Gateway installs dependencies and packages the server without them, so the same artifact can run with different values in each deployment. Some existing Python servers still use an earlier build process that passes environment variables to the build. For those servers, create a new build after you change a value that affects dependency installation. If your server registers tools conditionally based on an environment variable, preview and production deployments can serve different capabilities. At runtime, the deployed server process receives the variables captured when its deployment started. FastMCP Gateway 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 FastMCP Gateway has deployed the new value.
2

Update FastMCP Gateway

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

Deploy and verify

Redeploy the current version to the relevant target and confirm representative tool calls succeed. Create a new build first when the value affects build behavior.
4

Revoke the old credential

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

​
Troubleshooting

Confirm a redeployment started after the variable was saved and succeeded for the expected target. If the value affects build behavior, confirm a new build also ran.
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 values available to the live deployment with the capabilities Playground lists for that target.
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.