Explicit request context passed to handlers.
FastestMCP.Context is where FastestMCP makes runtime lifetimes visible
instead of hiding them behind injected globals or rewritten function
signatures.
A context carries four different kinds of state:
- request state - metadata and scratch values that live for one operation
- session state - values stored in a per-session process and reused across multiple requests
- auth state - principal, raw auth payload, and capability data resolved by
FastestMCP.Auth - task state - metadata needed when the current operation is running as a background task
- request metadata - a transport snapshot that can be exposed as
%FastestMCP.RequestContext{}
Example
FastestMCP.add_tool(server, "visit", fn _arguments, ctx ->
visits = FastestMCP.Context.get_session_state(ctx, :visits, 0) + 1
:ok = FastestMCP.Context.put_session_state(ctx, :visits, visits)
%{
visits: visits,
server: ctx.server_name
}
end)Why The Context Is Explicit
Handler signatures stay honest. If a tool depends on session state, auth result, request headers, or progress reporting, you can see that dependency in the function body immediately. That keeps the runtime easier to debug and easier to reason about when the request crosses transport boundaries or moves into background-task execution.
Convenience Helpers
FastestMCP exposes a few narrow convenience helpers for nested runtime code:
FastestMCP.add_tool(server, "explicit", fn _arguments, ctx ->
request = FastestMCP.Context.request_context(ctx)
%{
request_id: request.request_id,
client_id: FastestMCP.Context.client_id(ctx),
path: request.path
}
end)For nested helpers where passing ctx through every layer is noisy:
defmodule MyApp.ReleaseHelpers do
def current_request_summary do
ctx = FastestMCP.Context.current!()
request = FastestMCP.Context.request_context(ctx)
%{request_id: request.request_id, transport: request.transport}
end
endThe recommended default is still explicit handler ctx. current/0 and
current!/0 are convenience helpers for nested runtime code, not a hidden
global programming model.
Summary
Functions
Returns the current access token available on the context.
Returns whether the context belongs to background-task execution.
Builds the base metadata shared across telemetry and event emission.
Builds the value managed by this module from runtime state and options.
Returns the authenticated client identifier when one is available.
Returns the current request context for the calling process.
Returns the current request context or raises when no request is active.
Emits a debug log event from this context.
Deletes one request-scoped value from the context.
Deletes state for the current context.
Returns the dependency map available on the context.
Resolves one named dependency from the context.
Disables matching components for the current session only.
Requests interactive input for a background task.
Emits telemetry and local runtime events for this context.
Enables matching components for the current session only.
Emits an error log event from this context.
Builds a derived context for background-task execution.
Reads request-scoped state from the context.
Reads session-scoped state for the current session.
Reads state for the current context.
Returns HTTP headers captured on the current request context.
Returns the immutable HTTP request snapshot for this context.
Emits an info log event from this context.
Returns whether the context belongs to background-task execution.
Lists visible prompts using the current request context.
Lists visible resources using the current request context.
Emits a log event from this context.
Notifies subscribed sessions that one concrete resource URI changed.
Returns the original request id that created the background task, if any.
Builds a progress helper for this context.
Stores a resolved auth result on the context.
Stores request-scoped state on the context.
Stores session-scoped state for the current session.
Reads a resource using the current request context.
Renders a prompt using the current request context.
Records a progress update.
Builds a stable request-context snapshot from the current context.
Clears all session visibility rules.
Runs a sampling request from this context.
Sends a raw MCP notification to the connected client session stream.
Builds a new server definition.
Stores state for the current context.
Returns the current background-task id, if any.
Returns the background-task store attached to the context, if present.
Emits a warning log event from this context.
Runs the given function with this context installed as the current request context.
Types
@type t() :: %FastestMCP.Context{ auth: map(), capabilities: [any()], dependencies: map(), event_bus: pid() | atom(), lifespan_context: map(), principal: any(), request_id: String.t(), request_metadata: map(), server: FastestMCP.Server.t() | nil, server_name: String.t(), session_id: String.t(), task_metadata: map(), task_store: pid() | atom() | nil, transport: atom() }
Functions
Returns the current access token available on the context.
Returns whether the context belongs to background-task execution.
Builds the base metadata shared across telemetry and event emission.
Builds the value managed by this module from runtime state and options.
Returns the authenticated client identifier when one is available.
FastestMCP derives this from normalized auth or principal data rather than exposing a second mutable field on the context struct.
Returns the current request context for the calling process.
This is the narrow convenience helper for nested runtime code. It returns
nil when the current process is not executing inside a FastestMCP request.
Returns the current request context or raises when no request is active.
Use this when helper code is only valid inside an active FastestMCP request and should fail loudly otherwise.
Emits a debug log event from this context.
Deletes one request-scoped value from the context.
Deletes state for the current context.
Returns the dependency map available on the context.
Resolves one named dependency from the context.
Disables matching components for the current session only.
Requests interactive input for a background task.
Emits telemetry and local runtime events for this context.
Enables matching components for the current session only.
Emits an error log event from this context.
Builds a derived context for background-task execution.
Reads request-scoped state from the context.
Reads session-scoped state for the current session.
Reads state for the current context.
Returns HTTP headers captured on the current request context.
Returns the immutable HTTP request snapshot for this context.
Emits an info log event from this context.
Returns whether the context belongs to background-task execution.
Lists visible prompts using the current request context.
Lists visible resources using the current request context.
Emits a log event from this context.
Notifies subscribed sessions that one concrete resource URI changed.
Returns the original request id that created the background task, if any.
Builds a progress helper for this context.
Stores a resolved auth result on the context.
Stores request-scoped state on the context.
Stores session-scoped state for the current session.
Reads a resource using the current request context.
Renders a prompt using the current request context.
Records a progress update.
Builds a stable request-context snapshot from the current context.
%FastestMCP.Context{} is still the primary runtime object. This helper is
the narrower convenience surface for code that wants request metadata without
depending on the full context struct.
Example
FastestMCP.add_tool(server, "request_info", fn _arguments, ctx ->
request = FastestMCP.Context.request_context(ctx)
%{
request_id: request.request_id,
transport: request.transport,
path: request.path
}
end)Clears all session visibility rules.
Runs a sampling request from this context.
Sends a raw MCP notification to the connected client session stream.
Builds a new server definition.
Stores state for the current context.
Returns the current background-task id, if any.
Returns the background-task store attached to the context, if present.
Emits a warning log event from this context.
Runs the given function with this context installed as the current request context.