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

# 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

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

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

Each server entry needs a `url`. Auth is 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
```

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

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

See [Authentication](./authentication) for full auth examples.