<!-- zibby-template-version: 1 -->
# /zibby-connect — connect this project's Claude Code to a Zibby control-plane (cloud OR self-host)

You are wiring THIS project up to a Zibby control-plane over MCP, so the `zibby_*` tools (trigger workflows, list agents, tail logs, …) become available directly in the editor. Works identically for Zibby Cloud and a self-hosted box — only the URL + token differ.

You cannot drive the CLI's interactive prompts (they need a TTY) — use the non-interactive flags path below. That is exactly what it exists for.

## Steps

1. **Check whether a connection already exists.** Read `./.mcp.json` (project root). If it has an `mcpServers.zibby` entry:
   - Verify it still answers: POST the MCP initialize handshake to its `url` with its `Authorization` header:
     ```
     Bash(curl -s -o /dev/null -w '%{http_code}' -X POST <url> -H "Authorization: <the header value>" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}')
     ```
   - `200` → report "already connected, verified working" and stop. Non-200 → the stored token/URL is stale; continue below to re-install.

2. **Ask the user for the two inputs, conversationally:**
   - **Control-plane URL** — their self-host box (e.g. `https://aiagent.example.com`) or Zibby cloud (`https://api-prod.zibby.app`). If `ZIBBY_API_URL` is already exported, offer it as the default.
   - **Access token** — a self-host admin/project token (`zby_…`, from the box's `.env` / `zibby self-host token`) or a user PAT (`zby_pat_…`, from https://zibby.dev/settings/tokens). If `ZIBBY_API_KEY` is exported, offer to reuse it.

3. **Run the installer — token via env var, NEVER inline in argv** (argv lands in shell history/process lists; the env form doesn't):
   ```
   Bash(ZIBBY_MCP_TOKEN="$THE_TOKEN" zibby mcp install --url <url> --yes)
   ```
   (`--yes` = non-interactive, writes project `./.mcp.json`; add `--agent claude-code` instead for a global install if the user asks.) The CLI VALIDATES before writing: an authenticated REST read + the MCP initialize handshake. Nothing is written if either fails, and the error says which check failed.
   - **Never echo the token back into the chat** — not in commands you display, not in summaries. Refer to it masked (`zby_…`).

4. **Tell the user to restart Claude Code and APPROVE the server.** `.mcp.json` is project scope, so Claude Code shows it as `⏸ Pending approval` until they run `claude` in this directory and accept the prompt — that is Claude Code's gate, not an install failure, and `claude mcp list` never prompts. The file holds the token inline and the installer gitignored it; nothing else is needed.

5. **Report honestly** what the validation said: which URL was connected, that both checks passed (or the exact failure the CLI printed), and where the config was written. Do not claim success if the CLI exited non-zero.

## Common pitfalls

- **401 on validation** → wrong token for that control-plane (e.g. a cloud PAT against a self-host box, or a revoked token). Ask the user to re-check where the token came from.
- **URL unreachable** → typo'd host, missing `https://`, or the box isn't up. The CLI's error distinguishes "URL unreachable" from "token rejected" — relay it as-is.
- **`ZIBBY_API_KEY` already exported** → then plain `zibby mcp install --yes` needs no token input at all (the CLI reuses it as the bearer).
- **Self-signed HTTPS self-host** → `export NODE_EXTRA_CA_CERTS=/path/to/ca.pem` before running the install.