# How to build an MCP server with FastMCP

Canonical: https://theagenticweekly.com/guides/build-an-mcp-server-with-fastmcp · Last verified: 2026-10-26 · Published: 2026-10-26 · Author: Agentic Weekly (operated independently from Texas, US) · Versions covered: fastmcp 4.1.3; mcp 2.3.0; Python 3.13 · Evidence: Tested (smoke test, 2026-10-25, no LLM involved), stdio only · Tools: fastmcp

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

> 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.

## 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?](https://theagenticweekly.com/what-is/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](https://theagenticweekly.com/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](https://theagenticweekly.com/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
```

Table: Timings from the log (three warm repeats, plus the very first run)

| Run | Cold start | tools/list | 50 x add_numbers, median |
|---|---|---|---|
| FastMCP 4.1.3, first run | 1589 ms | 367.8 ms | 1.3 ms |
| FastMCP, repeats 1 to 3 | 643, 735, 645 ms | 120.8, 139.3, 127.3 ms | 1.2, 1.3, 1.3 ms |
| Official SDK 2.3.0 MCPServer, same three tools, repeats 1 to 3 | 461, 516, 463 ms | 1.8, 2.6, 2.4 ms | 0.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](https://theagenticweekly.com/guides/add-mcp-server-to-claude-code).

Step evidence: Tested (stdio run, 2026-10-25; log: [/tests/mcp-python-servers](https://theagenticweekly.com/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](https://theagenticweekly.com/tests/mcp-python-servers).
- 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](https://theagenticweekly.com/tools/fastmcp) 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.

Table: Evidence by step

| Step | Evidence | Covered by |
|---|---|---|
| 1 Install | Tested | [/tests/mcp-python-servers](https://theagenticweekly.com/tests/mcp-python-servers) |
| 2 Write the server | Tested | [/tests/mcp-python-servers](https://theagenticweekly.com/tests/mcp-python-servers) |
| 3 Run over stdio and call a tool | Tested | [/tests/mcp-python-servers](https://theagenticweekly.com/tests/mcp-python-servers) |
| 4 HTTP and the fastmcp command | Reported | [FastMCP quickstart](https://gofastmcp.com/getting-started/quickstart), read 2026-10-26 |

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

## Troubleshooting

Table: Problems we hit or the docs describe

| Symptom | Likely cause | Fix | Source |
|---|---|---|---|
| A server written for the 1.x SDK fails to start with `ExceptionGroup: unhandled errors in a TaskGroup` | The import `from mcp.server.fastmcp import FastMCP` does not work the same under MCP Python SDK 2.3.0 | Use 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](https://theagenticweekly.com/tests/mcp-python-servers) |
| The first start takes more than a second | Python compiles bytecode on the first import | Run it again; our repeats started in 643 to 735 ms. | Seen by us 2026-10-25, [/tests/mcp-python-servers](https://theagenticweekly.com/tests/mcp-python-servers) |
| `fastmcp run` does not execute your `if __name__ == "__main__"` block | The command imports the server object and applies its own transport and options | Use `python server.py`, or pass the transport and port to `fastmcp run`. | [FastMCP quickstart](https://gofastmcp.com/getting-started/quickstart), read 2026-10-26 |

## Related tools

- [FastMCP](https://theagenticweekly.com/tools/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

- [FastMCP quickstart](https://gofastmcp.com/getting-started/quickstart) (fetched 2026-10-26)
- [FastMCP repository (PrefectHQ)](https://github.com/PrefectHQ/fastmcp) (fetched 2026-10-26)
- [fastmcp on PyPI](https://pypi.org/project/fastmcp/) (fetched 2026-10-26)

## Related

- [Test log: FastMCP and the official MCP Python SDK](https://theagenticweekly.com/tests/mcp-python-servers)
- [FastMCP facts and sources](https://theagenticweekly.com/tools/fastmcp)
- [FastMCP vs MCP reference servers](https://theagenticweekly.com/compare/fastmcp-vs-mcp-servers)
- [What is an MCP server?](https://theagenticweekly.com/what-is/mcp-server)
- [Best AI agent-building tools](https://theagenticweekly.com/best/agent-building)
- [Study: MCP server startup and call latency](https://theagenticweekly.com/research/mcp-servers-latency-and-failures)
- [Guide: add an MCP server to Claude Code](https://theagenticweekly.com/guides/add-mcp-server-to-claude-code)

## Changelog

- 2026-10-26: 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.

## How to cite

Agentic Weekly, "How to build an MCP server with FastMCP", last updated 2026-10-26, https://theagenticweekly.com/guides/build-an-mcp-server-with-fastmcp