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> --yesThe installed CLI wraps the same flow and is mechanically checked against the generated command registry:
zephr connect2. 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.