Skip to main content
The FastMCP class is the central piece of every FastMCP application. It acts as the container for your tools, resources, and prompts, managing communication with MCP clients and orchestrating the entire server lifecycle.

​
Creating a Server

At its simplest, a FastMCP server just needs a name. Everything else has sensible defaults. 
from fastmcp import FastMCP

mcp = FastMCP("MyServer")
Instructions help clients (and the LLMs behind them) understand what your server does and how to use it effectively. 
mcp = FastMCP(
    "DataAnalysis",
    instructions="Provides tools for analyzing numerical datasets. Start with get_summary() for an overview.",
)

​
Components

FastMCP servers expose three types of components to clients, each serving a distinct role in the MCP protocol. Tools are functions that clients invoke to perform actions or access external systems. 
@mcp.tool
def multiply(a: float, b: float) -> float:
    """Multiplies two numbers together."""
    return a * b
Resources expose data that clients can read — passive data sources rather than invocable functions. 
@mcp.resource("data://config")
def get_config() -> dict:
    return {"theme": "dark", "version": "1.0"}
Prompts are reusable message templates that guide LLM interactions. 
@mcp.prompt
def analyze_data(data_points: list[float]) -> str:
    formatted_data = ", ".join(str(point) for point in data_points)
    return f"Please analyze these data points: {formatted_data}"
Each component type has detailed documentation: Tools, Resources (including Resource Templates), and Prompts.

​
Running the Server

Start your server by calling mcp.run(). The if __name__ guard ensures compatibility with MCP clients that launch your server as a subprocess. 
from fastmcp import FastMCP

mcp = FastMCP("MyServer")

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

if __name__ == "__main__":
    mcp.run()
FastMCP supports several transports:
  • STDIO (default): For local integrations and CLI tools
  • HTTP: For web services using the Streamable HTTP protocol
  • SSE: Legacy web transport (deprecated)
# Run with HTTP transport
mcp.run(transport="http", host="127.0.0.1", port=9000)
The server can also be run using the FastMCP CLI. For detailed information on transports and deployment, see Running Your Server.

​
Configuration Reference

The FastMCP constructor accepts parameters organized into four categories: identity, composition, behavior, and handlers.

​
Identity

These parameters control how your server presents itself to clients.

​
name
str
default:"FastMCP"
A human-readable name for your server, shown in client applications and logs
​
instructions
str | None
Description of how to interact with this server. Clients surface these instructions to help LLMs understand the server’s purpose and available functionality
​
version
str | None
Version string for your server. Defaults to the FastMCP library version if not provided
​
website_url
str | None
URL to a website with more information about your server. Displayed in client applications
​
icons
list[Icon] | None
List of icon representations for your server. See Icons for details

​
Composition

These parameters control what your server is built from — its components, middleware, providers, and lifecycle.

​
tools
list[Tool | Callable] | None
Tools to register on the server. An alternative to the @mcp.tool decorator when you need to add tools programmatically
​
auth
OAuthProvider | TokenVerifier | None
Authentication provider for securing HTTP-based transports. See Authentication for configuration
​
middleware
list[Middleware] | None
Middleware that intercepts and transforms every MCP message flowing through the server — requests, responses, and notifications in both directions. Use for cross-cutting concerns like logging, error handling, and rate limiting
​
providers
list[Provider] | None
Providers that supply tools, resources, and prompts dynamically. Providers are queried at request time, so they can serve components from databases, APIs, or other external sources
​
transforms
list[Transform] | None
Server-level transforms to apply to all components. Transforms modify how tools, resources, and prompts are presented to clients — for example, search transforms replace large catalogs with on-demand discovery
​
lifespan
Lifespan | AsyncContextManager | None
Server-level setup and teardown logic that runs when the server starts and stops. See Lifespans for composable lifespans

​
Behavior

These parameters tune how the server processes requests and communicates with clients.

