> ## Documentation Index
> Fetch the complete documentation index at: https://handler.alduncanson.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Servers

> Configure global or repo-scoped A2A server definitions for Handler, including auth and requested extensions.

# 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

```toml theme={null}
version = 1

[servers.local]
url = "http://localhost:8000"
```

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

## Global vs repo-scoped

Use global config by default:

```bash theme={null}
handler server add demo --url http://localhost:8000
```

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

```bash theme={null}
handler server add demo --url http://localhost:8000 --repository
```

## 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.

```toml theme={null}
[servers.demo]
url = "https://agent.example.com"
extensions = ["https://example.com/extensions/traceability/v1"]
```

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.

```toml theme={null}
[servers.remy]
url = "https://remy.example.com/a2a"

[servers.remy.headers]
"X-Remy-User" = "alice"
"X-Trace" = "handler"
```

`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:

```bash theme={null}
handler server list
```

Show one server's resolved configuration:

```bash theme={null}
handler server show demo
```

Validate configured servers and auth references:

```bash theme={null}
handler server validate
```

## Example with auth

```toml theme={null}
version = 1

[servers.demo]
url = "https://agent.example.com"
extensions = ["https://example.com/extensions/traceability/v1"]

[servers.demo.auth]
type = "bearer"
env = "HANDLER_DEMO_TOKEN"
```

See [Authentication](https://handler.alduncanson.com/guides/authentication.md) for all six auth types.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.