When defining FastMCP tools, resources, resource templates, or prompts, your functions might need to interact with the underlying MCP session or access advanced server capabilities. FastMCP provides the Context
object for this purpose.
What Is Context?
The Context
object provides a clean interface to access MCP features within your functions, including:
- Logging: Send debug, info, warning, and error messages back to the client
- Progress Reporting: Update the client on the progress of long-running operations
- Resource Access: Read data from resources registered with the server
- LLM Sampling: Request the clientβs LLM to generate text based on provided messages
- User Elicitation: Request structured input from users during tool execution
- Request Information: Access metadata about the current request
- Server Access: When needed, access the underlying FastMCP server instance
Accessing the Context
Via Dependency Injection
To use the context object within any of your functions, simply add a parameter to your function signature and type-hint it as Context
. FastMCP will automatically inject the context instance when your function is called.
Key Points:
- The parameter name (e.g.,
ctx
, context
) doesnβt matter, only the type hint Context
is important.
- The context parameter can be placed anywhere in your functionβs signature; it will not be exposed to MCP clients as a valid parameter.
- The context is optional - functions that donβt need it can omit the parameter entirely.
- Context methods are async, so your function usually needs to be async as well.
- The type hint can be a union (
Context | None
) or use Annotated[]
and it will still work properly.
- Context is only available during a request; attempting to use context methods outside a request will raise errors. If you need to debug or call your context methods outside of a request, you can type your variable as
Context | None=None
to avoid missing argument errors.
from fastmcp import FastMCP, Context
mcp = FastMCP(name="Context Demo")
@mcp.tool
async def process_file(file_uri: str, ctx: Context) -> str:
"""Processes a file, using context for logging and resource access."""
# Context is available as the ctx parameter
return "Processed file"
Resources and Templates
New in version:Β 2.2.5
from fastmcp import FastMCP, Context
mcp = FastMCP(name="Context Demo")
@mcp.resource("resource://user-data")
async def get_user_data(ctx: Context) -> dict:
"""Fetch personalized user data based on the request context."""
# Context is available as the ctx parameter
return {"user_id": "example"}
@mcp.resource("resource://users/{user_id}/profile")
async def get_user_profile(user_id: str, ctx: Context) -> dict:
"""Fetch user profile with context-aware logging."""
# Context is available as the ctx parameter
return {"id": user_id}
Prompts
New in version:Β 2.2.5
from fastmcp import FastMCP, Context
mcp = FastMCP(name="Context Demo")
@mcp.prompt
async def data_analysis_request(dataset: str, ctx: Context) -> str:
"""Generate a request to analyze data with contextual information."""
# Context is available as the ctx parameter
return f"Please analyze the following dataset: {dataset}"
Via Dependency Function
New in version:Β 2.2.11
While the simplest way to access context is through function parameter injection as shown above, there are cases where you need to access the context in code that may not be easy to modify to accept a context parameter, or that is nested deeper within your function calls.
FastMCP provides dependency functions that allow you to retrieve the active context from anywhere within a server requestβs execution flow:
from fastmcp import FastMCP
from fastmcp.server.dependencies import get_context
mcp = FastMCP(name="Dependency Demo")
# Utility function that needs context but doesn't receive it as a parameter
async def process_data(data: list[float]) -> dict:
# Get the active context - only works when called within a request
ctx = get_context()
await ctx.info(f"Processing {len(data)} data points")
@mcp.tool
async def analyze_dataset(dataset_name: str) -> dict:
# Call utility function that uses context internally
data = load_data(dataset_name)
await process_data(data)
Important Notes:
- The
get_context
function should only be used within the context of a server request. Calling it outside of a request will raise a RuntimeError
.
- The
get_context
function is server-only and should not be used in client code.
Context Capabilities
FastMCP provides several advanced capabilities through the context object. Each capability has dedicated documentation with comprehensive examples and best practices:
Logging
Send debug, info, warning, and error messages back to the MCP client for visibility into function execution.
await ctx.debug("Starting analysis")
await ctx.info(f"Processing {len(data)} items")
await ctx.warning("Deprecated parameter used")
await ctx.error("Processing failed")
See Server Logging for complete documentation and examples.
Client Elicitation
New in version:Β 2.10.0
Request structured input from clients during tool execution, enabling interactive workflows and progressive disclosure. This is a new feature in the 6/18/2025 MCP spec.
result = await ctx.elicit("Enter your name:", response_type=str)
if result.action == "accept":
name = result.data
See User Elicitation for detailed examples and supported response types.
LLM Sampling
New in version:Β 2.0.0
Request the clientβs LLM to generate text based on provided messages, useful for leveraging AI capabilities within your tools.
response = await ctx.sample("Analyze this data", temperature=0.7)
See LLM Sampling for comprehensive usage and advanced techniques.
Progress Reporting
Update clients on the progress of long-running operations, enabling progress indicators and better user experience.
await ctx.report_progress(progress=50, total=100) # 50% complete
See Progress Reporting for detailed patterns and examples.
Resource Access
Read data from resources registered with your FastMCP server, allowing access to files, configuration, or dynamic content.
content_list = await ctx.read_resource("resource://config")
content = content_list[0].content
Method signature:
ctx.read_resource(uri: str | AnyUrl) -> list[ReadResourceContents]
: Returns a list of resource content parts
Change Notifications
New in version:Β 2.9.1
FastMCP automatically sends list change notifications when components (such as tools, resources, or prompts) are added, removed, enabled, or disabled. In rare cases where you need to manually trigger these notifications, you can use the context methods:
@mcp.tool
async def custom_tool_management(ctx: Context) -> str:
"""Example of manual notification after custom tool changes."""
# After making custom changes to tools
await ctx.send_tool_list_changed()
await ctx.send_resource_list_changed()
await ctx.send_prompt_list_changed()
return "Notifications sent"
These methods are primarily used internally by FastMCPβs automatic notification system and most users will not need to invoke them directly.
FastMCP Server
To access the underlying FastMCP server instance, you can use the ctx.fastmcp
property:
@mcp.tool
async def my_tool(ctx: Context) -> None:
# Access the FastMCP server instance
server_name = ctx.fastmcp.name
...
MCP Request
Access metadata about the current request and client.
@mcp.tool
async def request_info(ctx: Context) -> dict:
"""Return information about the current request."""
return {
"request_id": ctx.request_id,
"client_id": ctx.client_id or "Unknown client"
}
Available Properties:
ctx.request_id -> str
: Get the unique ID for the current MCP request
ctx.client_id -> str | None
: Get the ID of the client making the request, if provided during initialization
ctx.session_id -> str | None
: Get the MCP session ID for session-based data sharing (HTTP transports only)
The MCP request is part of the low-level MCP SDK and intended for advanced use cases. Most users will not need to use it directly.