`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 dictionary as the lifespan result.

`create_proxy`

create_proxy(target: Client[ClientTransportT] | ClientTransport | FastMCP[Any] | FastMCP1Server | AnyUrl | Path | MCPConfig | dict[str, Any] | str, **settings: Any) -> FastMCPProxy

Create a FastMCP proxy server for the given target. This is the recommended way to create a proxy server. For lower-level control, use FastMCPProxy or ProxyProvider directly from fastmcp.server.providers.proxy. Args:

target: The backend to proxy to. Can be:
A Client instance (connected or disconnected)
A ClientTransport
A FastMCP server instance
A URL string or AnyUrl
A Path to a server script
An MCPConfig or dict
**settings: Additional settings passed to FastMCPProxy (name, etc.)

Returns:

A FastMCPProxy server that proxies to the target.

Classes

`StateValue`

Wrapper for stored context state values.

`FastMCP`

Methods:

`settings`

settings(self) -> Settings

`name`

name(self) -> str

`instructions`

instructions(self) -> str | None

`instructions`

instructions(self, value: str | None) -> None

`version`

version(self) -> str | None

`website_url`

website_url(self) -> str | None

`icons`

icons(self) -> list[mcp.types.Icon]

`add_middleware`

add_middleware(self, middleware: Middleware) -> None

`add_provider`

add_provider(self, provider: Provider) -> None

Add a provider for dynamic tools, resources, and prompts. Providers are queried in registration order. The first provider to return a non-None result wins. Static components (registered via decorators) always take precedence over providers. Args:

provider: A Provider instance that will provide components dynamically.
namespace: Optional namespace prefix. When set:
Tools become “namespace_toolname”
Resources become “protocol://namespace/path”
Prompts become “namespace_promptname”

`get_tasks`

get_tasks(self) -> Sequence[FastMCPComponent]

Get task-eligible components with all transforms applied. Overrides AggregateProvider.get_tasks() to apply server-level transforms after aggregation. AggregateProvider handles provider-level namespacing.

`add_transform`

add_transform(self, transform: Transform) -> None

Add a server-level transform. Server-level transforms are applied after all providers are aggregated. They transform tools, resources, and prompts from ALL providers. Args:

transform: The transform to add.

`add_tool_transformation`

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

Add a tool transformation. .. deprecated:: Use add_transform(ToolTransform({...})) instead.

`remove_tool_transformation`

remove_tool_transformation(self, _tool_name: str) -> None

Remove a tool transformation. .. deprecated:: Tool transformations are now immutable. Use enable/disable controls instead.

`list_tools`

list_tools(self) -> Sequence[Tool]

List all enabled tools from providers. Overrides Provider.list_tools() to add visibility filtering, auth filtering, and middleware execution. Returns all versions (no deduplication). Protocol handlers deduplicate for MCP wire format.

`get_tool`

get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None

Get a tool by name, filtering disabled tools. Overrides Provider.get_tool() to add visibility filtering after all transforms (including session-level) have been applied. This ensures session transforms can override provider-level disables. Args:

name: The tool name.
version: Version filter (None returns highest version).

Returns:

The tool if found and enabled, None otherwise.

`list_resources`

list_resources(self) -> Sequence[Resource]

List all enabled resources from providers. Overrides Provider.list_resources() to add visibility filtering, auth filtering, and middleware execution. Returns all versions (no deduplication). Protocol handlers deduplicate for MCP wire format.

`get_resource`

get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | None

Get a resource by URI, filtering disabled resources. Overrides Provider.get_resource() to add visibility filtering after all transforms (including session-level) have been applied. Args:

uri: The resource URI.
version: Version filter (None returns highest version).

Returns:

The resource if found and enabled, None otherwise.

`list_resource_templates`

list_resource_templates(self) -> Sequence[ResourceTemplate]

List all enabled resource templates from providers. Overrides Provider.list_resource_templates() to add visibility filtering, auth filtering, and middleware execution. Returns all versions (no deduplication). Protocol handlers deduplicate for MCP wire format.

`get_resource_template`

get_resource_template(self, uri: str, version: VersionSpec | None = None) -> ResourceTemplate | None

Get a resource template by URI, filtering disabled templates. Overrides Provider.get_resource_template() to add visibility filtering after all transforms (including session-level) have been applied. Args:

uri: The template URI.
version: Version filter (None returns highest version).

Returns:

The template if found and enabled, None otherwise.

`list_prompts`

list_prompts(self) -> Sequence[Prompt]

List all enabled prompts from providers. Overrides Provider.list_prompts() to add visibility filtering, auth filtering, and middleware execution. Returns all versions (no deduplication). Protocol handlers deduplicate for MCP wire format.

`get_prompt`

get_prompt(self, name: str, version: VersionSpec | None = None) -> Prompt | None

Get a prompt by name, filtering disabled prompts. Overrides Provider.get_prompt() to add visibility filtering after all transforms (including session-level) have been applied. Args:

name: The prompt name.
version: Version filter (None returns highest version).

Returns:

The prompt if found and enabled, None otherwise.

`call_tool`

call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> ToolResult

`call_tool`

call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.CreateTaskResult

`call_tool`

call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> ToolResult | mcp.types.CreateTaskResult

Call a tool by name. This is the public API for executing tools. By default, middleware is applied. Args:

name: The tool name
arguments: Tool arguments (optional)
version: Specific version to call. If None, calls highest version.
run_middleware: If True (default), apply the middleware chain. Set to False when called from middleware to avoid re-applying.
task_meta: If provided, execute as a background task and return CreateTaskResult. If None (default), execute synchronously and return ToolResult.

Returns:

ToolResult when task_meta is None.
CreateTaskResult when task_meta is provided.

Raises:

NotFoundError: If tool not found or disabled
ToolError: If tool execution fails
ValidationError: If arguments fail validation

`read_resource`

read_resource(self, uri: str) -> ResourceResult

`read_resource`

read_resource(self, uri: str) -> mcp.types.CreateTaskResult

`read_resource`

read_resource(self, uri: str) -> ResourceResult | mcp.types.CreateTaskResult

Read a resource by URI. This is the public API for reading resources. By default, middleware is applied. Checks concrete resources first, then templates. Args:

uri: The resource URI
version: Specific version to read. If None, reads highest version.
run_middleware: If True (default), apply the middleware chain. Set to False when called from middleware to avoid re-applying.
task_meta: If provided, execute as a background task and return CreateTaskResult. If None (default), execute synchronously and return ResourceResult.

Returns:

ResourceResult when task_meta is None.
CreateTaskResult when task_meta is provided.

Raises:

NotFoundError: If resource not found or disabled
ResourceError: If resource read fails

`render_prompt`

render_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> PromptResult

`render_prompt`

render_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> mcp.types.CreateTaskResult

`render_prompt`

render_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> PromptResult | mcp.types.CreateTaskResult

Render a prompt by name. This is the public API for rendering prompts. By default, middleware is applied. Use get_prompt() to retrieve the prompt definition without rendering. Args:

name: The prompt name
arguments: Prompt arguments (optional)
version: Specific version to render. If None, renders highest version.
run_middleware: If True (default), apply the middleware chain. Set to False when called from middleware to avoid re-applying.
task_meta: If provided, execute as a background task and return CreateTaskResult. If None (default), execute synchronously and return PromptResult.

Returns:

PromptResult when task_meta is None.
CreateTaskResult when task_meta is provided.

Raises:

NotFoundError: If prompt not found or disabled
PromptError: If prompt rendering fails

`add_tool`

add_tool(self, tool: Tool | Callable[..., Any]) -> 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 or @tool-decorated function to register

Returns:

The tool instance that was added to the server.

`remove_tool`

remove_tool(self, name: str, version: str | None = None) -> None

Remove tool(s) from the server. Args:

name: The name of the tool to remove.
version: If None, removes ALL versions. If specified, removes only that version.

Raises:

NotFoundError: If no matching tool is found.

`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 | partial[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. Deprecated: Use Depends() for dependency injection instead.
meta: Optional meta information about 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 | Callable[..., Any]) -> Resource | ResourceTemplate

