Skip to main content
The MCP server authenticates with Ed25519 keypair sessions — the same mechanism AbadgeAgentClient uses. It reads configuration from environment variables first, then falls back to ~/.abadge/config.json. The MCP server has no other auth method — there are no agent API keys. Every agent authenticates with a keypair session.

​
Required configuration

The MCP server needs three things on startup: the API URL, the agent ID, and the agent’s Ed25519 private key (either inline or via a file path). Exactly one of ABADGE_PRIVATE_KEY_PATH or ABADGE_PRIVATE_KEY must be set. Missing everything makes the server exit with a clear error message.

​
MCP-specific overrides

When the same machine runs both the CLI and the MCP server under the same operator, these env vars override the generic values for MCP only: Use these when the CLI and MCP should authenticate as different agents.

​
Config file fallback

If an env var isn’t set, the MCP server reads ~/.abadge/config.json at the top level:
The MCP server reads the top-level apiUrl, agentId, and privateKeyPath fields — not the localAgents.mcp object that the CLI writes. Provide these values via environment variables when launching the MCP server from Claude Desktop; see Claude Desktop config.

​
Keypair session lifecycle

On startup, the MCP server:
1

Load configuration

Resolve env vars → fall back to config file → error out if required fields are missing.
2

Build an anonymous client

No bearer set yet.
3

Request a challenge

POST /v1/agents/{agentId}/sessions/challenge returns abc_... (60-second TTL).
4

Sign the challenge

Ed25519 detached signature with the configured private key.
5

Exchange for a session

POST /v1/agents/{agentId}/sessions/exchange returns abs_... (15-minute TTL).
6

Schedule refresh

A timer re-runs the exchange at T-2 minutes before expiry. If the refresh budget is exhausted, subsequent tool calls return SESSION_REFRESH_FAILED.

​
What gets persisted

  • The Ed25519 private key lives at ABADGE_PRIVATE_KEY_PATH (or wherever you stored it) with 0600 permissions. The CLI’s abadge agent add --kind local_mcp generates one for you.
  • The Ed25519 public key is stored on the server (public-key enrollment).
  • Session tokens (abs_...) live in MCP server process memory only. Restarting the MCP server forces a new exchange.
  • Bootstrap tokens (abe_...) are consumed during enrollment and never persisted.

​
Audit events

The MCP server emits standard auth audit events:
  • agent.session_issue (on each successful exchange)
  • agent.session_reject (on failed signature verification)
  • agent.session_revoke (on explicit revocation)
  • access.mount_env, access.mount_file, access.ciphertext, access.reveal — one per tool invocation