​
on_duplicate
Literal["warn", "error", "replace", "ignore"]
default:"warn"
How to handle duplicate component registrations
​
strict_input_validation
bool
default:"False"
When False (default), FastMCP uses Pydantic’s flexible validation that coerces compatible inputs (e.g., "10" → 10 for int parameters). When True, validates inputs against the exact JSON Schema before calling your function, rejecting type mismatches. See Input Validation Modes for details
​
mask_error_details
bool | None
When True, replaces internal error details in tool/resource responses with a generic message to avoid leaking implementation details to clients. Defaults to the FASTMCP_MASK_ERROR_DETAILS environment variable
​
list_page_size
int | None
default:"None"
Maximum items per page for list operations (tools/list, resources/list, etc.). When None, all results are returned in a single response. See Pagination for details
​
tasks
bool | None
default:"False"
Enable background task support. When True, tools and resources can return CreateTaskResult to run work asynchronously while the client polls for results
​
client_log_level
LoggingLevel | None
Default minimum log level for messages sent to MCP clients via context.log(). When set, messages below this level are suppressed. Individual clients can override this per-session using the MCP logging/setLevel request. One of "debug", "info", "notice", "warning", "error", "critical", "alert", or "emergency"
​
dereference_schemas
bool
default:"True"
Automatically dereference $ref pointers in JSON schemas generated from complex Pydantic models. Most clients require flat schemas without $ref, so this should usually stay enabled

​
Handlers and Storage

These parameters provide custom handlers for MCP capabilities and persistent storage for session state.

​
sampling_handler
SamplingHandler | None
Custom handler for MCP sampling requests (server-initiated LLM calls). See Sampling for details
​
sampling_handler_behavior
Literal["always", "fallback"] | None
default:"fallback"
When "fallback", the sampling handler is used only when no tool-specific handler exists. When "always", this handler is used for all sampling requests
​
session_state_store
AsyncKeyValue | None
Persistent key-value store for session state that survives across requests. Defaults to an in-memory store. Provide a custom implementation for persistence across server restarts

​
Tag-Based Filtering

Tags let you categorize components and selectively expose them. This is useful for creating different views of your server for different environments or user types. 
@mcp.tool(tags={"public", "utility"})
def public_tool() -> str:
    return "This tool is public"

@mcp.tool(tags={"internal", "admin"})
def admin_tool() -> str:
    return "This tool is for admins only"
The filtering logic works as follows:
  • Enable with only=True: Switches to allowlist mode — only components with at least one matching tag are exposed
  • Disable: Components with any matching tag are hidden
  • Precedence: Later calls override earlier ones, so call disable after enable to exclude from an allowlist
To ensure a component is never exposed, you can set enabled=False on the component itself. See the component-specific documentation for details.
# Only expose components tagged with "public"
mcp = FastMCP()
mcp.enable(tags={"public"}, only=True)

# Hide components tagged as "internal" or "deprecated"
mcp = FastMCP()
mcp.disable(tags={"internal", "deprecated"})

# Combine both: show admin tools but hide deprecated ones
mcp = FastMCP()
mcp.enable(tags={"admin"}, only=True).disable(tags={"deprecated"})
This filtering applies to all component types (tools, resources, resource templates, and prompts) and affects both listing and access.

​
Custom Routes

When running with HTTP transport, you can add custom web routes alongside your MCP endpoint using the @custom_route decorator. 
from fastmcp import FastMCP
from starlette.requests import Request
from starlette.responses import PlainTextResponse

mcp = FastMCP("MyServer")

@mcp.custom_route("/health", methods=["GET"])
async def health_check(request: Request) -> PlainTextResponse:
    return PlainTextResponse("OK")

if __name__ == "__main__":
    mcp.run(transport="http")  # Health check at http://localhost:8000/health
Custom routes are useful for health checks, status endpoints, and simple webhooks. For more complex web applications, consider mounting your MCP server into a FastAPI or Starlette app.