Agentic WeeklyGet the weekly

How to build an MCP server with FastMCP

FastMCP is a Python framework for building MCP servers. In our 2026-10-25 smoke test, FastMCP 4.1.3 ran a three-tool server over stdio, answering calls in about 1 ms median and starting in 643 to 735 ms on warm repeats. We did not test HTTP transport, authentication or any AI client for this guide.

By Agentic Weekly, operated independently from Texas, US · Last updated (America/Chicago) · How we work

Checked by Agentic Weekly's editorial process: vendor docs re-read (the commands were run on 2026-10-25, not re-run on this date).

Last verified: 2026-10-26 (America/Chicago) · Versions covered: fastmcp 4.1.3; mcp 2.3.0; Python 3.13 · Evidence: Tested (see “What we tested”)

What you will build

A small MCP server in Python with three tools (add_numbers, echo and word_count) that any MCP client can start over stdio. FastMCP's own docs call the library "the fast, Pythonic way to build MCP servers and clients" (docs site metadata, read 2026-10-26). If you are new to the term, read What is an MCP server? first.

The code below is the server from our test log (we added blank lines for readability). It has no model in it: the tools are plain Python functions, and the framework builds each tool's input schema from the function signature.

Prerequisites

  • Operating system and hardware we ran on: Linux x86_64 virtual machine (Debian 13), 8 vCPU, 15 GiB RAM, no GPU. Not run by us: macOS and Windows.
  • Python 3.13 and uv (what we ran). PyPI lists Python 3.10 or newer for FastMCP (PyPI, read 2026-10-26), which we did not run.
  • Versions: FastMCP 4.1.3 and the MCP Python SDK 2.3.0. PyPI listed FastMCP 4.1.4 when we read it on 2026-10-26, so the latest release may behave differently from the one we ran.
  • Accounts and keys: none. Nothing in this guide calls a hosted model.

Step 1: Install FastMCP in a clean environment

Create a fresh virtual environment and install FastMCP. Our log installed FastMCP 4.1.3, which our log records as the version installed on 2026-10-25; to match it exactly, pin fastmcp==4.1.3.

Command (as logged)
uv venv -p 3.13 .venv && VIRTUAL_ENV=.venv uv pip install fastmcp mcp
Expected result (from the log notes)
fastmcp 4.1.3 installed; its dependency list included mcp 2.3.0 and mcp-types 2.3.0.

Step evidence: Tested (install, 2026-10-25; log: /tests/mcp-python-servers).

Step 2: Write the server

Save this as server.py. @mcp.tool registers a function as a tool, and mcp.run(transport="stdio") makes the script speak MCP on standard input and output.

server.py (from the log, with blank lines added)
from fastmcp import FastMCP

mcp = FastMCP("bench-fastmcp")

@mcp.tool
def add_numbers(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

@mcp.tool
def echo(message: str) -> str:
    """Echo a message."""
    return message

@mcp.tool
def word_count(text: str) -> int:
    """Count words."""
    return len(text.split())

if __name__ == "__main__":
    mcp.run(transport="stdio", show_banner=False)

The FastMCP quickstart (read 2026-10-26) shows the same pattern with a greet tool, and notes that mcp.run() defaults to stdio while mcp.run(transport="http", port=8000) serves HTTP.

Step evidence: Tested (this server file, 2026-10-25; log: /tests/mcp-python-servers).

Step 3: Run it over stdio and call a tool

A stdio server is started by its client. Our client was a small script written with the official MCP Python SDK 2.3.0 that launched the server as a child process, then timed the handshake, one tools/list and 50 add_numbers calls. The command it launched was the server file run by the virtual environment's Python.

Command the client launched (as logged)
.venv/bin/python server.py
Expected result (what our client saw)
server: bench-fastmcp 4.1.3
protocol: 2025-11-25
tools: add_numbers, echo, word_count (3)
add_numbers({"a": 17, "b": 25}) -> 42
Timings from the log (three warm repeats, plus the very first run)
RunCold starttools/list50 x add_numbers, median
FastMCP 4.1.3, first run1589 ms367.8 ms1.3 ms
FastMCP, repeats 1 to 3643, 735, 645 ms120.8, 139.3, 127.3 ms1.2, 1.3, 1.3 ms
Official SDK 2.3.0 MCPServer, same three tools, repeats 1 to 3461, 516, 463 ms1.8, 2.6, 2.4 ms0.7, 0.8, 0.9 ms

The first FastMCP run was slower because Python compiled bytecode on first import, so the repeats are the better guide to normal startup. Both servers answered calls in about a millisecond; that is process and protocol overhead on tiny inputs, not a measure of real tools. To use the server from an AI client, follow your client's instructions, for example Add an MCP server to Claude Code.

Step evidence: Tested (stdio run, 2026-10-25; log: /tests/mcp-python-servers).

Step 4: Optional: serve it over HTTP or with the fastmcp command

The FastMCP quickstart (read 2026-10-26) documents two other ways to run a server. We list them for completeness; they are not part of our published log.

From the FastMCP quickstart: run with the CLI over stdio
fastmcp run server.py:mcp
From the FastMCP quickstart: run over HTTP on port 8000
fastmcp run server.py:mcp --transport http --port 8000

The quickstart says clients then connect at http://localhost:8000/mcp, and that the fastmcp run command imports your server object instead of executing the __main__ block. We did not test authentication, so treat an HTTP server as local-only until you have checked how access is controlled.

Step evidence: Reported (not run by us). Source: https://gofastmcp.com/getting-started/quickstart, read 2026-10-26.

What we tested

Evidence: Tested (smoke test, 2026-10-25, no LLM involved), stdio only. Everything about HTTP, the fastmcp command and clients is Reported (not run by us) here.

  • What we ran: the install above, then the three-tool server over stdio, compared with the same three tools written on the official MCP Python SDK 2.3.0. Run on 2026-10-25 at 22:38 to 22:39 CDT (America/Chicago).
  • Environment: Linux x86_64 virtual machine (Debian 13), 8 vCPU, 15 GiB RAM, no GPU, shared with other jobs.
  • Model: no language model involved.
  • Full test log: FastMCP and the official MCP Python SDK test log.
  • A separate earlier run, also on 2026-10-25 (17:35 to 17:55 CDT), tried a two-tool server through an in-memory client, stdio and HTTP on 127.0.0.1 and ran fastmcp inspect. Its raw log is not published on a /tests page, so this guide does not count it: those steps stay Reported here. The FastMCP tool page states the same split.
  • Not tested: remote (HTTP) transport as part of the published log, authentication including OAuth, concurrent clients, large payloads, any real AI client (Claude, ChatGPT or others), and production deployment.
Evidence by step
StepEvidenceCovered by
1 InstallTested/tests/mcp-python-servers
2 Write the serverTested/tests/mcp-python-servers
3 Run over stdio and call a toolTested/tests/mcp-python-servers
4 HTTP and the fastmcp commandReportedFastMCP quickstart, read 2026-10-26

This is a smoke test, not a benchmark: one client, tiny inputs, one shared machine.

Troubleshooting

Problems we hit or the docs describe
SymptomLikely causeFixSource
A server written for the 1.x SDK fails to start with ExceptionGroup: unhandled errors in a TaskGroupThe import from mcp.server.fastmcp import FastMCP does not work the same under MCP Python SDK 2.3.0Use the standalone fastmcp package as above, or on the official SDK 2.x use mcp.server.mcpserver.MCPServer. We saw the failure and did not dig into the cause.Reproduced by us 2026-10-25, /tests/mcp-python-servers
The first start takes more than a secondPython compiles bytecode on the first importRun it again; our repeats started in 643 to 735 ms.Seen by us 2026-10-25, /tests/mcp-python-servers
fastmcp run does not execute your if __name__ == "__main__" blockThe command imports the server object and applies its own transport and optionsUse python server.py, or pass the transport and port to fastmcp run.FastMCP quickstart, read 2026-10-26
  • FastMCP: If you run FastMCP servers, upgrade and read the security notices; the OAuth issuer step is not automatic. Tested (smoke test, 2026-10-25, no language model involved).

FAQ

What is FastMCP?

FastMCP is a Python library for building MCP servers and clients; its docs call it "the fast, Pythonic way to build MCP servers and clients" (read 2026-10-26). We installed version 4.1.3 and ran a three-tool server over stdio in a smoke test on 2026-10-25.

How do I install FastMCP?

We ran uv venv -p 3.13 .venv, then uv pip install fastmcp mcp, which installed FastMCP 4.1.3 on 2026-10-25. PyPI listed 4.1.4 on 2026-10-26, so pin fastmcp==4.1.3 if you want the version we tested.

How do I run a FastMCP server over HTTP?

The FastMCP quickstart (read 2026-10-26) gives fastmcp run server.py:mcp --transport http --port 8000, then clients connect at http://localhost:8000/mcp. We have not run that command for this guide; our published log covers stdio only.

Do I need an API key to build an MCP server?

Not in our test: we used no account, API key or language model. That describes this local stdio test only. A server that calls a paid service, or an HTTP deployment with authentication, can need credentials.

Does FastMCP work with Claude or ChatGPT?

We have not tested FastMCP servers with Claude, ChatGPT or any other AI client, so we do not claim compatibility. Check each client's own documentation for how to add a server; our Claude Code guide lists the documented commands.

Have you tested FastMCP?

Yes, for stdio only. On 2026-10-25 we published a smoke test of a three-tool FastMCP 4.1.3 server against the official SDK. HTTP, authentication, OAuth and real AI clients were not tested for this guide; those steps are Reported.

Sources

Page history

  • : First published. FastMCP quickstart and PyPI page read on this date; commands come from the 2026-10-25 test log and were not re-run.

Markdown version for agents: /guides/build-an-mcp-server-with-fastmcp.md