Installation

The MCP server is shipped as a compiled binary (abadge-mcp) and runs as a subprocess that an MCP-aware client launches over stdio.

Recommended: install script

curl -fsSL https://raw.githubusercontent.com/punitarani/abadge/main/install.sh | bash

By default this installs both abadge (CLI) and abadge-mcp (MCP server) to ~/.abadge/bin. To install only the MCP server:

ABADGE_INSTALL_PACKAGE=mcp \
  curl -fsSL https://raw.githubusercontent.com/punitarani/abadge/main/install.sh | bash

The script:

Detects your OS, architecture, and (on Linux) libc (glibc baseline or musl).
Downloads the latest signed mcp-v* release archive from GitHub.
Verifies the SHA-256 checksum against the published SHA256SUMS file.
Extracts the binary to ~/.abadge/bin/abadge-mcp.
Adds ~/.abadge/bin to your shell profile’s PATH if it’s not already there.

After install:

abadge-mcp
# expect non-zero exit and a message like
# "ABADGE_AGENT_ID is required (env or ~/.abadge/config.json)."

That error proves the binary loaded and validated config — it just needs auth env vars or a populated ~/.abadge/config.json. See Authentication.

Pinning a version

When installing only the MCP server:

ABADGE_INSTALL_PACKAGE=mcp ABADGE_MCP_VERSION=0.0.2 \
  curl -fsSL https://raw.githubusercontent.com/punitarani/abadge/main/install.sh | bash

When installing both packages, use the scoped variables (CLI and MCP have independent release cadences):

ABADGE_CLI_VERSION=1.4.2 ABADGE_MCP_VERSION=0.0.2 \
  curl -fsSL https://raw.githubusercontent.com/punitarani/abadge/main/install.sh | bash

Custom install paths

Variable	Default	Effect
`ABADGE_INSTALL_PACKAGE`	`all`	`cli`, `mcp`, or `all`
`ABADGE_INSTALL_DIR`	`~/.abadge/bin`	Where the binary is installed
`ABADGE_INSTALL_REPO`	`punitarani/abadge`	GitHub repo to fetch from
`ABADGE_INSTALL_BASE_URL`	(GitHub releases)	Override the release archive URL
`ABADGE_MCP_VERSION`	(latest stable `mcp-v*`)	Pin the MCP release
`ABADGE_VERSION`	(none)	Fallback when installing a single package only
`PROFILE`	(auto-detected)	Shell profile file to update

Build from source

If you’ve cloned the monorepo:

# Run directly from TypeScript (development workflow)
bun run mcp

# Compile a binary into packages/mcp/dist/
bun run --cwd packages/mcp build
./packages/mcp/dist/abadge-mcp

Compile a per-platform release tarball into /tmp (mirrors the GitHub Actions release pipeline):

bun run release:mcp:dry-run -- --outdir /tmp/abadge-mcp-release
ls /tmp/abadge-mcp-release/

What gets installed where

Path	Purpose	Permissions
`~/.abadge/bin/abadge-mcp`	The MCP server binary	`0755`
`~/.abadge/config.json`	Shared config (read by both CLI and MCP server)	`0600`
`~/.abadge/agents/*.jwk`	Local Ed25519 private keys (one per registered agent)	`0600`
`~/.abadge/vaultd.sock`	Daemon Unix socket (required for ZK item access)	`0600`

The MCP server reads its config from env vars or ~/.abadge/config.json. To register an MCP agent and get a paste-ready Claude Desktop snippet:

abadge agent add --kind local_mcp --name claude-desktop --mcp-config

See Claude Desktop for the full setup walk-through.

What it does on startup

Sweep orphaned mounts

The server walks the OS temp directory and removes any abadge-* directory older than 10 minutes. This cleans up after crashed previous runs.

Resolve configuration

Read env vars (or fall back to top-level apiUrl, agentId, privateKeyPath in ~/.abadge/config.json). Error out on missing required fields.

list_items, use_secret, mount_secret, release_mount, get_audit.

Listen on stdio

The server prints abadge-mcp server running on stdio on stderr and begins handling MCP requests. The keypair session exchange happens lazily on the first tool invocation.

Health check

There’s no separate health endpoint — the server exits non-zero if startup fails. Common failure modes:

Symptom	Likely cause
`ABADGE_API_URL is required`	No env var and no config file
`ABADGE_AGENT_ID is required`	No agent ID configured
`ABADGE_PRIVATE_KEY or ABADGE_PRIVATE_KEY_PATH is required`	No private key configured
`ENOENT` on the private key path	`ABADGE_PRIVATE_KEY_PATH` typo or file missing
`UNAUTHORIZED` / `AGENT_NOT_ENROLLED`	Wrong agent ID, wrong key, agent revoked, or public key never enrolled
Connection refused on `ABADGE_API_URL`	API not reachable from the host running the MCP server

Logs

The server writes structured logs to stderr. Routes that fail include the API error envelope (code, message, hint). In Claude Desktop, MCP server logs are captured in the application log directory. On macOS that’s ~/Library/Logs/Claude/.

Authentication

Env vars, config fallback, keypair session lifecycle.

Claude Desktop

Drop-in JSON config snippet.

Getting started

Tools

Security

Recommended: install script

Pinning a version

Custom install paths

Build from source

What gets installed where

What it does on startup

Health check

Logs

Next

Authentication

Claude Desktop

​Recommended: install script

​Pinning a version

​Custom install paths

​Build from source

​What gets installed where

​What it does on startup

​Health check

​Logs

​Next

Authentication

Claude Desktop

Recommended: install script

Pinning a version

Custom install paths

Build from source

What gets installed where

What it does on startup

Health check

Logs

Next