ExMCP.Approval behaviour (ex_mcp v0.9.0)

Behaviour for implementing approval handlers in MCP clients.

This behaviour defines the callback for handling approval requests when a server wants to perform actions that require user consent.

Summary

Types

approval_data()

approval_opts()

approval_result()

approval_type()

Callbacks

request_approval(approval_type, approval_data, approval_opts)

Requests approval for an action.

Types

approval_data()

@type approval_data() :: map()

approval_opts()

@type approval_opts() :: keyword()

approval_result()

@type approval_result() ::
  {:approved, approval_data()} | {:denied, reason :: String.t()}

approval_type()

@type approval_type() :: :sampling | :tool_call | :resource_access | atom()

Callbacks

request_approval(approval_type, approval_data, approval_opts)

@callback request_approval(approval_type(), approval_data(), approval_opts()) ::
  approval_result()

Requests approval for an action.

Parameters

type - The type of approval being requested (e.g., :sampling, :tool_call)
data - The data associated with the approval request
opts - Additional options for the approval handler

Returns

{:approved, data} - The request was approved, possibly with modified data
{:denied, reason} - The request was denied with a reason

Examples

def request_approval(:sampling, %{"messages" => messages}, opts) do
  # Show UI to user for approval
  case get_user_consent(messages) do
    :yes -> {:approved, %{"messages" => messages}}
    :no -> {:denied, "User declined the request"}
  end
end