`fastmcp.server.server`

FastMCP - A more ergonomic interface for MCP servers.

Functions

`default_lifespan`

default_lifespan(server: FastMCP[LifespanResultT]) -> AsyncIterator[Any]

Default lifespan context manager that does nothing. Args:

server: The server instance this lifespan is managing

Returns:

An empty context object

`add_resource_prefix`

add_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> str

Add a prefix to a resource URI. Args:

uri: The original resource URI
prefix: The prefix to add

Returns:

The resource URI with the prefix added

Examples: With new style:

add_resource_prefix("resource://path/to/resource", "prefix")
"resource://prefix/path/to/resource"

With legacy style:

add_resource_prefix("resource://path/to/resource", "prefix")
"prefix+resource://path/to/resource"

With absolute path:

add_resource_prefix("resource:///absolute/path", "prefix")
"resource://prefix//absolute/path"

Raises:

ValueError: If the URI doesn’t match the expected protocol://path format

`remove_resource_prefix`

remove_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> str

Remove a prefix from a resource URI. Args:

uri: The resource URI with a prefix
prefix: The prefix to remove
prefix_format: The format of the prefix to remove

Returns: The resource URI with the prefix removed Examples: With new style:

remove_resource_prefix("resource://prefix/path/to/resource", "prefix")
"resource://path/to/resource"

With legacy style:

remove_resource_prefix("prefix+resource://path/to/resource", "prefix")
"resource://path/to/resource"

With absolute path:

remove_resource_prefix("resource://prefix//absolute/path", "prefix")
"resource:///absolute/path"

Raises:

ValueError: If the URI doesn’t match the expected protocol://path format

`has_resource_prefix`

has_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> bool

Check if a resource URI has a specific prefix. Args:

uri: The resource URI to check
prefix: The prefix to look for

Returns:

True if the URI has the specified prefix, False otherwise

Examples: With new style:

has_resource_prefix("resource://prefix/path/to/resource", "prefix")
True

With legacy style:

has_resource_prefix("prefix+resource://path/to/resource", "prefix")
True

With other path:

has_resource_prefix("resource://other/path/to/resource", "prefix")
False

Raises:

ValueError: If the URI doesn’t match the expected protocol://path format

Classes

`FastMCP`

Methods:

`settings`

settings(self) -> Settings

`name`

name(self) -> str

`instructions`

instructions(self) -> str | None

`version`

version(self) -> str | None

`run_async`

run_async(self, transport: Transport | None = None, show_banner: bool = True, **transport_kwargs: Any) -> None

Run the FastMCP server asynchronously. Args:

transport: Transport protocol to use (“stdio”, “sse”, or “streamable-http”)

`run`

run(self, transport: Transport | None = None, show_banner: bool = True, **transport_kwargs: Any) -> None

Run the FastMCP server. Note this is a synchronous function. Args:

transport: Transport protocol to use (“stdio”, “sse”, or “streamable-http”)

`add_middleware`

add_middleware(self, middleware: Middleware) -> None

`get_tools`

get_tools(self) -> dict[str, Tool]

Get all registered tools, indexed by registered key.

`get_tool`

get_tool(self, key: str) -> Tool

`get_resources`

get_resources(self) -> dict[str, Resource]

Get all registered resources, indexed by registered key.

`get_resource`

get_resource(self, key: str) -> Resource

`get_resource_templates`

get_resource_templates(self) -> dict[str, ResourceTemplate]

Get all registered resource templates, indexed by registered key.

`get_resource_template`

get_resource_template(self, key: str) -> ResourceTemplate

Get a registered resource template by key.

`get_prompts`

get_prompts(self) -> dict[str, Prompt]

List all available prompts.

`get_prompt`

get_prompt(self, key: str) -> Prompt

`custom_route`

custom_route(self, path: str, methods: list[str], name: str | None = None, include_in_schema: bool = True) -> Callable[[Callable[[Request], Awaitable[Response]]], Callable[[Request], Awaitable[Response]]]

Decorator to register a custom HTTP route on the FastMCP server. Allows adding arbitrary HTTP endpoints outside the standard MCP protocol, which can be useful for OAuth callbacks, health checks, or admin APIs. The handler function must be an async function that accepts a Starlette Request and returns a Response. Args:

