FastMCP quickstart

Who this is for and what you will build

This guide is for readers who want to write an MCP server in Python quickly. By the end you will have installed FastMCP, written a server with a tool, run it over stdio and over HTTP, called it from a client, and seen how a tool can return a visual interface and how the server can be deployed.

What FastMCP is

FastMCP is a Python toolkit for writing MCP servers. A server is a collection of tools, resources and other MCP components, and you create one by instantiating the FastMCP class^[2].

Install

The guide recommends uv for installing and managing FastMCP^[1]:

uv add fastmcp

With pip, the command is:

pip install fastmcp

Optional extras are installed with quotes. For example, pip install "fastmcp[tasks]" adds the background tasks extra^[1]. Tools that return a visual UI also need the apps extra, installed with pip install "fastmcp[apps]"^[2].

After installing, run fastmcp version to check the setup. The output lists the FastMCP version, the MCP version, the Python version and the platform^[1].

Step 1: create a server

Create a file called my_server.py with the following code^[2]:

from fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

At this point the server has no features yet. The next step adds a tool.

Step 2: add a tool

Decorate a function with @mcp.tool to register it as a tool on the server^[2]. The greet function below takes a name and returns a greeting^[2]:

from fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

@mcp.tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

Step 3: run the server

Call mcp.run() to run the server. Use the stdio transport for local servers and the http transport for remote access^[2]. Stdio is the traditional way to connect MCP servers to clients, and HTTP enables remote connections^[2].

To run over stdio, execute python my_server.py^[2]. To use HTTP instead, replace the run call with the following version^[2]:

from fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

@mcp.tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run(transport="http", port=8000)

The if __name__ == "__main__": block keeps the server working with every client that runs the file as a script. If you only start the server with the FastMCP CLI, you can leave it out^[2].

Start it with the FastMCP CLI

fastmcp run my_server.py:mcp starts the server with the default stdio transport. The CLI does not execute the __main__ block. It imports the server object and runs it with the transport and options you pass^[2]. To use HTTP, run fastmcp run my_server.py:mcp --transport http --port 8000^[2].

Step 4: call it from a client

Once the server is running over HTTP, a client can connect to http://localhost:8000/mcp. The code below calls the greet tool with the name Ford^[2]:

import asyncio
from fastmcp import Client

client = Client("http://localhost:8000/mcp")

async def call_tool(name: str):
    async with client:
        result = await client.call_tool("greet", {"name": name})
        print(result)

asyncio.run(call_tool("Ford"))

FastMCP clients are asynchronous, so the call runs through asyncio.run. The async with client: block opens the connection, and you can make as many calls inside it as you need^[2].

Advanced: return a visual interface

Tools return text by default. Add app=True to the decorator, as in @mcp.tool(app=True), and the tool can return a Prefab component. The host renders it as a chart, table, form or other visual element^[2]. This requires the apps extra^[2]. You can preview such tools locally with fastmcp dev apps my_server.py, without an MCP host^[2].

Deploying to the internet

FastMCP Gateway is the enterprise MCP platform built by the FastMCP team at Prefect. It provides hosting, authentication, access control and observability for MCP servers^[2][3]. It is free for personal projects^[2].

Deployment takes three steps^[2][3]:

1. Push my_server.py to a GitHub repository.
2. Sign in to FastMCP Gateway with your GitHub account.
3. Create a new project from the repository and enter my_server.py:mcp as the server entrypoint.

Common questions

**What if import fastmcp fails after an upgrade?** This happens only when you upgrade with pip from FastMCP 3.2 or earlier to 3.3 or later. Fresh installs and uv upgrades are not affected^[1]. Run pip install --force-reinstall fastmcp first. If that does not fix it, run pip uninstall -y fastmcp fastmcp-slim and then pip install fastmcp^[1].

How do I move from the MCP SDK or an older FastMCP? If you use the SDK v1 high-level server, with from mcp.server.fastmcp import FastMCP, the change is usually a single import line^[1]. If you already write against MCPServer in SDK v2, the migration is mostly renaming^[1]. Most FastMCP 3 servers run on FastMCP 4 without changes, and the breaking changes are listed in the upgrade guide^[1]. Upgrading from FastMCP 2.0 is covered by its own upgrade guide, which lists the breaking changes in full^[1].

How should I pin the version? For production, use a lockfile or an exact pin such as fastmcp==4.0.5, not fastmcp>=4.0.0^[1].

Next steps

For more detail, read the FastMCP installation guide and quickstart. Everything in this article comes from those two pages^[1][2].

Adapted from the installation guide and quickstart of the FastMCP official documentation^[1][2], released under the Apache-2.0 License.