# `A2UIAgent.MCP`
[🔗](https://github.com/a2ui-elixir/a2ui/blob/v0.1.1/umbrella/apps/a2ui_agent/lib/a2ui_agent/mcp.ex#L1)

Carries A2UI over the [Model Context Protocol](https://modelcontextprotocol.io),
as the A2UI project's guide "A2UI over MCP" describes: the JSON values an
MCP server puts in its responses, and the A2UI values it reads from
requests. It works with any MCP server implementation.

Presentation and data are separate. Layouts (`createSurface` and
`updateComponents` messages, with data bindings) are MCP resources with
the MIME type `application/a2ui+json`; a tool call returns the data,
usually an `updateDataModel` message, in an embedded resource next to a
text fallback. A tool links to its layout with `_meta.ui`:

    A2UIAgent.MCP.tool("get_recipe", resource_uri: "a2ui://recipe-card",
      description: "Returns a recipe.")

    A2UIAgent.MCP.tool_result(messages,
      uri: "a2ui://recipe-card/data",
      resource_uri: "a2ui://recipe-card",
      text: "Generated recipe: Grilled salmon")

A client states its renderer capabilities once in `initialize`
(`capabilities.a2ui.clientCapabilities`), or in the `_meta` of each tool
call; `renderer_capabilities/1` reads either. The renderer sends its
users' actions and its errors as calls of the `a2ui_action` and
`a2ui_error` tools (`action_tool/0`, `error_tool/0`).

# `a2ui_messages`
*since 0.1.0* 

```elixir
@spec a2ui_messages(map()) :: {:ok, [map()]} | {:error, Jason.DecodeError.t()}
```

The A2UI messages in a tool call's result: the JSON of every embedded
resource with the A2UI MIME type, in order. Content that is not A2UI
is skipped; A2UI text that is not JSON is an error.

# `action`
*since 0.1.0* 

```elixir
@spec action(map(), String.t()) :: {:ok, map()} | {:error, String.t()}
```

The arguments of an `a2ui_action` tool call as an A2UI `action`
message of `version`, or an error naming the missing fields.

    iex> A2UIAgent.MCP.action(%{"name" => "go", "surfaceId" => "s", "sourceComponentId" => "b",
    ...>   "timestamp" => "2026-10-16T12:00:00Z", "context" => %{}})
    {:ok, %{"version" => "v1.0", "action" => %{"name" => "go", "surfaceId" => "s",
      "sourceComponentId" => "b", "timestamp" => "2026-10-16T12:00:00Z", "context" => %{}}}}

# `action_tool`
*since 0.1.0* 

```elixir
@spec action_tool() :: map()
```

The definition of the `a2ui_action` tool, through which a renderer
sends its users' actions. Every field of an action is required, so
that an MCP SDK does not drop one.

# `error_tool`
*since 0.1.0* 

```elixir
@spec error_tool() :: map()
```

The definition of the `a2ui_error` tool, through which a renderer reports errors.

# `mime_type`
*since 0.1.0* 

```elixir
@spec mime_type() :: String.t()
```

The MIME type of A2UI resources: `application/a2ui+json`.

# `renderer_capabilities`
*since 0.1.0* 

```elixir
@spec renderer_capabilities(map()) :: map() | nil
```

The renderer capabilities in the params of an `initialize` request
(`capabilities.a2ui.clientCapabilities`) or of a tool call
(`_meta.a2ui.clientCapabilities`), keyed by protocol version, or `nil`
when they carry none. Pass them to
`A2UIAgent.Generator.create_processor/3`.

# `resource`
*since 0.1.0* 

```elixir
@spec resource(String.t(), String.t(), keyword()) :: map()
```

A resource entry for `resources/list`. Option: `:description`.

    iex> A2UIAgent.MCP.resource("a2ui://form", "Form")
    %{"uri" => "a2ui://form", "name" => "Form", "mimeType" => "application/a2ui+json"}

# `resource_contents`
*since 0.1.0* 

```elixir
@spec resource_contents(String.t(), [map()]) :: map()
```

The contents of an A2UI resource for `resources/read`: `messages`, as
JSON text.

# `tool`
*since 0.1.0* 

```elixir
@spec tool(String.t(), keyword()) :: map()
```

A tool definition for `tools/list`. Options: `:title`,
`:description`, `:input_schema` (default: an object that takes any
arguments) and `:resource_uri`, the A2UI resource that presents its
results.

# `tool_result`
*since 0.1.0* 

```elixir
@spec tool_result([map()], keyword()) :: map()
```

A tool call's result (`CallToolResult`) carrying A2UI messages in an
embedded resource.

Options:

  * `:uri` — the embedded resource's URI (default `"a2ui://messages"`);
  * `:text` — a text fallback, put first, for clients and models that
    do not render A2UI;
  * `:resource_uri` — the A2UI resource that presents the result,
    linked with `_meta.ui`;
  * `:audience` — who the messages are for: `["user"]` renders them
    without putting them in the model's context, `["assistant"]` the
    other way round (default: both).

# `ui_meta`
*since 0.1.0* 

```elixir
@spec ui_meta(String.t()) :: map()
```

The `_meta` that links a tool, or a tool's result, to the A2UI resource
that presents it.

    iex> A2UIAgent.MCP.ui_meta("a2ui://recipe-card")
    %{"ui" => %{"resourceUri" => "a2ui://recipe-card", "mimeType" => "application/a2ui+json"}}

---

*Consult [api-reference.md](api-reference.md) for complete listing*