path: URL path for the route (e.g., “/auth/callback”)
methods: List of HTTP methods to support (e.g., [“GET”, “POST”])
name: Optional name for the route (to reference this route with Starlette’s reverse URL lookup feature)
include_in_schema: Whether to include in OpenAPI schema, defaults to True

`add_tool`

add_tool(self, tool: Tool) -> Tool

Add a tool to the server. The tool function can optionally request a Context object by adding a parameter with the Context type annotation. See the @tool decorator for examples. Args:

tool: The Tool instance to register

Returns:

The tool instance that was added to the server.

`remove_tool`

remove_tool(self, name: str) -> None

Remove a tool from the server. Args:

name: The name of the tool to remove

Raises:

NotFoundError: If the tool is not found

`add_tool_transformation`

add_tool_transformation(self, tool_name: str, transformation: ToolTransformConfig) -> None

Add a tool transformation.

`remove_tool_transformation`

remove_tool_transformation(self, tool_name: str) -> None

Remove a tool transformation.

`tool`

tool(self, name_or_fn: AnyFunction) -> FunctionTool

`tool`

tool(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionTool]

`tool`

tool(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionTool] | FunctionTool

Decorator to register a tool. Tools can optionally request a Context object by adding a parameter with the Context type annotation. The context provides access to MCP capabilities like logging, progress reporting, and resource access. This decorator supports multiple calling patterns:

@server.tool (without parentheses)
@server.tool (with empty parentheses)
@server.tool(“custom_name”) (with name as first argument)
@server.tool(name=“custom_name”) (with name as keyword argument)
server.tool(function, name=“custom_name”) (direct function call)

Args:

name_or_fn: Either a function (when used as @tool), a string name, or None
name: Optional name for the tool (keyword-only, alternative to name_or_fn)
description: Optional description of what the tool does
tags: Optional set of tags for categorizing the tool
output_schema: Optional JSON schema for the tool’s output
annotations: Optional annotations about the tool’s behavior
exclude_args: Optional list of argument names to exclude from the tool schema
meta: Optional meta information about the tool
enabled: Optional boolean to enable or disable the tool

Examples: Register a tool with a custom name:

@server.tool
def my_tool(x: int) -> str:
    return str(x)

# Register a tool with a custom name
@server.tool
def my_tool(x: int) -> str:
    return str(x)

@server.tool("custom_name")
def my_tool(x: int) -> str:
    return str(x)

@server.tool(name="custom_name")
def my_tool(x: int) -> str:
    return str(x)

# Direct function call
server.tool(my_function, name="custom_name")

`add_resource`

add_resource(self, resource: Resource) -> Resource

Add a resource to the server. Args:

resource: A Resource instance to add

Returns:

The resource instance that was added to the server.

`add_template`

add_template(self, template: ResourceTemplate) -> ResourceTemplate

Add a resource template to the server. Args:

template: A ResourceTemplate instance to add

Returns:

The template instance that was added to the server.

`add_resource_fn`

add_resource_fn(self, fn: AnyFunction, uri: str, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None) -> None

