Use when building, extending, or debugging FastMCP v3 Python MCP servers — covers tools, resource structure, prompts, provider integrations, transforms, authentication configuration, client SDK usage, deployment recipes, and testing. All guidance and examples are strictly grounded in the local FastMCP v3 documentation — zero speculation.
Python version:
!python3 --version 2>/dev/null || python --version 2>/dev/null || echo "Python not found in PATH"
Installed FastMCP version:
!uv run python -c "import fastmcp; print(f'FastMCP {fastmcp.__version__}')" 2>/dev/null || echo "FastMCP not installed — run: uv add 'fastmcp>=4.0' before scaffolding"
When user intent matches, load the reference file listed — do not rely on training data for v3/v4 API facts.
| User intent | Feature | Reference file |
|---|---|---|
| Build a new FastMCP server | FastMCP(), @mcp.tool, @mcp.resource | ./references/server-core.md |
| Compose multiple servers | mount(), namespace, providers | ./references/providers.md |
| Bridge remote HTTP server to stdio | ProxyProvider, create_proxy() | ./references/providers.md |
| Serve files or skills as resources | FileSystemProvider, SkillsProvider | ./references/providers.md |
| Rename or filter tools from sub-server | ToolTransform, Namespace | ./references/transforms.md |
| Expose resources as tools | ResourcesAsTools | ./references/transforms.md |
| Search/discover tools in large catalogs | BM25SearchTransform, RegexSearchTransform | ./references/transforms.md |
| Sandbox tool execution via Python scripts | CodeMode (experimental) | ./references/transforms.md |
| Add authentication to a server | require_scopes, OAuth variants | ./references/auth.md |
| Mix OAuth + JWT token verifiers | MultiAuth | ./references/auth.md |
| Use PropelAuth for auth | PropelAuthProvider | ./references/auth.md |
| Write a FastMCP client | Client, transports, BearerAuth | ./references/client-sdk.md |
| Run long tasks without blocking | @mcp.tool(task=True) | ./references/advanced.md |
| Add multi-turn user input to a tool | Elicitation API | ./references/advanced.md |
| Deploy to production | Prefect Horizon, HTTP, stdio, nginx | ./references/deployment.md |
| Deploy behind nginx reverse proxy | SSE config, TLS, subpath mounting | ./references/deployment.md |
| Write tests for a FastMCP server | In-memory Client, pytest patterns | ./references/testing.md |
| Integrate with Anthropic/OpenAI/FastAPI | Integration patterns | ./references/integrations.md |
| Migrate from FastMCP v2 to v3 | Breaking changes, syntax fixes | ./references/migration.md |
| Migrate/upgrade a v3 server to v4 | ToolAnnotations snake_case, TasksExtension, sampling removal | ./references/migration.md |
| Debug a masked tool exception on stdio | Rich traceback logging trap | ./references/server-core.md |
| Add web UI to a server | Apps HTML API, Prefab Apps | ./references/apps.md |
| Return interactive UI from tools | @mcp.tool(app=True), PrefabApp | ./references/advanced.md |
| Add request/response middleware | Middleware, built-in middleware | ./references/middleware.md |
| Find real-world usage patterns | ProxyProvider, mount(), showcase | ./references/real-world-patterns.md |
| Evaluate MCP server quality | Evaluation harness, QA pairs | ./references/evaluation-guide.md |
| Build interactive app server with UI tools | FastMCPApp, @app.ui(), @app.tool() | ./references/apps.md |
| LLM writes custom UI at runtime | Generative UI | ./references/apps.md |
| Use Keycloak for enterprise auth | KeycloakProvider | ./references/auth.md |
| Install client-only, no server deps | fastmcp-slim | ./references/client-sdk.md |
| Preview app tools in browser without MCP host | fastmcp dev apps | ./references/deployment.md |
| Add OTEL tracing to a server | OTEL instrumentation | ./references/observability.md |
| Configure persistent cache or OAuth state storage | storage backends | ./references/middleware.md |
flowchart TD
Q1{What do you need?}
Q1 -->|Define tools/resources in this server| LC["LocalProvider — default<br>No mount() needed<br>Source: providers/local.mdx"]
Q1 -->|Add another FastMCP server's tools| MC["FastMCPProvider / mount()<br>mcp.mount(sub, namespace='ns')<br>Source: servers/composition.md"]
Q1 -->|Wrap remote HTTP MCP server| PC["ProxyProvider<br>create_proxy('http://remote/mcp')<br>Source: providers/proxy.mdx"]
Q1 -->|Serve files from disk as resources| FC["FileSystemProvider('path/')<br>reload=True for dev, False for prod<br>Source: providers/filesystem.mdx"]
Q1 -->|Expose Claude/Cursor skill files| SC["SkillsProvider / ClaudeSkillsProvider()<br>skill:// URI scheme<br>Source: providers/skills.mdx"]
Q1 -->|Build a custom provider| CC["Subclass Provider base class<br>Source: providers/custom.mdx"]
flowchart TD
Q1{How will clients connect?}
Q1 -->|Local tool in Claude Code / desktop app| ST["stdio — default<br>fastmcp run server.py:mcp<br>Source: deployment/running-server.mdx"]
Q1 -->|Web service or multi-client| HT["HTTP transport<br>mcp.run(transport='http', port=8000)<br>Source: deployment/http.mdx"]
Q1 -->|Testing — in-process| IT["In-memory transport<br>async with Client(mcp) as client<br>Source: patterns/testing.mdx"]
Q1 -->|Managed cloud deployment| PH["Prefect Horizon<br>fastmcp run via GitHub integration<br>Source: deployment/prefect-horizon.mdx"]
flowchart TD
Q1{Auth requirement?}
Q1 -->|No auth needed| NA["No auth — default FastMCP behavior"]
Q1 -->|Validate bearer tokens per tool| RS["require_scopes('scope')<br>@mcp.tool(auth=require_scopes('write'))<br>Source: servers/auth/token-verification.mdx"]
Q1 -->|Full OAuth2 server built-in| FO["Full OAuth server<br>Source: servers/auth/full-oauth-server.mdx"]
Q1 -->|Delegate to external IdP — Auth0, Azure| OP["OIDC proxy / OAuth proxy<br>Source: servers/auth/oidc-proxy.mdx"]
Q1 -->|Mix OAuth + JWT for hybrid clients| MA["MultiAuth — compose OAuth server<br>+ token verifiers (v3.1)<br>Source: servers/auth/multi-auth.mdx"]
Q1 -->|Use PropelAuth| PA["PropelAuthProvider<br>OAuth + token introspection (v3.1)<br>Source: integrations/propelauth.mdx"]
Q1 -->|Client calling protected server| CA["Client auth — BearerAuth / CIMDAuth / OAuthAuth<br>Source: clients/auth/*.mdx"]
from fastmcp import FastMCP
mcp = FastMCP("my-server")
@mcp.tool # RULE: no parentheses — v3 canonical syntax
def greet(name: str) -> str:
"""Return a greeting."""
return f"Hello, {name}!"
if __name__ == "__main__":
mcp.run()
from fastmcp import FastMCP
weather = FastMCP("weather")
main = FastMCP("main")
main.mount(weather, namespace="weather")
# Tools from weather become weather_<tool-name> on main
from fastmcp import FastMCP
from fastmcp_tasks import TasksExtension
mcp = FastMCP("task-server")
mcp.add_extension(TasksExtension()) # required in v4; implicit in v3 — see references/migration.md
@mcp.tool(task=True) # RULE: task=True, NOT task=TaskConfig(...)
async def long_running(data: str) -> str:
"""Process data in background."""
return "done"
Before deploying: run in-process pytest using the in-memory Client transport (references/testing.md) before switching to HTTP transport. In-process tests are the fastest signal that tools behave as expected.
CONSTRAINT: These v2 patterns are deprecated or removed. Generate only the v3 form, then check ./references/migration.md for a v3→v4 change to the same pattern — e.g. task=True also needs TasksExtension registration in v4.
| v2 / wrong pattern | v3 correct pattern | Source | Why |
|---|---|---|---|
| @mcp.tool() with parentheses | @mcp.tool without parentheses | quickstart.mdx | v3 unified tool config into constructor kwargs — per-decorator arguments removed |
| task=TaskConfig(mode="required") | task=True | servers/tasks.mdx | TaskConfig replaced by runtime extra dependency |
| require_auth | require_scopes("scope") | servers/authorization.mdx | v3 replaced binary auth flags with granular scope-based access control — require_scopes() specifies which scopes are required rather than just checking authentication |
| .mcpb packaging | Prefect Horizon or stdio deploy | deployment/running-server.mdx | — |
| ctx.get_state() / ctx.set_state() (synchronous) | await ctx.get_state() / await ctx.set_state() | getting-started/upgrading/from-fastmcp-2.md | State is now session-scoped and backed by a pluggable storage backend — calls must be awaited; the methods exist in v3 but are async |
All core features (tools, resources, prompts, providers, transforms, auth, tasks, elicitation, client SDK, deployment) are available in FastMCP 3.0.
The following features were added in FastMCP 3.1.0 and require fastmcp>=3.1.0:
BM25SearchTransform, RegexSearchTransform for large tool catalogsfastmcp[code-mode])transforms= kwarg — server-level FastMCP("name", transforms=[...]) constructor parameterPropelAuthProvider for PropelAuth OAuth + token introspection@mcp.tool(app=True) with declarative UI components (fastmcp[apps])-m/--module flag — fastmcp run -m my_package.server for module modeFASTMCP_TRANSPORT env var — default transport selection without CLI flaghttp_client parameter — connection pooling for token verifiersinclude_unversioned option in VersionFilterTool.from_tool() — immediate transformation at registration time [4]The following features were added in FastMCP 3.2 and require fastmcp>=3.2.0:
@app.ui()) from backend tools (@app.tool())fastmcp dev apps — browser preview for app tools without an MCP hostfastmcp realmrun_in_thread=False on @mcp.tool() — opt sync tools out of the default threadpool dispatch for thread-affine librariesssl verify parameter on Client — SSL certificate configuration for development with self-signed certsclient_log_level parameter on Client — control client-side log verbosityResponseCachingMiddleware token-partitioning security fix (v3.2.2) — cache now partitioned by access token; upgrade required for deployments with multiple users [5]The following features were added in FastMCP 3.3 and require fastmcp>=3.3.0:
fastmcp-slim[client] for consumers who only need the FastMCP client without the full server framework; import namespace is identical (from fastmcp import Client)FastMCP 4.0 is not an additive gate like 3.1–3.3 above — it removes and renames APIs. See ./references/migration.md for what changed and what to generate instead.
All reference files sourced from https://gofastmcp.com (published docs) and https://github.com/jlowin/fastmcp (source code); v4-specific deltas are called out inline and centralized in ./references/migration.md:
FastMCP(), tools, resources, prompts, context, lifespan, transforms= kwargrequire_scopes, OAuth variants, token verification, MultiAuth, PropelAuth, http_client poolingClient, transports, BearerAuth, CIMD, OAuth, sampling, elicitation, fastmcp discover, fuzzy matchingFASTMCP_TRANSPORTPreserved references:
.mcp.json config, Claude Code deploymentSkill(skill: "fastmcp-creator:fastmcp-python-tests")fastmcp list / fastmcp call / fastmcp discover CLI usage:
Skill(skill: "fastmcp-creator:fastmcp-client-cli")Skill(skill: "python3-development:python3-development").mcp.json): ./references/claude-code-mcp-integration.mdSearch for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer