FastMCP MCP — Use Cases, Install & Live Demo

Why use it

Key features

Single decorator per tool: @mcp.tool or @mcp.resource
Type hints become JSON schemas — no manual schema writing
Async-first, supports sync too — stdlib typing works
Transports built in: stdio (for desktop clients), SSE / streamable HTTP (for remote)

Live Demo

What it looks like in practice

fastmcp.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "fastmcp",
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "fastmcp": {
      "command": {
        "path": "uvx",
        "args": [
          "fastmcp"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add fastmcp -- uvx fastmcp

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use FastMCP

Expose an internal REST API as an MCP in under an hour

👤 Backend engineers with an existing Python service ⏱ ~45 min intermediate

When to use: You have a company API that agents should be able to call, and you don't want to write a client spec from scratch.

Prerequisites

Python 3.10+ — python --version
uv installed — curl -LsSf https://astral.sh/uv/install.sh | sh

Flow

Bootstrap the project

Scaffold a FastMCP server project called 'acme-api-mcp' with one starter tool. Use uv for dependency management.✓ Copied

→ pyproject.toml + server.py with a working @mcp.tool example
Wrap the 3 highest-value endpoints

My internal API has endpoints /orders/{id}, /customers/search, /invoices/{id}/pdf. Write a FastMCP tool for each, using httpx.AsyncClient and reading AUTH_TOKEN from env.✓ Copied

→ 3 decorated functions with type hints + docstrings that become tool descriptions
Test locally with the MCP Inspector

Run the server with uv run mcp dev server.py. Open the inspector and call each tool with a realistic input.✓ Copied

→ Tools return expected JSON, no stack traces

Outcome: A working MCP server you can point Claude Desktop or any MCP client at.

Pitfalls

Secrets leak into tool descriptions because you printed them in docstrings — Use docstrings to describe behavior, not examples with real tokens. Load secrets via os.environ and never echo them in errors
Async + sync mixed, causes event loop errors — Pick one — if your HTTP client is async, make the whole tool async; don't call asyncio.run inside a tool

Expose company docs as MCP resources for RAG

👤 Platform engineers building agent infra ⏱ ~30 min intermediate

When to use: You want the agent to auto-discover and pull company knowledge without tool calls for every file.

Flow

Define a resource listing

Define a FastMCP resource at URI docs://{path} that lists all markdown files under ./docs/ and returns their content on read.✓ Copied

→ Resource registered, inspector shows list
Add a template resource

Add a resource template docs://{category}/{slug} that returns the matching file. Document valid {category} values.✓ Copied

→ Template registered, parameterized fetches work
Test in a real client

Connect Claude Desktop to the server. Verify the Resources menu lists all docs and content loads.✓ Copied

→ Resources appear as attachable context

Outcome: A resource-backed knowledge surface the agent can pull from natively — cleaner than tool calls for static content.

Pitfalls

Large resource lists overwhelm the client's UI — Paginate or filter in your list endpoint; not every file needs to be surfaced

Deploy a FastMCP server as a remote SSE endpoint

👤 Platform engineers serving multiple teams ⏱ ~60 min advanced

When to use: Multiple devs need the same MCP — host it once, don't make everyone run stdio locally.

Prerequisites

A container host (Cloud Run, Fly, Railway) — Any Docker-capable runtime works

Flow

Switch transport to SSE

Modify server.py to run mcp.run(transport='sse', host='0.0.0.0', port=8080). Add a minimal Dockerfile.✓ Copied

→ Local curl localhost:8080/sse shows SSE handshake
Deploy behind auth

Deploy to Cloud Run with IAM auth. Front the /sse endpoint with a header-based auth check in a FastAPI middleware.✓ Copied

→ Public URL with 401 on unauth'd requests
Wire clients

Share the connection command with teammates: npx -y mcp-remote https://mcp.acme.com/sse. Verify their Claude Desktop picks up the tools.✓ Copied

→ Team members' clients see the same tools

Outcome: A shared remote MCP — one codebase, many users, easy to update.

Pitfalls

SSE connections drop behind some corporate proxies — Use streamable HTTP transport instead (newer spec) or document a VPN/direct-path requirement

Combine with: cloud-run

Combinations

Pair with other MCPs for X10 leverage

fastmcp + cloud-run

Build once, deploy to Cloud Run, share with the team

Wrap my internal pricing API as a FastMCP server, containerize it, and deploy to Cloud Run with IAM auth.✓ Copied

fastmcp + fastapi-mcp

Compare approaches — FastMCP for greenfield, fastapi-mcp for existing FastAPI apps

I have an existing FastAPI service. Should I add fastapi-mcp to expose it or rewrite in FastMCP? Compare based on my routes.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
@mcp.tool	decorated function with typed signature	Wrap any function you want agents to call	free
@mcp.resource	URI template + function	Expose readable content (docs, config, data snapshots)	free
@mcp.prompt	decorated function returning Message[]	Provide reusable multi-turn prompt scaffolds to clients	free
mcp.run	transport: 'stdio'\|'sse'\|'streamable-http', host?, port?	Entry point — call at end of your main script	free
Context (ctx) parameter	inject ctx: Context into any tool	Long-running tools that need to stream progress or log	free

Cost & Limits

What this costs to run

API quota: None — this is a framework, not a service
Tokens per call: Your server runs any LLM calls; framework overhead is negligible
Monetary: Free, open source
Tip: Use resources instead of tools for static content — resources are cheaper in tokens because they're pre-declared

Security

Permissions, secrets, blast radius

Credential storage: Your choice — env vars are idiomatic; load secrets at process start, not per call

Data egress: Wherever your tool functions reach out to

Troubleshooting

Common errors and fixes

Tool schema missing required fields in the client

Your function params need type hints. Plain def foo(x) generates a useless schema — use def foo(x: str) with a docstring.

Verify: Run `uv run mcp dev server.py` and check the Inspector's tool schema

Server starts but client sees 0 tools

You're mixing stdio with SSE misconfiguration. For Claude Desktop use transport='stdio'; for mcp-remote use 'sse'.

`ImportError: No module named 'fastmcp'`

Install with uv pip install fastmcp or add to pyproject.toml dependencies. Check that you're running the server from the same venv.

Verify: uv pip show fastmcp

Async tool hangs on first call

You imported sync httpx inside an async tool. Use httpx.AsyncClient with async with — never mix.

Alternatives

FastMCP vs others

Alternative	When to use it instead	Tradeoff
TypeScript MCP SDK	You're a TS/Node shop and want to stay there	Official, well-maintained, similar DX — just different language
fastapi-mcp	You already have a FastAPI app and want to expose routes as tools	Less control over the MCP surface but zero-refactor for existing services
csharp-sdk	.NET shop	First-party, but smaller ecosystem of examples

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills