Configure server authentication

Handler supports four auth types for configured servers:

bearer tokens
API keys
mTLS client certificates
OAuth2 client credentials

Add a server from the CLI with the matching auth flags, or define the auth block manually in servers.toml.

Bearer tokens

CLI:

handler server add demo \
  --url https://agent.example.com \
  --bearer-env HANDLER_DEMO_TOKEN

TOML:

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

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

For one-off local setups you can also use a literal value, but environment variables are safer for anything shared.

API keys

CLI:

handler server add demo \
  --url https://agent.example.com \
  --api-key-env HANDLER_DEMO_API_KEY

Handler sends API keys in X-API-Key by default. TOML with the default header:

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

[servers.demo.auth]
type = "api_key"
env = "HANDLER_DEMO_API_KEY"

TOML with a custom header:

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

[servers.demo.auth]
type = "api_key"
env = "HANDLER_DEMO_API_KEY"
header = "Authorization"

mTLS

CLI:

handler server add demo \
  --url https://agent.example.com \
  --cert /path/to/client.crt \
  --key /path/to/client.key

TOML:

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

[servers.demo.auth]
type = "mtls"
cert = "/path/to/client.crt"
key = "/path/to/client.key"
ca_cert = "/path/to/ca.crt"

Handler checks that the certificate and key files exist before use, and verifies private key permissions.

OAuth2 client credentials

CLI:

handler server add demo \
  --url https://agent.example.com \
  --oauth2-token-url https://auth.example.com/oauth/token \
  --oauth2-client-id-env HANDLER_CLIENT_ID \
  --oauth2-client-secret-env HANDLER_CLIENT_SECRET \
  --oauth2-scope read \
  --oauth2-scope write

TOML:

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

[servers.demo.auth]
type = "oauth2"
token_url = "https://auth.example.com/oauth/token"
client_id_env = "HANDLER_CLIENT_ID"
client_secret_env = "HANDLER_CLIENT_SECRET"
scopes = ["read", "write"]

Handler fetches the access token with the OAuth2 client credentials grant, applies it as a bearer token on requests, and refreshes it when it expires. Use an HTTPS token endpoint so client credentials are protected in transit.

Core workflows

Agent and MCP workflows

Authentication

Configure server authentication

Bearer tokens

API keys

mTLS

OAuth2 client credentials

​Configure server authentication

​Bearer tokens

​API keys

​mTLS

​OAuth2 client credentials

Configure server authentication

Bearer tokens

API keys

mTLS

OAuth2 client credentials