Skip to main content
Hosted servers are the FastMCP Gateway-managed path for Python MCP and FastMCP servers you keep in Git. Point FastMCP Gateway at a repository and entrypoint, and each build turns one source revision into an artifact that can be served from a stable MCP URL. Successful deployments automatically update their production or preview target, and operators can redeploy or roll back. The important boundary is simple: FastMCP Gateway owns the path from source to a protected deployment URL. Your server code still owns the MCP behavior behind that URL, including tools, resources, prompts, upstream API calls, durable state, and application errors.

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 FastMCP Gateway deployment URL, usually ending in /mcp, instead of exposing a process or runtime address.

Protect before your server runs

Check FastMCP Gateway 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 FastMCP Gateway. 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, or you want to upload it directly without a repository.
  • Pull request previews should test code, manifests, and environment changes before those changes merge into production.
  • Clients should use a shared FastMCP Gateway 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.
If the server already runs somewhere else and should stay there, register it as an external server. If clients should connect to one curated endpoint made from selected capabilities across multiple servers, use a remix server.

​
Client contract

To clients, a hosted server is a FastMCP Gateway MCP endpoint. Clients call the live or preview deployment URL. FastMCP Gateway 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 your code runs. Runtime failures happen after FastMCP Gateway has forwarded the request to your deployed server.

​
Ownership boundary

Hosted does not make FastMCP Gateway 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 FastMCP Gateway should use for builds.
2

Create a build

FastMCP Gateway resolves the requested branch, pull request, or manual selector to an exact commit, installs dependencies, and packages the server.
3

Publish an artifact

A successful build produces an immutable artifact. A failed build leaves the currently selected live artifact unchanged.
4

Serve a deployment

A successful deployment becomes current for its production or preview target. Redeploy and rollback change the artifact or runtime settings behind the same target URL.
5

Route client traffic

MCP clients call the deployment URL. FastMCP Gateway identifies the deployment, checks access, and forwards accepted requests to the hosted runtime. Each request can run on a different instance. See the session contract.
6

Run your handlers

Tool, resource, and prompt handlers execute in your server’s process. FastMCP Gateway captures request outcomes and stdout or stderr emitted by the running server.

​
Authentication model

Hosted servers expose one authentication control, FastMCP Gateway Authentication, which is either enabled or disabled. FastMCP Gateway authentication is enabled by default for shared and production hosted servers. When a client supports interactive sign-in, the user completes a FastMCP Gateway authorization flow and the client receives a FastMCP Gateway credential for that hosted endpoint. Non-interactive clients can send a FastMCP Gateway API key as a bearer token. Disabling FastMCP Gateway authentication is for endpoints that are intentionally public or for servers whose code implements the full authentication and authorization model. It is available on Developer and Enterprise, and the change applies after a new deployment uses the updated setting. Change it from the server’s Access and Authentication page, or programmatically by updating the project’s authMode — see the API reference for the request schema. 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, FastMCP Gateway exchanges the identified actor for the saved downstream credentials and injects the configured request headers before hosted code runs. This lets code that already expects upstream credentials in those headers call the provider without implementing an OAuth callback or credential store. Delegated authorization is optional. Without a linked auth source, your server 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.

​
Capability discovery

FastMCP Gateway reads a hosted server’s capabilities from the running deployment, not from the build. The Permissions page inspects the live production target, while Playground and Chat inspect the target you select. 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, clients and FastMCP Gateway may not see it when they list capabilities. If registration depends on environment variables, preview and production deployments can intentionally serve different capabilities.

​
Troubleshooting

Check your build logs for dependency installation, entrypoint, or packaging errors. A failed build does not replace the live artifact.
Check Deployments. The build may belong to a preview target, its deployment may have failed, or a newer deployment may have superseded it before it started.
The request stopped before your code ran. Check Authentication, Authorization, server access, capability policy, and request logs.
Gateway routing succeeded. Check your server logs, handler code, upstream calls, and any application errors written to stdout or stderr.
The handler or startup path exceeded the -second request window. Reduce startup work or submit long-running work to an external worker or job service. Hosted MCP background tasks are not currently supported. See long-running work.
The server used ephemeral local state as durable state. Store durable application state outside the local filesystem.
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 FastMCP Gateway endpoint.
  • Authentication matches the audience: FastMCP Gateway 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 your server code.

Builds

Understand build inputs, states, artifacts, and capability discovery.

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 FastMCP Gateway deployment URL.