context

fastmcp.server.context

Functions

set_context

set_context(context: Context) -> Generator[Context, None, None]

Classes

LogData

Data object for passing log arguments to client-side handlers.

This provides an interface to match the Python standard library logging, for compatibility with structured logging.

Context

Context object providing access to MCP capabilities.

This provides a cleaner interface to MCP’s RequestContext functionality. It gets injected into tool and resource functions that request it via type hints.

To use context in a tool function, add a parameter with the Context type annotation:

@server.tool
async def my_tool(x: int, ctx: Context) -> str:
    # Log messages to the client
    await ctx.info(f"Processing {x}")
    await ctx.debug("Debug info")
    await ctx.warning("Warning message")
    await ctx.error("Error message")

    # Report progress
    await ctx.report_progress(50, 100, "Processing")

    # Access resources
    data = await ctx.read_resource("resource://data")

    # Get request info
    request_id = ctx.request_id
    client_id = ctx.client_id

    # Manage state across the request
    ctx.set_state("key", "value")
    value = ctx.get_state("key")

    return str(x)

State Management: Context objects maintain a state dictionary that can be used to store and share data across middleware and tool calls within a request. When a new context is created (nested contexts), it inherits a copy of its parent’s state, ensuring that modifications in child contexts don’t affect parent contexts.

The context parameter name can be anything as long as it’s annotated with Context. The context is optional - tools that don’t need it can omit the parameter.

Methods:

fastmcp

fastmcp(self) -> FastMCP

Get the FastMCP instance.

request_context

request_context(self) -> RequestContext[ServerSession, Any, Request]

Access to the underlying request context.

If called outside of a request context, this will raise a ValueError.

report_progress

report_progress(self, progress: float, total: float | None = None, message: str | None = None) -> None

Report progress for the current operation.

Args:

• progress: Current progress value e.g. 24
• total: Optional total value e.g. 100

read_resource

read_resource(self, uri: str | AnyUrl) -> list[ReadResourceContents]

Read a resource by URI.

Args:

• uri: Resource URI to read

Returns:

• The resource content as either text or bytes

log

log(self, message: str, level: LoggingLevel | None = None, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None

Send a log message to the client.

Args:

• message: Log message
• level: Optional log level. One of “debug”, “info”, “notice”, “warning”, “error”, “critical”, “alert”, or “emergency”. Default is “info”.
• logger_name: Optional logger name
• extra: Optional mapping for additional arguments

client_id

client_id(self) -> str | None

Get the client ID if available.

request_id

request_id(self) -> str

Get the unique ID for this request.

session_id

session_id(self) -> str

Get the MCP session ID for ALL transports.

Returns the session ID that can be used as a key for session-based data storage (e.g., Redis) to share data between tool calls within the same client session.

Returns:

• The session ID for StreamableHTTP transports, or a generated ID
• for other transports.

session

session(self) -> ServerSession

Access to the underlying session for advanced usage.

debug

debug(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None

Send a debug log message.

info

info(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None

Send an info log message.

warning

warning(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None

Send a warning log message.

error

error(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None

Send an error log message.

list_roots

list_roots(self) -> list[Root]

List the roots available to the server, as indicated by the client.

send_tool_list_changed

send_tool_list_changed(self) -> None

Send a tool list changed notification to the client.

send_resource_list_changed

send_resource_list_changed(self) -> None

Send a resource list changed notification to the client.

send_prompt_list_changed

send_prompt_list_changed(self) -> None

Send a prompt list changed notification to the client.

sample

sample(self, messages: str | Sequence[str | SamplingMessage], system_prompt: str | None = None, include_context: IncludeContext | None = None, temperature: float | None = None, max_tokens: int | None = None, model_preferences: ModelPreferences | str | list[str] | None = None) -> TextContent | ImageContent | AudioContent

Send a sampling request to the client and await the response.

Call this method at any time to have the server request an LLM completion from the client. The client must be appropriately configured, or the request will error.

elicit

elicit(self, message: str, response_type: None) -> AcceptedElicitation[dict[str, Any]] | DeclinedElicitation | CancelledElicitation

elicit

elicit(self, message: str, response_type: type[T]) -> AcceptedElicitation[T] | DeclinedElicitation | CancelledElicitation

elicit

elicit(self, message: str, response_type: list[str]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation

elicit

elicit(self, message: str, response_type: type[T] | list[str] | None = None) -> AcceptedElicitation[T] | AcceptedElicitation[dict[str, Any]] | AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation

Send an elicitation request to the client and await the response.

Call this method at any time to request additional information from the user through the client. The client must support elicitation, or the request will error.

Note that the MCP protocol only supports simple object schemas with primitive types. You can provide a dataclass, TypedDict, or BaseModel to comply. If you provide a primitive type, an object schema with a single “value” field will be generated for the MCP interaction and automatically deconstructed into the primitive type upon response.

If the response_type is None, the generated schema will be that of an empty object in order to comply with the MCP protocol requirements. Clients must send an empty object ("")in response.

Args:

• message: A human-readable message explaining what information is needed
• response_type: The type of the response, which should be a primitive type or dataclass or BaseModel. If it is a primitive type, an object schema with a single “value” field will be generated.

get_http_request

get_http_request(self) -> Request

Get the active starlette request.

set_state

set_state(self, key: str, value: Any) -> None

Set a value in the context state.

get_state

get_state(self, key: str) -> Any

Get a value from the context state. Returns None if the key is not found.