Caddi
Sign inGet started

Docs

Agents

caddi install registers a single local MCP server, the gateway (caddi mcp), with any coding agent it detects on your machine. This page covers what it does per agent, what tools your agent sees, the manual fallback, and the audit trail.

What caddi install does

Run it once, then restart your coding agent:

caddi install

It never touches an agent’s other MCP servers or config keys: only a single caddi entry is added or updated, and re-running it is safe.

AgentDetected viaRegistration
Claude CodeThe claude binary on your PATH, or, failing that, an existing ~/.claude.json or ~/.claude directory.Runs claude mcp add caddi -- caddi mcp if the binary is available. Otherwise writes the caddi entry directly into the top-level mcpServers key of ~/.claude.json.
CursorA ~/.cursor directory.Merges the caddi entry into mcpServers in ~/.cursor/mcp.json.
WindsurfA ~/.codeium/windsurf (or ~/.codeium) directory.Merges the caddi entry into mcpServers in ~/.codeium/windsurf/mcp_config.json.
Codex CLIA ~/.codex directory.Writes a [mcp_servers.caddi] table into ~/.codex/config.toml, leaving every other table and comment in the file untouched.

Manual setup

If caddi install doesn’t detect anything, or your agent isn’t one of the four above, register the gateway by hand. Every MCP-capable agent needs the same stdio entry:

{
  "command": "caddi",
  "args": ["mcp"]
}

Add it under whichever key your agent uses for MCP servers, for example:

  • Claude Code: top-level mcpServers in ~/.claude.json
  • Cursor: mcpServers in ~/.cursor/mcp.json
  • Windsurf: mcpServers in ~/.codeium/windsurf/mcp_config.json
  • Codex CLI: a [mcp_servers.caddi] table in ~/.codex/config.toml

What tools appear

Once the gateway is registered, your agent sees one MCP tool per curated action on each native provider you’ve connected (see connections for native vs secrets-only). Tools are connection-scoped: if you haven’t connected GitHub, no GitHub tools appear. A project can narrow this further with an optional caddi.json, which allowlists which tools are available when the agent is launched from that directory tree. A get_secret tool exists for reading a raw connection value directly, but it’s off by default and has to be explicitly requested by a project’s caddi.json and approved with caddi approve get_secret.

Audit trail

Every tool call the gateway makes is written to a local, names-only audit log: the service, the tool, a hashed project identifier, and the outcome, never argument values. Tail it live while you work:

caddi audit --tail

Or list recent events without watching:

caddi audit

The same events sync (best effort) to the dashboard’s audit page, so you can review agent activity across every machine you use, not just the one you’re on.

Next