What a callback can ask of the client: input from the user (elicitation), a model completion (sampling) and the roots of the client.
The functions block the calling process until the client answers. They
run inside a callback (tool.call/2, resource.read/2, prompt.get/2, a
task tool) and take its ctx. They are built on OzMcp.Outbound.request/4:
the client must have declared the capability (elicitation, sampling,
roots), else nothing is sent and the result is
{:error, :capability_not_supported}. Every error of
OzMcp.Outbound is possible; the options :timeout and
:wait_for_stream are passed to it.
Invalid arguments
elicit/3, sample/3 and url_elicitation_required/2 build their params
with the structs of OzMcp.Structs and raise ArgumentError for invalid
arguments (a missing :message or :max_tokens, a schema that is not
flat, a URL with credentials, tool use messages out of order). This is for
a programmer error. Inside a callback the raise is caught by the framework:
the client gets the generic -32603 error and the log has the cause.
Waiting time
The client has a limited time to answer and a call that waits longer ends
with {:error, :timeout} (the client is told to cancel the request). The
default depends on who answers (a person, a model, or list_roots/2);
the :timeout option of a call overrides it. The guide about the requests
to the client gives the options and the default of each method.
Elicitation
elicit/3 asks the user for input. With a schema it is a form: the
client shows the fields and returns the values. With a URL it is a URL
interaction: the client sends the user to a web page and the data never
passes through the client (use it for credentials and authorizations).
schema =
%ElicitationSchema{}
|> ElicitationSchema.property("name", %StringSchema{} |> StringSchema.title("Name"))
|> ElicitationSchema.required(["name"])
case OzMcp.Client.elicit(ctx, schema, message: "Who are you?") do
{:ok, %{action: :accept, content: %{"name" => name}}} -> name
{:ok, %{action: action}} when action in [:decline, :cancel] -> nil
{:error, reason} -> reason
endA form the client did not declare is not sent (an empty elicitation: {}
means form only). The content of an accepted form is validated against the
schema (validate: false turns it off). The guide about the requests to
the client gives the rules of the validation and of the defaults.
A callback that needs a URL interaction before it can run at all returns
the error of url_elicitation_required/2.
Sampling
sample/3 asks the client to run a model on a conversation. max_tokens
is required. Tools (tools:) and tool_choice: need the client capability
sampling.tools; include_context: other than :none needs
sampling.context.
messages = [OzMcp.Structs.SamplingMessage.user("Summarize this text: ...")]
{:ok, %{content: [%{"type" => "text", "text" => text}]}} =
OzMcp.Client.sample(ctx, messages, max_tokens: 300)Roots
list_roots/2 returns the roots the client exposes. A server that wants to
know when they change defines roots_list_changed/1 (see
OzMcp.Config.Server).
Tasks of the client
sample/3 and elicit/3 can run the request as a task of the client:
pass task: true or task: %{ttl: milliseconds}. The client answers at
once with a task, the server polls tasks/get and reads the final result
with tasks/result. Use it for a long sampling or a long human input: one
request is not held open. The option needs the runtime option
client_tasks (default false, experimental) and a client without the
task capability gets a plain request unless task_required: true. The
guide about the requests to the client describes the flow and its errors.
In a task
A callback that runs as a task (ctx.task_id is set) can use all of these
functions: the request travels on the tasks/result stream of the task
with the io.modelcontextprotocol/related-task meta and the task is
input_required while it waits. If the client does not call
tasks/result, the request ends with {:error, :timeout}.
A task of the client (task:) is a different thing from the task of the
server: the server task stays working while its polls can travel on a
tasks/result stream.
Summary
Functions
Asks the user for input. schema_or_url is an
OzMcp.Structs.ElicitationSchema struct or a map (form mode), or a URL
string (URL mode).
Asks the client for its roots.
Asks the client to complete a conversation with a model.
Builds the error of a request that cannot run before the user finishes a
URL interaction (JSON-RPC error -32042). A callback returns it
Types
Functions
@spec elicit( ctx(), OzMcp.Structs.ElicitationSchema.t() | map() | String.t(), keyword() ) :: {:ok, elicit_result()} | {:error, term()}
Asks the user for input. schema_or_url is an
OzMcp.Structs.ElicitationSchema struct or a map (form mode), or a URL
string (URL mode).
Options:
:message(required) — what the user sees, with the reason for the request.:elicitation_id— URL mode only: the identifier of the interaction (generated by default). It is part of the result.:validate— form mode only: validate the content against the schema (defaulttrue).:_meta— a_metamap for the request.:task— run the request as a task of the client:trueor%{ttl: milliseconds}. Needs the runtime optionclient_tasks(experimental) and the client capabilitytasks.requests.elicitation.create.:task_requiredand:poll_interval— the same as inOzMcp.Outbound.request_task/4.:timeout,:wait_for_stream— seeOzMcp.Outbound.request/4.
Returns {:ok, %{action: action, content: content}}. action is
:accept, :decline or :cancel; content is the map of the values
(string keys) for an accepted form, nil otherwise. In URL mode :accept
means the user agreed to open the URL, not that the interaction is done.
A client task gives the errors of OzMcp.Outbound.request_task/4:
{:error, {:client_task_cancelled, task_id}} and
{:error, {:invalid_response, result}} in addition to the plain ones.
Asks the client for its roots.
Returns {:ok, roots}: a list of maps with the string keys "uri" (a
file:// URI) and, optionally, "name".
@spec sample(ctx(), [OzMcp.Structs.SamplingMessage.t() | map()], keyword()) :: {:ok, sample_result()} | {:error, term()}
Asks the client to complete a conversation with a model.
messages is a list of OzMcp.Structs.SamplingMessage structs or maps.
Options:
:max_tokens(required):system_prompt,:temperature,:stop_sequences,:metadata:model_preferences— aOzMcp.Structs.ModelPreferencesstruct or map:include_context—:none,:this_serveror:all_servers:tools— a list ofOzMcp.Structs.Toolstructs or maps:tool_choice—:auto,:required,:noneor aOzMcp.Structs.ToolChoice:task— run the request as a task of the client:trueor%{ttl: milliseconds}. Needs the runtime optionclient_tasks(experimental) and the client capabilitytasks.requests.sampling.createMessage.:task_requiredand:poll_interval— the same as inOzMcp.Outbound.request_task/4.:_meta,:timeout,:wait_for_stream
Returns {:ok, result} with role, content (always a list of blocks
with string keys), model and stop_reason ("endTurn", "toolUse",
"maxTokens", ... or nil). When stop_reason is "toolUse" the content
has tool_use blocks: run the tools and sample again with their results.
A client task gives the errors of OzMcp.Outbound.request_task/4:
{:error, {:client_task_cancelled, task_id}} and
{:error, {:invalid_response, result}} in addition to the plain ones.
@spec url_elicitation_required([map()], String.t()) :: OzMcp.Utils.Error.t()
Builds the error of a request that cannot run before the user finishes a
URL interaction (JSON-RPC error -32042). A callback returns it:
def call(ctx, params) do
{:error,
OzMcp.Client.url_elicitation_required([
%{url: "https://example.com/connect", message: "Connect your account"}
])}
endEach elicitation is a map with :url and :message and optionally
:elicitation_id (generated by default). The client opens the URLs and
retries the request when the interactions are done.