Zephr Docs

Connect your client

The server runs over stdio JSON-RPC and needs a database path — it falls back to an in-memory store when ZEPHR_DB_PATH is unset. Use absolute paths.

1. Admission via the trusted launcher

zephr-mcp is admission-scoped. Do not connect a bare zephr-mcp process with only ZEPHR_DB_PATH for real work. Use the trusted launcher, which mints a single-use capability and binding:

zephr-mcp project approve --name <name> --path <checkout> --yes
zephr-mcp path bind --project <id|name> --repository <id|name> --path <absolute-path> --yes
zephr-mcp launch --binding <id> --client <claude-code|cursor|codex|headless|cli|approved-adapter> --yes

The installed CLI wraps the same flow and is mechanically checked against the generated command registry:

zephr connect

2. Configure the client

Add Zephr to your client's MCP server list. Claude Code reads this shape from its settings file; Cursor reads the same shape from its own MCP settings.

{
  "mcpServers": {
    "zephr": {
      "command": "node",
      "args": ["/absolute/path/to/zephr/apps/mcp/dist/main.cjs", "--stdio"],
      "env": {
        "ZEPHR_DB_PATH": "/absolute/path/to/zephr.sqlite"
      }
    }
  }
}

Both paths must be absolute. ZEPHR_DB_PATH is optional — without it the server falls back to an in-memory store, useful for a smoke test but discarded when the process exits.

One database, scoped by worktree

Zephr opens a single SQLite file and scopes beliefs to a project → repository → worktree hierarchy inside it. The launcher admits a connection to exactly one worktree before any tool call; calls that reach outside the admitted scope are refused with scope_violation.

Next

Capture your first recall.