Skip to main content
Builds package hosted Python MCP and FastMCP servers into deployable artifacts. A build belongs to one server and one source revision. Successful builds can be served as live deployments or preview deployments. For the hosted-server contract across source, builds, deployments, gateway access, and runtime behavior, start with Hosted servers. For the full lifecycle, defaults, and failure modes, see Build system.

​
Build contract

A build is an immutable attempt to turn one repository commit and one set of server settings into one deployable artifact. After the build starts, changing a branch or updating build settings does not change that build. Those changes apply to the next build that uses them.
Debug build problems from the build record, not from the current branch tip. The current branch may have moved since the failed build started.

​
Build states

​
What starts a build

Default branch push

A push to the configured default branch can create a production build.

Pull request

A pull request can create a preview build with preview-scoped environment variables.

Manual build

A user with server edit access can start a build from the dashboard.

Configuration change

Changes to build-relevant settings, such as the entrypoint or dependency file, take effect on the next build.

​
What does not start a build

Not every server change produces a new artifact. Some changes affect gateway or dashboard state without rebuilding server code.

​
Build inputs

​
Source resolution

FastMCP Gateway records the repository, branch context, and exact commit for every hosted build. Branch names are useful for starting production and preview workflows, but the artifact is tied to the commit that was resolved at build start. This matters when a pull request receives several pushes quickly. Preview builds run concurrently, so an older build may finish after a newer one. Use the deployment page to confirm which artifact is selected before assuming the latest completed build is live.

​
Build output

A successful build produces:
  • A deployable artifact.
  • Build logs for audit and debugging.
  • Metadata that FastMCP Gateway uses for deployment, routing, and observability.
Do not put required setup work behind a code path that only runs after a tool call. A successful build does not load your server, so import-time and startup failures appear only after the artifact is deployed. Some existing Python servers still use an earlier build process that imports the entrypoint during the build. For those servers, import-time errors can fail the build.

​
Concurrency and ordering

Default-branch deploys to the same server run one at a time. When you push several commits in quick succession, their builds run in parallel but deploy serially, so the newest commit is the last one applied and owns live traffic. Preview builds still run concurrently across branches.

​
Capability discovery

Builds do not record your server’s MCP capabilities. FastMCP Gateway reads them from the running server instead: the Permissions page lists what the live production target serves, while Playground and ChatMCP list capabilities from the target you select. If a capability is missing after a successful deployment, check whether the server registers the tool, resource, prompt, or template during import or startup. Conditional registration can make local behavior differ from the deployed server, especially when it depends on environment variables.

​
Troubleshooting

Check the dependency file path, runtime version requirements, and private package credentials.
Confirm the configured file exists in the repository revision and can be imported without running interactive code.
Make sure tools, resources, and prompts are registered during import or startup, then list capabilities for that target in Playground.
The image configuration includes startup configuration for the deployable artifact. If that configuration is larger than KB, the build fails before it reports success. Reduce values that affect the image configuration, such as large environment variables, then rebuild.
Redeploy the current version when runtime code needs the new value. Start a new build when the value affects dependency installation.
Confirm that the build created a production deployment and that the deployment succeeded. Preview deployments change only their preview target, and a superseded deployment never starts.
Compare the source revisions of the previous successful build and the new build. Then check registration code and environment-dependent imports.

Hosted servers

Start with the hosted-server contract across source, deployments, access, runtime, and observability.

Deployments

Serve successful builds as live or preview deployments.

Environment variables

Manage production and preview environment variables.

Compute model

Understand how artifacts run after deployment.