Skip to main content

​
Starting a Server

fastmcp run starts a server. Point it at a Python file, a factory function, a remote URL, or a config file:
By default, the server runs over stdio — the transport that MCP clients like Claude Desktop expect. To serve over HTTP instead, specify the transport:

​
Entrypoints

FastMCP supports several ways to locate and start your server: Inferred instance — FastMCP imports the file and looks for a variable named mcp, server, or app:
Explicit instance — point at a specific variable:
Factory function — FastMCP calls the function and uses the returned server. Useful when your server needs async setup or configuration that runs before startup:
Remote URL — starts a local proxy that bridges to a remote server. Handy for local development against a deployed server, or for bridging a remote HTTP server to stdio:
FastMCP config — uses a fastmcp.json file that declaratively specifies the server, its dependencies, and deployment settings. When you run fastmcp run with no arguments, it auto-detects fastmcp.json in the current directory:
See Server Configuration for the full fastmcp.json format. MCP config — runs servers defined in a standard MCP configuration file (any .json with an mcpServers key):
fastmcp run completely ignores the if __name__ == "__main__" block. Any setup code in that block won’t execute. If you need initialization logic to run, use a factory function.

​
Options

​
Dependency Management

By default, fastmcp run uses your current Python environment directly. When you pass --python, --with, --project, or --with-requirements, it switches to running via uv run in a subprocess, which handles dependency isolation automatically. The --skip-env flag is useful when you’re already inside an activated venv, a Docker container with pre-installed dependencies, or a uv-managed project — it prevents uv from trying to set up another environment layer.

​
Previewing Apps

fastmcp dev apps launches a browser-based preview UI for servers with Prefab App tools. It starts your MCP server on one port and a local dev UI on another — giving you a live, interactive picker where you can call app tools and see their rendered output without needing a full MCP host client.
The picker auto-generates a form from each tool’s input schema. Submit the form and the result opens in a new tab as a rendered Prefab UI. Auto-reload is on by default — save a file and the MCP server restarts automatically.
fastmcp dev apps requires fastmcp[apps] — install with pip install "fastmcp[apps]".

​
Development with the Inspector

fastmcp dev inspector launches your server inside the MCP Inspector, a browser-based tool for interactively testing MCP servers. Auto-reload is on by default, so your server restarts when you save changes.
The Inspector always runs your server via uv run in a subprocess — it never uses your local environment directly. Specify dependencies with --with, --with-editable, --with-requirements, or through a fastmcp.json file.
The Inspector connects over stdio only. When it launches, you may need to select “STDIO” from the transport dropdown and click connect. To test a server over HTTP, start it separately with fastmcp run server.py --transport http and point the Inspector at the URL.

​
Pre-Building Environments

fastmcp project prepare creates a persistent uv project from a fastmcp.json file, pre-installing all dependencies. This separates environment setup from server execution — install once, run many times.
The prepared directory contains a pyproject.toml, a .venv with all packages installed, and a uv.lock for reproducibility. This is particularly useful in deployment scenarios where you want deterministic, pre-built environments.