Expose A2A tools through MCP

Handler can expose A2A protocol operations through an MCP server so other tools can call the same card, message, task, and session operations.

Configure your agent harness

Most users do not start handler mcp manually. Instead, add it to your agent’s MCP server configuration so the agent harness launches Handler when it needs the tools.

Amp or Pi example

Use the same command shape for Amp, Pi, or any MCP client that supports stdio servers:

{
  "mcpServers": {
    "handler": {
      "command": "handler",
      "args": ["mcp"]
    }
  }
}

Run it manually for debugging

For local debugging, you can start the stdio server yourself:

handler mcp

The default transport is stdio, which is what most local MCP clients expect.

Available transports

Start the MCP server with the default stdio transport:

handler mcp --transport stdio

Start the MCP server with Server-Sent Events transport:

handler mcp --transport sse

Start the MCP server with streamable HTTP transport:

handler mcp --transport streamable-http

Use stdio for local tool integrations and the HTTP-based transports when you need a networked MCP endpoint.

What the MCP server exposes

The server provides thirteen tools:

Area	Tools
Cards	`get_agent_card` (public or extended card), `validate_agent_card`
Messages	`send_message` (with session, task, and auth support)
Tasks	`get_task`, `list_tasks`, `cancel_task`
Push notifications	`set_task_notification`, `get_task_notification`, `list_task_notifications`, `delete_task_notification`
Sessions	`list_sessions`, `get_session_info`, `clear_session_data`

Every tool that talks to an agent takes either agent_url or server, the name of an entry in servers.toml (global, or repository-local relative to the MCP server’s working directory). A named server brings its URL, its configured auth, and its static headers, so the call needs no credential at all:

{ "server": "remy", "message": "What do you remember about me?" }

For an ad-hoc URL, prefer bearer_env or api_key_env, which name an environment variable in the MCP server’s process; the secret stays out of the tool-call JSON that clients log and display. The raw-value arguments (bearer_token, api_key, cert_path, key_path, ca_cert_path, custom_headers) still work and take precedence when given. Credentials are bound to the origin of the agent URL, exactly as in the CLI. list_tasks follows pagination to the end and returns the tasks with a count and a truncated flag. get_task_notification looks up the task’s single config when no config_id is given. That makes it useful as a bridge layer between MCP clients and A2A agents.

Typical workflow

One common pattern is:

Configure one or more A2A servers in Handler.
Add handler mcp to your agent harness MCP config.
Connect your MCP client.
Use MCP tools to inspect cards, send messages, and manage tasks against those agents.

If you are still experimenting with URLs or auth, the CLI and TUI are usually the fastest way to stabilize that setup first.

When to use this instead of the CLI

Use the MCP server when another tool should drive Handler for you. Use the CLI when you want direct shell control or automation in scripts.

Core workflows

Agent and MCP workflows

MCP server

Expose A2A tools through MCP

Configure your agent harness

Amp or Pi example

Run it manually for debugging

Available transports

What the MCP server exposes

Typical workflow

When to use this instead of the CLI

​Expose A2A tools through MCP

​Configure your agent harness

​Amp or Pi example

​Run it manually for debugging

​Available transports

​What the MCP server exposes

​Typical workflow

​When to use this instead of the CLI

Expose A2A tools through MCP

Configure your agent harness

Amp or Pi example

Run it manually for debugging

Available transports

What the MCP server exposes

Typical workflow

When to use this instead of the CLI