ToolCairnThe ToolCairn MCP server uses RFC 8628 device authorization. The CLI never sees the user's password, never opens a redirect server on localhost, and works even in headless environments (via manual code entry).
Sequence
text
CLI Web API
│ │ │
│──── toolcairn_auth login ───────▶│ │
│ │ POST /v1/auth/device │
│◀── user_code: ABCD-EFGH ─────────│◀─────────────────────────── ── ─│
│ │ device_code + poll interval │
│ │ │
│──── open browser @ /device ─────▶│ │
│ │ user enters user_code │
│ │ confirms consent │
│ │ │
│ poll /v1/auth/token ──────────┼────────────────────────────────▶│
│ (every N seconds) │ │
│ │ │
│◀─────────── JWT (90 days) ───────┼─────────────────────────────────│
│ │
│ save to ~/.toolcairn/credentials.json │Auth-gate mode
On first start (before any credentials exist), the MCP server boots into auth-gate mode — it registers exactly one tool, toolcairn_auth, and the MCP instructions tell the agent to call it. After a successful login and a client restart, the full catalog of 14 tools is registered.
Tokens & storage
- Credentials file:
~/.toolcairn/credentials.json(0600 mode on *nix). - Token: HS256 JWT. Payload includes
sub(user id),email,type: "mcp",tier. - Expiry: 90 days. The CLI treats a token as expired 5 minutes early to avoid race conditions on refresh.
- Revocation: sign out in the web app or call
toolcairn_auth { action: "logout" }. Revoked tokens reject on the next API call.
Related
toolcairn_authreference- HTTP API authentication (for non-MCP integrations)