Skip to main content

​
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] | None
Access to the underlying request context. Returns None when the MCP session has not been established yet. Returns the full RequestContext once the MCP session is available. For HTTP request access in middleware, use get_http_request() from fastmcp.server.dependencies, which works whether or not the MCP session is available. Example in middleware: 
async def on_request(self, context, call_next):
    ctx = context.fastmcp_context
    if ctx.request_context:
        # MCP session available - can access session_id, request_id, etc.
        session_id = ctx.session_id
    else:
        # MCP session not available yet - use HTTP helpers
        from fastmcp.server.dependencies import get_http_request
        request = get_http_request()
    return await call_next(context)

​
lifespan_context 

lifespan_context(self) -> dict[str, Any]
Access the server’s lifespan context. Returns the context dict yielded by the server’s lifespan function. Returns an empty dict if no lifespan was configured or if the MCP session is not yet established. Example: 
@server.tool
def my_tool(ctx: Context) -> str:
    db = ctx.lifespan_context.get("db")
    if db:
        return db.query("SELECT 1")
    return "No database connection"

​
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

​
list_resources 

list_resources(self) -> list[SDKResource]
List all available resources from the server. Returns:
  • List of Resource objects available on the server

​
list_prompts 

list_prompts(self) -> list[SDKPrompt]
List all available prompts from the server. Returns:
  • List of Prompt objects available on the server

​
get_prompt 

get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> GetPromptResult
Get a prompt by name with optional arguments. Args:
  • name: The name of the prompt to get
  • arguments: Optional arguments to pass to the prompt
Returns:
  • The prompt result

​
read_resource 

read_resource(self, uri: str | AnyUrl) -> ResourceResult
Read a resource by URI. Args:
  • uri: Resource URI to read
Returns:
  • ResourceResult with contents

​
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. Messages sent to Clients are also logged to the fastmcp.server.context.to_client logger with a level of DEBUG. 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. Raises RuntimeError if MCP request context is not available.

​
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. Raises RuntimeError if MCP request context is not available.

​
debug 

debug(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
Send a DEBUG-level message to the connected MCP Client. Messages sent to Clients are also logged to the fastmcp.server.context.to_client logger with a level of DEBUG.

​
info 

info(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
Send a INFO-level message to the connected MCP Client. Messages sent to Clients are also logged to the fastmcp.server.context.to_client logger with a level of DEBUG.

​
warning 

warning(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
Send a WARNING-level message to the connected MCP Client. Messages sent to Clients are also logged to the fastmcp.server.context.to_client logger with a level of DEBUG.

​
error 

error(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None
Send a ERROR-level message to the connected MCP Client. Messages sent to Clients are also logged to the fastmcp.server.context.to_client logger with a level of DEBUG.

​
list_roots 

list_roots(self) -> list[Root]
List the roots available to the server, as indicated by the client.

​
send_notification 

send_notification(self, notification: mcp.types.ServerNotificationType) -> None
Send a notification to the client immediately. Use this in async code when you want the notification sent right away. For sync code, use send_notification_sync() which queues the notification for the background flusher. Args:
  • notification: An MCP notification instance (e.g., ToolListChangedNotification())

​
send_notification_sync 

send_notification_sync(self, notification: mcp.types.ServerNotificationType) -> None
Queue a notification to be sent by the background flusher. Use this in sync code when you can’t await. The notification will be sent within ~1 second by the background flusher. Args:
  • notification: An MCP notification instance (e.g., ToolListChangedNotification())

​
close_sse_stream 

close_sse_stream(self) -> None
Close the current response stream to trigger client reconnection. When using StreamableHTTP transport with an EventStore configured, this method gracefully closes the HTTP connection for the current request. The client will automatically reconnect (after retry_interval milliseconds) and resume receiving events from where it left off via the EventStore. This is useful for long-running operations to avoid load balancer timeouts. Instead of holding a connection open for minutes, you can periodically close and let the client reconnect.

​
sample_step 

sample_step(self, messages: str | Sequence[str | SamplingMessage]) -> SampleStep
Make a single LLM sampling call. This is a stateless function that makes exactly one LLM call and optionally executes any requested tools. Use this for fine-grained control over the sampling loop. Args:
  • messages: The message(s) to send. Can be a string, list of strings, or list of SamplingMessage objects.
  • system_prompt: Optional system prompt for the LLM.
  • temperature: Optional sampling temperature.
  • max_tokens: Maximum tokens to generate. Defaults to 512.
  • model_preferences: Optional model preferences.
  • tools: Optional list of tools the LLM can use.
  • tool_choice: Tool choice mode (“auto”, “required”, or “none”).
  • execute_tools: If True (default), execute tool calls and append results to history. If False, return immediately with tool_calls available in the step for manual execution.
  • mask_error_details: If True, mask detailed error messages from tool execution. When None (default), uses the global settings value. Tools can raise ToolError to bypass masking.
Returns:
  • SampleStep containing:
    • .response: The raw LLM response
    • .history: Messages including input, assistant response, and tool results
    • .is_tool_use: True if the LLM requested tool execution
    • .tool_calls: List of tool calls (if any)
    • .text: The text content (if any)

​
sample 

sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[ResultT]
Overload: With result_type, returns SamplingResult[ResultT].

​
sample 

sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[str]
Overload: Without result_type, returns SamplingResult[str].

​
sample 

sample(self, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[ResultT] | SamplingResult[str]
Send a sampling request to the client and await the response. This method runs to completion automatically. When tools are provided, it executes a tool loop: if the LLM returns a tool use request, the tools are executed and the results are sent back to the LLM. This continues until the LLM provides a final text response. When result_type is specified, a synthetic final_response tool is created. The LLM calls this tool to provide the structured response, which is validated against the result_type and returned as .result. For fine-grained control over the sampling loop, use sample_step() instead. Args:
  • messages: The message(s) to send. Can be a string, list of strings, or list of SamplingMessage objects.
  • system_prompt: Optional system prompt for the LLM.
  • temperature: Optional sampling temperature.
  • max_tokens: Maximum tokens to generate. Defaults to 512.
  • model_preferences: Optional model preferences.
  • tools: Optional list of tools the LLM can use. Accepts plain functions or SamplingTools.
  • result_type: Optional type for structured output. When specified, a synthetic final_response tool is created and the LLM’s response is validated against this type.
  • mask_error_details: If True, mask detailed error messages from tool execution. When None (default), uses the global settings value. Tools can raise ToolError to bypass masking.
Returns:
  • SamplingResult[T] containing:
    • .text: The text representation (raw text or JSON for structured)
    • .result: The typed result (str for text, parsed object for structured)
    • .history: All messages exchanged during sampling

​
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: dict[str, dict[str, str]]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation

​
elicit 

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

​
elicit 

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

​
elicit 

elicit(self, message: str, response_type: type[T] | list[str] | dict[str, dict[str, str]] | list[list[str]] | list[dict[str, dict[str, str]]] | None = None) -> AcceptedElicitation[T] | AcceptedElicitation[dict[str, Any]] | AcceptedElicitation[str] | AcceptedElicitation[list[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.

​
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.