HandlerCAUTION
A2A protocol client for your terminal
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://github.com/alDuncanson/handler/actions/workflows/ci.yml) [](https://a2a-protocol.org/latest/) [](https://pypi.org/project/a2a-handler/) [](https://pypi.org/project/a2a-handler/) [](https://pepy.tech/projects/a2a-handler) [](https://github.com/alDuncanson/handler/stargazers)
Handler is an open-source A2A protocol client for software engineers building, testing, and operating agentic systems. It provides an interactive TUI, a scriptable CLI with structured output, and an MCP server that lets other agents integrate with A2A services directly. Handler also supports global and repo-scoped A2A server configuration with bearer, API key, mTLS, and OAuth2 client credentials auth.
Install
Install Handler from the PyPI package as a uv tool:
uv tool install a2a-handler
Or with pipx:
pipx install a2a-handler
Or with pip:
pip install a2a-handler
Quick Start
Open the interactive terminal UI:
handler tui
Inspect an A2A server's agent card:
handler card get --url http://localhost:8000
Send a message from the CLI:
handler message send --url URL --text "hello"
Open the full documentation:
handler docs
Run Without Ins
f01b985cf046OBSERVED · 2026-10-08Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add a2a-handler --env CLIENT_SECRET=${CLIENT_SECRET} -- uvx a2a-handler{
"mcpServers": {
"a2a-handler": {
"command": "uvx",
"args": [
"a2a-handler"
],
"env": {
"CLIENT_SECRET": "${CLIENT_SECRET}"
}
}
}
}Exposed tools (13)
7 read · 4 write · 2 destructive. Blast radius: 2 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
cancel_task | read | Cancel a running task. |
clear_session_data | destructive | Clear saved session data. |
delete_task_notification | destructive | Delete a push notification config from a task. |
get_agent_card | read | Retrieve an agent |
get_session_info | read | Get session information for a specific agent. |
get_task | read | Get the current status and details of a task. |
get_task_notification | write | Get the push notification configuration for a task. |
list_sessions | read | List all saved sessions. |
list_task_notifications | write | List every push notification config for a task. |
list_tasks | read | List an agent |
send_message | write | Send a message to an A2A agent and receive a response. |
set_task_notification | write | Configure push notifications for a task. |
validate_agent_card | read | Validate an A2A agent card from a URL or local file. |
Trust audit
CAUTIONgrade B · trust 86/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- declared (5 observation(s))
- Shell
- none-observed
- Dependencies
- pinned
- Secrets in source
- found
Findings (9)
token="secret-token-value-here-long",
token="abcdefghij1234567890xyz",
clear_session_data, delete_task_notification
.actrc
4. Point that task at `http://127.0.0.1:9000/webhook` with `handler task notification set`.
5. Inspect received events at `http://127.0.0.1:9000/notifications`.
--webhook-url http://127.0.0.1:9000/webhook \
--webhook-url http://127.0.0.1:9000/webhook \
Handler fetches the access token with the OAuth2 client credentials grant,
Gates applied: no_behavioural_pass.
f01b985cf046full audit observations/trust-audit/mcp-server/alduncanson__handler.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-08 | f01b985cf046 | CAUTION | B | 86 | first audit |
Questions
What is the Handler MCP server?
A2A protocol client for your terminal
What tools does Handler expose?
13 in total: 7 read-only, 4 that write, and 2 that can delete or overwrite (clear_session_data, delete_task_notification). Every one is listed on this page with its risk.
Is Handler safe to connect to an agent?
With care. The audit graded it B (86/100) and found 9 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 2 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Handler need?
It reads CLIENT_SECRET from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does Handler run?
It speaks streamable-http, so it runs as a service you connect to over the network. It is published on PyPI as a2a-handler.
How current is this page?
The grade is for one exact copy of the source (f01b985cf046), read on 2026-10-08. The repository is watched and re-audited when it changes.