docs/deployment/prefect-horizon.mdx
Prefect Horizon is a platform for deploying and managing MCP servers. Built by the FastMCP team at Prefect, Horizon provides managed hosting, authentication, access control, and a registry of MCP capabilities.
Horizon includes a free personal tier for FastMCP users, making it the fastest way to get a secure, production-ready server URL with built-in OAuth authentication.
<Info> Horizon is free for personal projects. Enterprise governance features are available for teams deploying to thousands of users. </Info>Sign in to Horizon from the FastMCP CLI with the device authorization flow.
fastmcp login
The command uses an environment key or a valid stored key when one is available.
When login needs a new key, it shows a verification URL and code before it opens the browser.
If the browser cannot open, visit the shown URL and enter the code.
To switch accounts, run fastmcp logout before you run fastmcp login again.
New users can register and create their first Horizon organization in the browser.
Check the active account after login.
fastmcp whoami
Remove the local credential and revoke the active personal API key when possible.
fastmcp logout
Login does not select or store a deployment organization.
For an agent or a CI process, set HORIZON_API_KEY instead of storing a key.
The CLI never writes the environment value to its credential file.
When this variable controls the session, logout does not revoke or remove any credential.
Remove the variable from the environment to sign out.
Horizon is organized into four integrated pillars:
This guide focuses on Horizon Deploy, the managed hosting layer that gives you the fastest path from a FastMCP server to a production URL.
To use Horizon, you'll need a GitHub account and a GitHub repo containing a FastMCP server. If you don't have one yet, Horizon can create a starter repo for you during onboarding.
Your repo can be public or private, but must include at least a Python file containing a FastMCP server instance.
<Tip> To verify your file is compatible with Horizon, run `fastmcp inspect <file.py:server_object>` to see what Horizon will see when it runs your server. </Tip>If you have a requirements.txt or pyproject.toml in the repo, Horizon will automatically detect your server's dependencies and install them. Your file can have an if __name__ == "__main__" block, but it will be ignored by Horizon.
For example, a minimal server file might look like:
from fastmcp import FastMCP
mcp = FastMCP("MyServer")
@mcp.tool
def hello(name: str) -> str:
return f"Hello, {name}!"
There are just three steps to deploying a server to Horizon:
Visit horizon.prefect.io and sign in with your GitHub account. Connect your GitHub account to grant Horizon access to your repositories, then select the repo you want to deploy.
Next, you'll configure how Horizon should build and deploy your server.
The configuration screen lets you specify:
main.py). This field has the same syntax as the fastmcp run command—use main.py:mcp to specify a specific object in the file.Horizon will automatically detect your server's Python dependencies from either a requirements.txt or pyproject.toml file.
Click Deploy Server and Horizon will clone your repository, build your server, and deploy it to a unique URL—typically in under 60 seconds.
Once deployed, your server is accessible at a URL like:
https://your-server-name.fastmcp.app/mcp
Horizon monitors your repo and redeploys automatically whenever you push to main. It also builds preview deployments for every PR, so you can test changes before they go live.
Horizon provides two ways to verify your server is working before connecting external clients.
The Inspector gives you a structured view of everything your server exposes—tools, resources, and prompts. You can click any tool, fill in the inputs, execute it, and see the output. This is useful for systematically validating each capability and debugging specific behaviors.
For quick end-to-end testing, ChatMCP lets you interact with your server conversationally. It uses a fast model optimized for rapid iteration—you can verify the server works, test tool calls in context, and confirm the overall behavior before sharing it with others.
ChatMCP is designed for testing, not as a daily work environment. Once you've confirmed your server works, you can copy connection snippets for Claude Desktop, Cursor, Claude Code, and other MCP clients—or use the FastMCP client library to connect programmatically.
Beyond testing individual servers, Horizon lets you create Agents—chat interfaces backed by one or more MCP servers. While ChatMCP tests a single server, Agents let you compose capabilities from multiple servers into a unified experience.
To create an agent:
Once configured, you can chat with your agent directly in Horizon:
Agents are useful for creating purpose-built interfaces that combine tools from different servers. For example, you might create an agent that has access to both your company's internal data server and a general-purpose utilities server.