Add a resource to the server. Args:

resource: A Resource instance or @resource-decorated function 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.

`resource`

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

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
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")
async def get_weather_with_context(city: str, ctx: Context) -> str:
    await 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 | Callable[..., Any]) -> Prompt

Add a prompt to the server. Args:

prompt: A Prompt instance or @prompt-decorated function 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 | partial[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 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()
async def analyze_with_context(table_name: str, ctx: Context) -> list[Message]:
    await 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")
async 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")

`mount`

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

Mount another FastMCP server on this server with an optional namespace. 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 namespace:

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

When a server is mounted without a namespace (namespace=None), its tools, resources, templates, and prompts are accessible with their original names. Multiple servers can be mounted without namespaces, and they will be tried in order until a match is found. The mounted server’s lifespan is executed when the parent server starts, and its middleware chain is invoked for all operations (tool calls, resource reads, prompts). Args:

server: The FastMCP server to mount.
namespace: Optional namespace to use for the mounted server’s objects. If None, the server’s objects are accessible with their original names.
as_proxy: Deprecated. Mounted servers now always have their lifespan and middleware invoked. To create a proxy server, use create_proxy() explicitly before mounting.
tool_names: Optional mapping of original tool names to custom names. Use this to override namespaced names. Keys are the original tool names from the mounted server.
prefix: Deprecated. Use namespace instead.

`import_server`

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

Import the MCP objects from another FastMCP server into this one, optionally with a given prefix. .. deprecated:: Use :meth:mount instead. import_server will be removed in a future version. 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.

`from_openapi`

from_openapi(cls, openapi_spec: dict[str, Any], client: httpx.AsyncClient, name: str = 'OpenAPI Server', route_maps: list[RouteMap] | None = None, route_map_fn: OpenAPIRouteMapFn | None = None, mcp_component_fn: OpenAPIComponentFn | None = None, mcp_names: dict[str, str] | None = None, tags: set[str] | None = None, timeout: float | None = None, **settings: Any) -> Self

Create a FastMCP server from an OpenAPI specification. Args:

openapi_spec: OpenAPI schema as a dictionary
client: httpx AsyncClient for making HTTP requests
name: Name for the MCP server
route_maps: Optional list of RouteMap objects defining route mappings
route_map_fn: Optional callable for advanced route type mapping
mcp_component_fn: Optional callable for component customization
mcp_names: Optional dictionary mapping operationId to component names
tags: Optional set of tags to add to all components
timeout: Optional timeout (in seconds) for all requests
**settings: Additional settings passed to FastMCP

Returns:

A FastMCP server with an OpenAPIProvider attached.

`from_fastapi`

from_fastapi(cls, app: Any, name: str | None = None, route_maps: list[RouteMap] | None = None, route_map_fn: OpenAPIRouteMapFn | None = None, mcp_component_fn: OpenAPIComponentFn | None = None, mcp_names: dict[str, str] | None = None, httpx_client_kwargs: dict[str, Any] | None = None, tags: set[str] | None = None, timeout: float | None = None, **settings: Any) -> Self

Create a FastMCP server from a FastAPI application. Args:

app: FastAPI application instance
name: Name for the MCP server (defaults to app.title)
route_maps: Optional list of RouteMap objects defining route mappings
route_map_fn: Optional callable for advanced route type mapping
mcp_component_fn: Optional callable for component customization
mcp_names: Optional dictionary mapping operationId to component names
httpx_client_kwargs: Optional kwargs passed to httpx.AsyncClient
tags: Optional set of tags to add to all components
timeout: Optional timeout (in seconds) for all requests
**settings: Additional settings passed to FastMCP

Returns:

A FastMCP server with an OpenAPIProvider attached.

`as_proxy`

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

Create a FastMCP proxy server for the given backend. .. deprecated:: Use :func:fastmcp.server.create_proxy instead. This method will be removed in a future version. 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.

`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

​create_proxy

​Classes

​StateValue

​FastMCP

​settings

​name

​instructions

​instructions

​version

​website_url

​icons

​add_middleware

​add_provider

​get_tasks

​add_transform

​add_tool_transformation

​remove_tool_transformation

​list_tools

​get_tool

​list_resources

​get_resource

​list_resource_templates

​get_resource_template

​list_prompts

​get_prompt

​call_tool

​call_tool

​call_tool

​read_resource

​read_resource

​read_resource

​render_prompt

​render_prompt

​render_prompt

​add_tool

​remove_tool

​tool

​tool

​tool

​add_resource

​add_template

​resource

​add_prompt

​prompt

​prompt

​prompt

​mount

​import_server

​from_openapi

​from_fastapi

​as_proxy

​generate_name

`fastmcp.server.server`

Functions

`default_lifespan`

`create_proxy`

Classes

`StateValue`

`FastMCP`

`settings`

`name`

`instructions`

`instructions`

`version`

`website_url`

`icons`

`add_middleware`

`add_provider`

`get_tasks`

`add_transform`

`add_tool_transformation`

`remove_tool_transformation`

`list_tools`

`get_tool`

`list_resources`

`get_resource`

`list_resource_templates`

`get_resource_template`

`list_prompts`

`get_prompt`

`call_tool`

`call_tool`

`call_tool`

`read_resource`

`read_resource`

`read_resource`

`render_prompt`

`render_prompt`

`render_prompt`

`add_tool`

`remove_tool`

`tool`

`tool`

`tool`

`add_resource`

`add_template`

`resource`

`add_prompt`

`prompt`

`prompt`

`prompt`

`mount`

`import_server`

`from_openapi`

`from_fastapi`

`as_proxy`

`generate_name`