Skip to main content
When you deploy a hosted server, FastMCP Gateway transforms your source code into something it can run. For FastMCP Gateway, that means taking a Python MCP or FastMCP server from a specific repository commit, installing its dependencies, and producing an immutable artifact that can be deployed. This page explains what happens during that transformation, from the moment FastMCP Gateway receives a build request to the moment the build artifact is ready for a deployment.
FastMCP Gateway builds Python MCP and FastMCP servers. The build system expects a Python or TypeScript entrypoint inside your repository.

​
Starting a build

A build begins when FastMCP Gateway has a server revision to prepare. This can happen when:
  • you push to a connected Git repository
  • you upload a source archive and create a version
  • FastMCP Gateway creates or updates a preview deployment
  • you redeploy from the dashboard
  • another deployment action requests a new build
Before the build starts, FastMCP Gateway resolves the request to an exact commit SHA. That means a build is tied to immutable source code, even if it was triggered from a branch name. FastMCP Gateway also gathers the server configuration needed to build that commit.

​
Git sources

The FastMCP Gateway API can build from a Tangled, GitHub, GitLab, Bitbucket, or Azure DevOps Git repository without a provider connection. Git sources use HTTPS and a full 40-character commit SHA. FastMCP Gateway fetches that exact commit, so changing a branch after the build starts cannot change the build. Public Git access is the default. A version request can instead include token access; FastMCP Gateway encrypts the token separately from the persisted version. Token access cannot be stored as a project default, so include it in each version request that needs it. Git sources do not support branch or tag revisions, pull request previews, or automatic builds when the repository changes. Configure a new commit SHA and create a new version for each build. See the API reference for the current project configuration and version contracts.

​
Archive sources

A version can instead build from a source archive uploaded directly to FastMCP Gateway, with no repository involved. Request a presigned URL, PUT a gzipped tarball, then reference its SHA-256 in the version request. FastMCP Gateway records that digest, so the build is tied to the exact bytes you uploaded in the same way a Git build is tied to a commit. Archive sources suit work that does not justify a repository: trying a tool idea, sharing a one-off utility, or a scratch server that accumulates small tools. See deploy without Git for the full sequence.

Source

The repository and commit SHA FastMCP Gateway should check out.

Entrypoint

The Python or TypeScript file, and optional object name, that defines the server.

Dependencies

A configured dependency file, or the dependency file FastMCP Gateway discovers from the repository.

​
Build environment

Each build starts from a clean checkout of the selected commit. Files generated by previous builds are not reused, so anything your server needs must come from the repository or dependency installation. Builds do not receive the server’s environment variables. The build environment can access the network to download source code and install packages. It is meant to package your server, not run application workloads. Keep long setup scripts and import-time work small so builds stay fast and predictable. Builds time out after 15 minutes.

​
Understanding your project

Before FastMCP Gateway can package your server, it has to understand how your project is laid out. It does this by resolving the entrypoint, language version, dependency file, and execution environment.
These rules are evaluated from the checked-out commit, so changing a branch after a build starts does not change that build.

​
Entrypoint

The entrypoint tells FastMCP Gateway where your Python MCP or FastMCP server lives in the repository. It must be a relative Python or TypeScript file path, optionally followed by an object name:
If an object name is provided after :, it must be a valid identifier — starting with a letter or underscore, followed by letters, digits, or underscores. Entrypoints cannot be absolute paths, cannot include .., and must point to a file inside the repository. An entrypoint is required; FastMCP Gateway has no default entrypoint file. Python entrypoints can point to a low-level MCP server or a FastMCP server; either way, include fastmcp in your dependencies, since FastMCP Gateway relies on the fastmcp CLI to install and run your server during deployment. TypeScript entrypoints must resolve to a FastMCP instance from @prefecthq/fastmcp-ts — the build system currently does not support TypeScript servers built directly against the official MCP TypeScript SDK.

​
FastMCP configuration

A Python project can describe its own build environment in a fastmcp.json file, and FastMCP Gateway treats that file as authoritative. This is the way to control dependency installation and the Python version from your repository rather than from server settings, and it is the same file the FastMCP CLI reads locally, so a project builds on FastMCP Gateway the way it runs on your machine. FastMCP Gateway looks for the nearest fastmcp.json, starting in the entrypoint directory and walking up to the repository root. A configured dependency file in server settings takes precedence: when you set one, FastMCP Gateway uses it and ignores fastmcp.json. A repository with no fastmcp.json keeps the automatic discovery described below. FastMCP Gateway reads these fields and ignores the rest: Every path must point inside the repository, and requirement files and inline packages are resolved relative to the deployment working directory. FastMCP Gateway installs the project first, then the requirements file and inline packages together. environment.editable is not supported for hosted builds; declare those packages in environment.dependencies instead. FastMCP Gateway also ignores deployment.env, so set runtime values as environment variables on the server. A configuration selects the whole environment, so FastMCP Gateway does not fall back to dependency or Python files elsewhere in the repository. If the configuration declares no dependencies, FastMCP Gateway installs none, so list everything your server imports, including fastmcp.

