Skip to main content

​
Configure A2A servers

Handler can load configured A2A server definitions from two places:
  • global config in your user configuration directory
  • repo-scoped config at .handler/servers.toml in the repository root
The global file lives where your platform keeps per-user configuration: ~/Library/Application Support/handler/servers.toml on macOS, $XDG_CONFIG_HOME/handler/servers.toml on Linux (~/.config/handler when the variable is unset), and the local AppData directory on Windows. handler server validate prints the path of every file it read. Repo-scoped config is useful when a project should travel with a shared agent URL or auth shape, while secrets continue to come from environment variables on each developer machine.

​
File format

Each server entry needs a url. Auth and extensions are optional.

​
Global vs repo-scoped

Use global config by default:
Use repo-scoped config when the server definition belongs with the repo:

​
Request extensions on every call

If an agent expects an A2A extension, list its URI on the server entry and Handler sends it in the A2A-Extensions header on every request to that server. Extensions given on the command line with -e/--extension are merged in.
When a card marks an extension as required and the entry does not request it, Handler warns on connect.

​
Send static headers on every call

Some agents key behaviour off a request header that is not a credential: a per-user memory scope, a tenant id, a feature flag, a trace id. Put those in a headers table on the server entry and Handler sends them on every request to that server, from the CLI, the TUI, and the MCP server alike.
handler server add remy --url ... -H "X-Remy-User: alice" writes the same table. Header names go through the same check as -H on the command line, so Authorization, Cookie, and hop-by-hop headers are refused; authentication belongs in auth. A header given with -H on a command wins over the file’s on a name clash, and like credentials, these headers only go to the origin of the server’s URL.

​
Validation helpers

Handler validates server files when it loads them and skips only the invalid entries instead of failing the whole file. Use these commands to inspect what is available. List every configured server Handler can load:
Show one server’s resolved configuration:
Validate configured servers and auth references:

​
Example with auth

See Authentication for all six auth types.