Skip to main content

Configure A2A servers

Handler can load configured A2A server definitions from two places:
  • global config at $XDG_CONFIG_HOME/handler/servers.toml
  • repo-scoped config at .handler/servers.toml
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 is optional.

Global vs repo-scoped

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

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 full auth examples.