​
Python version

When a fastmcp.json applies, FastMCP Gateway uses its environment.python request, then the selected project’s own metadata, and otherwise Python 3.12. Otherwise FastMCP Gateway chooses the Python version from the server source tree. It starts in the entrypoint directory and walks up toward the repository root, looking for a version request in:
  • .python-version
  • pyproject.toml project metadata
  • Python version requirements in pyproject.toml
Supported versions are Python 3.11, 3.12, 3.13, and 3.14. If FastMCP Gateway cannot find a supported version, it uses Python 3.12.

​
Dependencies

If you configure a dependency file, FastMCP Gateway uses that file. The path must point to a file inside the repository. If you do not configure one and the project has a fastmcp.json, that configuration owns dependency installation. Otherwise FastMCP Gateway searches from the entrypoint directory up to the repository root and uses the first supported file it finds: For reproducible builds, commit your lockfiles and make dependency versions as explicit as your project needs.

​
TypeScript

For a TypeScript entrypoint, FastMCP Gateway instead searches for the nearest package.json using the same walk. From that package.json, it then searches for a package-lock.json, first beside it and then in each ancestor directory up to the repository root, accepting an ancestor only when its package.json lists the entrypoint’s package.json as an npm workspace — so an npm workspaces monorepo, where a single lockfile at the workspace root covers every member’s package.json, works without changes. FastMCP Gateway installs with npm ci, scoped to the member package when the lockfile is in an ancestor directory; pnpm and yarn lockfiles are not currently supported. If you configure a dependency file path for a TypeScript server, it must point to package.json itself, not to a lockfile.

​
Environment variables

Builds do not receive the environment variables configured for the server. FastMCP Gateway gives them to the running server when it starts a deployment, so setup scripts and package hooks cannot read them. See Environment variables.

​
Build lifecycle

1

Install dependencies

FastMCP Gateway installs FastMCP and your project dependencies into the server image. Dependency installation happens during the build, so package resolution errors, missing files, and incompatible Python versions surface before a deployment can succeed.In monorepos, FastMCP Gateway resolves automatic dependency files by walking from the entrypoint directory toward the repository root, so a closer, unrelated dependency file can shadow the one you meant to use. If that happens, configure an explicit dependency file path instead.
2

Package the server

FastMCP Gateway packages your source code, dependencies, and execution configuration into a deployable server artifact.
3

Publish the artifact

If the build succeeds, FastMCP Gateway publishes an immutable artifact and records the artifact reference on the build.

​
Producing output

A successful build produces:
  • an immutable server artifact
  • build logs for the full build lifecycle
  • a terminal build status
The artifact is what FastMCP Gateway deploys. The build does not load your server or record its tools, resources, and prompts; FastMCP Gateway reads those from the running deployment. Import-time errors therefore appear after deployment, not as build failures. 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 and appear in the build logs. Failed builds do not produce a new deployable artifact.

​
Finalizing deployment

Build success and deployment success are separate steps. A successful build produces an artifact. A successful deployment makes that artifact current for its target. The target determines which endpoint changes. A preview deployment updates only its preview URL. A production deployment updates the stable production URL. A tracked GitHub push creates a build. When automatic deployment is enabled for the target, FastMCP Gateway also creates a deployment and updates the target when that deployment succeeds. When automatic deployment is disabled, use the API reference to deploy the ready version to the intended target.
If a build succeeded but the endpoint did not change, check whether it created a deployment, whether that deployment succeeded, and whether it belongs to the production or a preview target.

​
Defaults and configuration

​
Failures and logs

Build logs include lifecycle markers, dependency installation output, and packaging output. Use them when a build fails because they usually show the exact command or package step that failed.
FastMCP Gateway could not find the configured entrypoint file, the path pointed outside the repository, or the object name after : was not a valid identifier.
The configured dependency file did not exist, pointed outside the repository, or dependency installation failed.
The build ran longer than 15 minutes. Large dependency installs, package hooks, network calls, or expensive import-time work can all contribute.
Platform-level failures happen when FastMCP Gateway cannot complete the build workflow. These failures are reported with a generic message and can usually be retried.

​
What affects build speed

Build time usually depends on things inside your repository:
  • dependency count and package size
  • package install scripts
  • large repositories or large files in the build context
  • network calls during setup scripts or package hooks
Keep build-time work lightweight. Your server should do expensive application work when it receives requests, not while FastMCP Gateway is packaging it.

GitHub

Install the GitHub App and deploy servers from your repo.

Environment variables

Configure deployment-scoped environment variables.

Deployments

Understand production and preview targets, redeploy, and rollback.

Compute model

Learn how FastMCP Gateway runs the deployed build artifact.