Phantom.Session (phantom_mcp v0.3.2)

Represents the state of the MCP session. This is the state across the conversation and is the bridge between the various transports (HTTP, stdio) to persistence, even if stateless.

Summary

Types

t()

Functions

allow_prompts(session, prompts)

Set an allow-list of usable Prompts for the session

allow_resource_templates(session, resource_templates)

Set an allow-list of usable Resource Templates for the session

allow_tools(session, tools)

Set an allow-list of usable Tools for the session

assign(session, map)

Assign state to the session.

assign(session, key, value)

Assign state to the session.

elicit(session, elicitation)

Elicit input from the client

finish(pid)

Closes the connection for the session

list_resource_subscriptions(session)

new(session_id, opts \\ [])

Builds a new session with the provided session ID.

notify(pid, payload)

Send a notification to the client

notify_progress(session, progress, total \\ nil)

Send a progress notification to the client

notify_progress(pid, progress_token, progress, total)

ping(pid)

Send a ping to the client

progress_token(session)

Fetch the current progress token if provided by the client

respond(session, payload)

Sends response back to the stream

respond(pid, request_id, payload)

See respond/2

set_log_level(session, request, level)

Sets the log level for the SSE stream. Sets both for the current request for async tasks and the SSE stream

subscribe_to_resource(session, uri)

Subscribe the session to a resource.

unsubscribe_to_resource(session, uri)

Unsubscribe the session to a resource.

Types

t()

@type t() :: %Phantom.Session{
  allowed_prompts: [String.t()],
  allowed_resource_templates: [String.t()],
  allowed_tools: [String.t()],
  assigns: map(),
  client_capabilities: %{
    elicitation: false | map(),
    sampling: false | map(),
    roots: false | map()
  },
  client_info: map(),
  close_after_complete: boolean(),
  id: binary(),
  last_event_id: String.t() | nil,
  pid: pid() | nil,
  pubsub: module(),
  request: Phantom.Request.t() | nil,
  requests: map(),
  router: module(),
  stream_fun: fun(),
  tracker: term(),
  transport_pid: pid()
}

Functions

allow_prompts(session, prompts)

Set an allow-list of usable Prompts for the session

allow_resource_templates(session, resource_templates)

Set an allow-list of usable Resource Templates for the session

allow_tools(session, tools)

Set an allow-list of usable Tools for the session

assign(session, map)

@spec assign(t(), map()) :: t()

Assign state to the session.

assign(session, key, value)

@spec assign(t(), atom(), any()) :: t()

Assign state to the session.

elicit(session, elicitation)

@spec elicit(t(), Phantom.Elicit.t()) ::
  {:ok, request_id :: String.t()} | :not_supported

Elicit input from the client

finish(pid)

@spec finish(Session.t() | pid()) :: :ok

Closes the connection for the session

list_resource_subscriptions(session)

new(session_id, opts \\ [])

@spec new(String.t() | nil, Keyword.t() | map()) :: t()

Builds a new session with the provided session ID.

This is used for adapters such as Phantom.Plug. If a session ID is not provided, it will generate one using UUIDv7.

notify(pid, payload)

@spec notify(t() | pid(), payload :: any()) :: :ok

Send a notification to the client

notify_progress(session, progress, total \\ nil)

@spec notify_progress(t(), number(), nil | number()) :: :ok

Send a progress notification to the client

the progress and total can be a integer or float, but must be ever-increasing. the total is optional.

https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/progress

notify_progress(pid, progress_token, progress, total)

ping(pid)

@spec ping(t() | pid()) :: :ok

Send a ping to the client

progress_token(session)

Fetch the current progress token if provided by the client

respond(session, payload)

Sends response back to the stream

This should likely be used in conjunction with:

Phantom.Tool.response(payload)
Phantom.Resource.response(payload)
Phantom.Prompt.response(payload)

For example:

session_pid = session.pid
request_id = request.id

Task.async(fn ->
  Session.respond(
    session_pid,
    request_id,
    Phantom.Tool.audio(
      File.read!("priv/static/game-over.wav"),
      mime_type: "audio/wav"
    )
  )
end)

respond(pid, request_id, payload)

See respond/2

set_log_level(session, request, level)

@spec set_log_level(Session.t(), Phantom.Request.t(), String.t()) :: :ok

Sets the log level for the SSE stream. Sets both for the current request for async tasks and the SSE stream

subscribe_to_resource(session, uri)

@spec subscribe_to_resource(t(), string_uri :: String.t()) :: :ok | :error

Subscribe the session to a resource.

This is used by the MCP Router when the client requests to subscribe to the provided resource.

unsubscribe_to_resource(session, uri)

@spec unsubscribe_to_resource(t(), string_uri :: String.t()) :: :ok | :error

Unsubscribe the session to a resource.

This is used by the MCP Router when the client requests to subscribe to the provided resource.