Anubis.Server.Session (anubis_mcp v2.2.0)

Per-client MCP session process.

Each Session is a GenServer that manages the lifecycle of a single MCP client connection. It handles protocol initialization, request/notification dispatch, server-initiated requests (sampling, roots), and session persistence.

Sessions are created by the transport layer (STDIO creates one at startup, HTTP transports create them dynamically via Anubis.Server.Supervisor). Transports deliver client messages through the dispatcher contract defined in Anubis.Server.Transport.Session.

Summary

Types

t()

Functions

auto_initialize(session)

Auto-initializes a session without a client initialize handshake.

auto_initialize(session, transport_context)

get_schema(atom)

parse_options(data)

parse_options!(data)

start_link(opts)

Starts a Session process linked to the current process.

Types

t()

@type t() :: %{
  session_id: String.t(),
  server_module: module(),
  protocol_version: String.t() | nil,
  protocol_module: module() | nil,
  initialized: boolean(),
  client_info: map() | nil,
  client_capabilities: map() | nil,
  init_meta: map(),
  log_level: String.t() | nil,
  frame: Anubis.Server.Frame.t(),
  server_info: map(),
  capabilities: map(),
  instructions: String.t() | nil,
  supported_versions: [String.t()],
  transport: %{layer: module(), name: GenServer.name()},
  registry: module(),
  session_idle_timeout: pos_integer(),
  expiry_timer: reference() | nil,
  pending_requests: %{
    required(String.t()) => %{started_at: integer(), method: String.t()}
  },
  server_requests: %{
    required(String.t()) => %{method: String.t(), timer_ref: reference()}
  },
  timeout: pos_integer(),
  task_supervisor: GenServer.name(),
  task_store: Anubis.Server.Session.Tasks.store() | nil,
  tasks: %{required(String.t()) => Anubis.Server.Session.Tasks.task_runtime()},
  task_refs: %{required(reference()) => String.t()},
  in_flight: Anubis.Server.Session.Scheduler.in_flight() | nil,
  request_queue: :queue.queue(Anubis.Server.Session.Scheduler.queued_request()),
  deferred_callbacks:
    :queue.queue(Anubis.Server.Session.Scheduler.deferred_callback()),
  owner_ref: reference() | nil,
  request_context: map() | nil
}

Functions

auto_initialize(session)

@spec auto_initialize(GenServer.server()) :: :ok | {:error, term()}

Auto-initializes a session without a client initialize handshake.

This is used when a client sends a non-initialize request to an expired or unknown session. Instead of returning 404, the server can create a new session and auto-initialize it so the request can be processed transparently.

Uses the server's latest supported protocol version and synthetic client info (%{"name" => "auto-recovered", "version" => "unknown"}). Server implementations should not rely on this identity for client-specific decisions.

auto_initialize(session, transport_context)

@spec auto_initialize(GenServer.server(), map() | nil) :: :ok | {:error, term()}

get_schema(atom)

parse_options(data)

parse_options!(data)

start_link(opts)

@spec start_link(keyword()) :: GenServer.on_start()

Starts a Session process linked to the current process.

Options

:session_id — unique session identifier (required)
:server_module — the MCP server module implementing Anubis.Server (required)
:name — GenServer registration name. Omit it for a session that is only ever addressed by pid, such as one started for a single request.
:transport — transport configuration [layer: module, name: name] (required)
:task_supervisor — name of the Task.Supervisor for async work (required)
:registry — session registry module (default: Anubis.Server.Registry)
:session_idle_timeout — idle timeout in ms before session expires (default: 30 min)
:timeout — request timeout in ms (default: 30s)
:owner — a process whose exit stops the session. A transport that starts a session for a single stateless request passes itself, so the session never outlives the request, and it does not expire when idle. Such a session calls the server's init/2 for each stateless request it serves, with that request's client info, because no handshake ever runs it.