Add a resource or template to the server from a function. If the URI contains parameters (e.g. “resource://”) or the function has parameters, it will be registered as a template resource. Args:

fn: The function to register as a resource
uri: The URI for the resource
name: Optional name for the resource
description: Optional description of the resource
mime_type: Optional MIME type for the resource
tags: Optional set of tags for categorizing the resource

`resource`

resource(self, uri: str) -> Callable[[AnyFunction], Resource | ResourceTemplate]

Decorator to register a function as a resource. The function will be called when the resource is read to generate its content. The function can return:

str for text content
bytes for binary content
other types will be converted to JSON

Resources can optionally request a Context object by adding a parameter with the Context type annotation. The context provides access to MCP capabilities like logging, progress reporting, and session information. If the URI contains parameters (e.g. “resource://”) or the function has parameters, it will be registered as a template resource. Args:

uri: URI for the resource (e.g. “resource://my-resource” or “resource://”)
name: Optional name for the resource
description: Optional description of the resource
mime_type: Optional MIME type for the resource
tags: Optional set of tags for categorizing the resource
enabled: Optional boolean to enable or disable the resource
annotations: Optional annotations about the resource’s behavior
meta: Optional meta information about the resource

Examples: Register a resource with a custom name:

@server.resource("resource://my-resource")
def get_data() -> str:
    return "Hello, world!"

@server.resource("resource://my-resource")
async get_data() -> str:
    data = await fetch_data()
    return f"Hello, world! {data}"

@server.resource("resource://{city}/weather")
def get_weather(city: str) -> str:
    return f"Weather for {city}"

@server.resource("resource://{city}/weather")
def get_weather_with_context(city: str, ctx: Context) -> str:
    ctx.info(f"Fetching weather for {city}")
    return f"Weather for {city}"

@server.resource("resource://{city}/weather")
async def get_weather(city: str) -> str:
    data = await fetch_weather(city)
    return f"Weather for {city}: {data}"

`add_prompt`

add_prompt(self, prompt: Prompt) -> Prompt

Add a prompt to the server. Args:

prompt: A Prompt instance to add

Returns:

The prompt instance that was added to the server.

`prompt`

prompt(self, name_or_fn: AnyFunction) -> FunctionPrompt

`prompt`

prompt(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionPrompt]

`prompt`

prompt(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt

Decorator to register a prompt. Prompts can optionally request a Context object by adding a parameter with the Context type annotation. The context provides access to MCP capabilities like logging, progress reporting, and session information. This decorator supports multiple calling patterns:

@server.prompt (without parentheses)
@server.prompt() (with empty parentheses)
@server.prompt(“custom_name”) (with name as first argument)
@server.prompt(name=“custom_name”) (with name as keyword argument)
server.prompt(function, name=“custom_name”) (direct function call)

Args: name_or_fn: Either a function (when used as @prompt), a string name, or None name: Optional name for the prompt (keyword-only, alternative to name_or_fn) description: Optional description of what the prompt does tags: Optional set of tags for categorizing the prompt enabled: Optional boolean to enable or disable the prompt meta: Optional meta information about the prompt Examples:

@server.prompt
def analyze_table(table_name: str) -> list[Message]:
    schema = read_table_schema(table_name)
    return [
        {
            "role": "user",
            "content": f"Analyze this schema:
{schema}"
        }
    ]

@server.prompt()
def analyze_with_context(table_name: str, ctx: Context) -> list[Message]:
    ctx.info(f"Analyzing table {table_name}")
    schema = read_table_schema(table_name)
    return [
        {
            "role": "user",
            "content": f"Analyze this schema:
{schema}"
        }
    ]

@server.prompt("custom_name")
def analyze_file(path: str) -> list[Message]:
    content = await read_file(path)
    return [
        {
            "role": "user",
            "content": {
                "type": "resource",
                "resource": {
                    "uri": f"file://{path}",
                    "text": content
                }
            }
        }
    ]

@server.prompt(name="custom_name")
def another_prompt(data: str) -> list[Message]:
    return [{"role": "user", "content": data}]

# Direct function call
server.prompt(my_function, name="custom_name")

`run_stdio_async`

run_stdio_async(self, show_banner: bool = True) -> None

Run the server using stdio transport.

`run_http_async`

run_http_async(self, show_banner: bool = True, transport: Literal['http', 'streamable-http', 'sse'] = 'http', host: str | None = None, port: int | None = None, log_level: str | None = None, path: str | None = None, uvicorn_config: dict[str, Any] | None = None, middleware: list[ASGIMiddleware] | None = None, stateless_http: bool | None = None) -> None

Run the server using HTTP transport. Args:

transport: Transport protocol to use - either “streamable-http” (default) or “sse”
host: Host address to bind to (defaults to settings.host)
port: Port to bind to (defaults to settings.port)
log_level: Log level for the server (defaults to settings.log_level)
path: Path for the endpoint (defaults to settings.streamable_http_path or settings.sse_path)
uvicorn_config: Additional configuration for the Uvicorn server
middleware: A list of middleware to apply to the app
stateless_http: Whether to use stateless HTTP (defaults to settings.stateless_http)

`run_sse_async`

run_sse_async(self, host: str | None = None, port: int | None = None, log_level: str | None = None, path: str | None = None, uvicorn_config: dict[str, Any] | None = None) -> None

Run the server using SSE transport.

`sse_app`

sse_app(self, path: str | None = None, message_path: str | None = None, middleware: list[ASGIMiddleware] | None = None) -> StarletteWithLifespan

Create a Starlette app for the SSE server. Args:

path: The path to the SSE endpoint
message_path: The path to the message endpoint
middleware: A list of middleware to apply to the app

`streamable_http_app`

streamable_http_app(self, path: str | None = None, middleware: list[ASGIMiddleware] | None = None) -> StarletteWithLifespan

Create a Starlette app for the StreamableHTTP server. Args:

path: The path to the StreamableHTTP endpoint
middleware: A list of middleware to apply to the app

`http_app`

http_app(self, path: str | None = None, middleware: list[ASGIMiddleware] | None = None, json_response: bool | None = None, stateless_http: bool | None = None, transport: Literal['http', 'streamable-http', 'sse'] = 'http') -> StarletteWithLifespan

Create a Starlette app using the specified HTTP transport. Args:

path: The path for the HTTP endpoint
middleware: A list of middleware to apply to the app
transport: Transport protocol to use - either “streamable-http” (default) or “sse”

Returns:

A Starlette application configured with the specified transport

`run_streamable_http_async`

run_streamable_http_async(self, host: str | None = None, port: int | None = None, log_level: str | None = None, path: str | None = None, uvicorn_config: dict[str, Any] | None = None) -> None

`mount`

mount(self, server: FastMCP[LifespanResultT], prefix: str | None = None, as_proxy: bool | None = None) -> None

Mount another FastMCP server on this server with an optional prefix. Unlike importing (with import_server), mounting establishes a dynamic connection between servers. When a client interacts with a mounted server’s objects through the parent server, requests are forwarded to the mounted server in real-time. This means changes to the mounted server are immediately reflected when accessed through the parent. When a server is mounted with a prefix:

Tools from the mounted server are accessible with prefixed names. Example: If server has a tool named “get_weather”, it will be available as “prefix_get_weather”.
Resources are accessible with prefixed URIs. Example: If server has a resource with URI “weather://forecast”, it will be available as “weather://prefix/forecast”.
Templates are accessible with prefixed URI templates. Example: If server has a template with URI “weather://location/”, it will be available as “weather://prefix/location/”.
Prompts are accessible with prefixed names. Example: If server has a prompt named “weather_prompt”, it will be available as “prefix_weather_prompt”.

When a server is mounted without a prefix (prefix=None), its tools, resources, templates, and prompts are accessible with their original names. Multiple servers can be mounted without prefixes, and they will be tried in order until a match is found. There are two modes for mounting servers:

Direct mounting (default when server has no custom lifespan): The parent server directly accesses the mounted server’s objects in-memory for better performance. In this mode, no client lifecycle events occur on the mounted server, including lifespan execution.
Proxy mounting (default when server has a custom lifespan): The parent server treats the mounted server as a separate entity and communicates with it via a Client transport. This preserves all client-facing behaviors, including lifespan execution, but with slightly higher overhead.

Args:

server: The FastMCP server to mount.
prefix: Optional prefix to use for the mounted server’s objects. If None, the server’s objects are accessible with their original names.
as_proxy: Whether to treat the mounted server as a proxy. If None (default), automatically determined based on whether the server has a custom lifespan (True if it has a custom lifespan, False otherwise).
tool_separator: Deprecated. Separator character for tool names.
resource_separator: Deprecated. Separator character for resource URIs.
prompt_separator: Deprecated. Separator character for prompt names.

`import_server`

import_server(self, server: FastMCP[LifespanResultT], prefix: str | None = None, tool_separator: str | None = None, resource_separator: str | None = None, prompt_separator: str | None = None) -> None

Import the MCP objects from another FastMCP server into this one, optionally with a given prefix. Note that when a server is imported, its objects are immediately registered to the importing server. This is a one-time operation and future changes to the imported server will not be reflected in the importing server. Server-level configurations and lifespans are not imported. When a server is imported with a prefix:

The tools are imported with prefixed names Example: If server has a tool named “get_weather”, it will be available as “prefix_get_weather”
The resources are imported with prefixed URIs using the new format Example: If server has a resource with URI “weather://forecast”, it will be available as “weather://prefix/forecast”
The templates are imported with prefixed URI templates using the new format Example: If server has a template with URI “weather://location/”, it will be available as “weather://prefix/location/”
The prompts are imported with prefixed names Example: If server has a prompt named “weather_prompt”, it will be available as “prefix_weather_prompt”

When a server is imported without a prefix (prefix=None), its tools, resources, templates, and prompts are imported with their original names. Args:

server: The FastMCP server to import
prefix: Optional prefix to use for the imported server’s objects. If None, objects are imported with their original names.
tool_separator: Deprecated. Separator for tool names.
resource_separator: Deprecated and ignored. Prefix is now applied using the protocol://prefix/path format
prompt_separator: Deprecated. Separator for prompt names.

`from_openapi`

from_openapi(cls, openapi_spec: dict[str, Any], client: httpx.AsyncClient, route_maps: list[RouteMap] | list[RouteMapNew] | None = None, route_map_fn: OpenAPIRouteMapFn | OpenAPIRouteMapFnNew | None = None, mcp_component_fn: OpenAPIComponentFn | OpenAPIComponentFnNew | None = None, mcp_names: dict[str, str] | None = None, tags: set[str] | None = None, **settings: Any) -> FastMCPOpenAPI | FastMCPOpenAPINew

Create a FastMCP server from an OpenAPI specification.

`from_fastapi`

from_fastapi(cls, app: Any, name: str | None = None, route_maps: list[RouteMap] | list[RouteMapNew] | None = None, route_map_fn: OpenAPIRouteMapFn | OpenAPIRouteMapFnNew | None = None, mcp_component_fn: OpenAPIComponentFn | OpenAPIComponentFnNew | None = None, mcp_names: dict[str, str] | None = None, httpx_client_kwargs: dict[str, Any] | None = None, tags: set[str] | None = None, **settings: Any) -> FastMCPOpenAPI | FastMCPOpenAPINew

Create a FastMCP server from a FastAPI application.

`as_proxy`

as_proxy(cls, backend: Client[ClientTransportT] | ClientTransport | FastMCP[Any] | AnyUrl | Path | MCPConfig | dict[str, Any] | str, **settings: Any) -> FastMCPProxy

Create a FastMCP proxy server for the given backend. The backend argument can be either an existing fastmcp.client.Client instance or any value accepted as the transport argument of fastmcp.client.Client. This mirrors the convenience of the fastmcp.client.Client constructor.

`from_client`

from_client(cls, client: Client[ClientTransportT], **settings: Any) -> FastMCPProxy

Create a FastMCP proxy server from a FastMCP client.

`generate_name`

generate_name(cls, name: str | None = None) -> str

fastmcp.cli

fastmcp.client

fastmcp.prompts

fastmcp.resources

fastmcp.server

fastmcp.tools

fastmcp.utilities

​fastmcp.server.server

​Functions

​default_lifespan

​add_resource_prefix

​remove_resource_prefix

​has_resource_prefix

​Classes

​FastMCP

​settings

​name

​instructions

​version

​run_async

​run

​add_middleware

​get_tools

​get_tool

​get_resources

​get_resource

​get_resource_templates

​get_resource_template

​get_prompts

​get_prompt

​custom_route

​add_tool

​remove_tool

​add_tool_transformation

​remove_tool_transformation

​tool

​tool

​tool

​add_resource

​add_template

​add_resource_fn

​resource

​add_prompt

​prompt

​prompt

​prompt

​run_stdio_async

​run_http_async

​run_sse_async

​sse_app

​streamable_http_app

​http_app

​run_streamable_http_async

​mount

​import_server

​from_openapi

​from_fastapi

​as_proxy

​from_client

​generate_name

​MountedServer

`fastmcp.server.server`

Functions

`default_lifespan`

`add_resource_prefix`

`remove_resource_prefix`

`has_resource_prefix`

Classes

`FastMCP`

`settings`

`name`

`instructions`

`version`

`run_async`

`run`

`add_middleware`

`get_tools`

`get_tool`

`get_resources`

`get_resource`

`get_resource_templates`

`get_resource_template`

`get_prompts`

`get_prompt`

`custom_route`

`add_tool`

`remove_tool`

`add_tool_transformation`

`remove_tool_transformation`

`tool`

`tool`

`tool`

`add_resource`

`add_template`

`add_resource_fn`

`resource`

`add_prompt`

`prompt`

`prompt`

`prompt`

`run_stdio_async`

`run_http_async`

`run_sse_async`

`sse_app`

`streamable_http_app`

`http_app`

`run_streamable_http_async`

`mount`

`import_server`

`from_openapi`

`from_fastapi`

`as_proxy`

`from_client`

`generate_name`

`MountedServer`