Runbook — Reconnect broker connectors after a rebuild

Prerequisites

• SSH to the box over Tailscale; the broker running (docker compose ps).
• BROKER_ADMIN_KEY is in the broker .env (regenerated on rebuild).
• Connector OAuth app creds present in .env — for notion_api/github these come from GCP-Secret-Manager on deploy; if a connect flow 500s with client_id string_too_short, the app creds are missing (add the secret + re-run install.yml). Cloudflare (Discovery) needs no creds.

Steps

On the box (cd /home/ubuntu/mcp-broker, K=$(grep -oP "(?<=^BROKER_ADMIN_KEY=).*" .env)):

1. Provision the app key (repopulates broker_keys.db; also what programmatic clients use as X-Broker-Key): curl -s -X POST -H "X-Admin-Key: $K" -d '{"app_key":"my_company:app1"}' http://127.0.0.1:8002/admin/keys → returns api_key once. Store it wherever a header-auth client needs it (the Telegram bot's /home/claudebot/.config/telegram.env; the Mac's NOTION_BROKER_KEY).
2. Authorize each connector — mint a single-use token and open the browser URL: curl -s -X POST -H "X-Admin-Key: $K" -d '{"app_key":"my_company:app1"}' http://127.0.0.1:8002/admin/connect-token → connect_token then visit https://bobsmcp.uk/oauth/<connector>/connect?connect_token=<token> and approve. Repeat per connector (notion_api, github, cloudflare).
3. Reconnect claude.ai — in claude.ai → Settings → Connectors, click Connect on the mcp-broker connector(s) and approve. Repopulates inbound_oauth.db.

Verification

python3 -c "import sqlite3;c=sqlite3.connect('data/tokens.db');print(list(c.execute('select connector_name from connections')))"
python3 -c "import sqlite3;c=sqlite3.connect('data/inbound_oauth.db');print(c.execute('select count(*) from inbound_tokens').fetchone())"

Expect a row per authorized connector, and inbound_tokens > 0 once claude.ai reconnects. End-to-end: ask claude.ai (or the Telegram bot) a Notion question.

Rollback

N/A — this only re-establishes authorizations. To revoke instead, delete the connection: DELETE /admin/connections/my_company:app1/<connector> or rotate the app key (POST /admin/keys/my_company:app1/rotate, which cascades and drops stored tokens).