Skip to main content
The MCP server runs as a subprocess that the host client launches over stdio. Most clients accept a JSON config that lists MCP servers and their startup commands.

​
Quick setup with the abadge CLI

The fastest path: register a local MCP agent and let the CLI emit the config snippet for you.
The last command prints something like:
Paste the inner mcpServers.abadge object into Claude Desktop’s config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), restart Claude, and the abadge tools should appear.
Use the absolute path for command. Claude Desktop is launched by launchd/systemd with a minimal $PATH that does not include ~/.abadge/bin, so a bare abadge-mcp will fail with “spawn ENOENT” or similar. The --mcp-config flag always emits absolute paths.
If you already registered the agent and just need the snippet again:

​
Manual setup

If you’d rather hand-write the config, the shape is:
Replace:
  • command with the absolute path to your installed abadge-mcp (default ~/.abadge/bin/abadge-mcp)
  • ABADGE_API_URL with your deployment
  • ABADGE_AGENT_ID and ABADGE_PRIVATE_KEY_PATH with the values from abadge agent add --kind local_mcp (or whatever you’ve stored in ~/.abadge/config.json under localAgents.mcp)
Restart Claude Desktop after editing.

​
Other MCP clients

Any MCP-compatible client that supports stdio transport works the same way. Provide:
  • A way to launch the subprocess (/Users/you/.abadge/bin/abadge-mcp, or bun packages/mcp/src/index.ts from the monorepo for development)
  • Environment variables to point it at the API and the agent’s private key

​
Verifying the connection

Once configured, the host client should list the abadge tools (list_items, use_secret, mount_secret, release_mount, get_audit) under the abadge server. If the tools don’t appear:
  1. Check the host client’s MCP server log (Claude Desktop logs to ~/Library/Logs/Claude/ on macOS).
  2. Run the server manually from a terminal to see startup errors:
  3. Confirm the agent is enabled with abadge agent list.

​
Permissions

The MCP server can only access items where the configured agent has an explicit permission. Grant the right capability before invoking a tool:
These CLI grants target a single item, so they use the legacy capability names. mount_env and mount_file both map to the canonical use capability that MCP needs — use_secret calls POST /v1/access/{itemId}/use with delivery: env, and mount_secret calls it with delivery: file. Grant mount_file too if the agent mounts secrets to files.

​
Full worked example

For a complete, copy-pasteable setup — config block, a setup script, the five tools, and an example prompt that triggers use_secret — see the Claude Desktop example in the repo, or the Examples page.