Troubleshooting AI Integration

Common symptoms, their causes, and the one-line fix. Skim the left column to find your error.

Install + connection issues

Claude Code shows zero tools after install

Cause: The MCP host process is reused across windows; closing the window doesn't reload mcp_servers.json.

Fix: Fully quit Claude Code (⌘Q on macOS, File → Quit elsewhere) and reopen.

/oauth/authorize?error=wrong_format

Cause: Pasted a cvii_test_* sandbox key. Only cvii_live_* keys are accepted.

Fix: Mint a live key in Settings → API (must be on a Starter plan or higher).

/oauth/authorize?error=invalid_key

Cause: The pasted key is unknown, malformed, or no longer active. Common causes: trailing whitespace from copy-paste, or the key was revoked.

Fix: Re-copy the key from Settings → API; if that fails, mint a fresh one.

/oauth/authorize?error=brute_force

Cause: More than 15 failed auth attempts from your IP in the last 5 minutes.

Fix: Wait 5 minutes and try again. If you're using the picker, sign in to celavii.com first to skip paste entirely.

/oauth/authorize?error=expired

Cause: The picked key has an expires_at date in the past.

Fix: Pick a different key, or revoke the expired one and create a new key in Settings → API.

/oauth/authorize?error=not_member

Cause: You signed in to celavii.com as a different user from the one who owns the key being authorized.

Fix: Sign in as the right user, or paste a key from a workspace you do belong to.

Plan + workspace issues

Workspace shows 🔒 Upgrade to Starter on the picker

Cause: That workspace's effective plan is Free; external API access requires Starter or higher.

Fix: Pick a different workspace, or upgrade the org's plan in Settings → Billing. If the workspace inherits its plan from a parent, the picker shows it as Pro · inherited automatically.

Workspace shows 🔒 No payment method

Cause: Plan is Starter+ but no card on file.

Fix: Add a payment method in Settings → Billing, then refresh the consent page.

Runtime errors

Tool calls return 401 even though /me works

Cause: The key is missing the scope for that tool. /me is unscoped; other tools need profiles:read, campaigns:write, etc.

Fix: Revoke the key and mint a new one with default scopes — by default new keys get all 16 scopes.

find_similar_profiles returns NOT_FOUND

Cause: The seed profile has no embedding yet. The embedding pipeline runs every minute; recently-added profiles may not yet be indexed.

Fix: Pick a higher-traffic seed (the top results from search_profiles for big brands always have embeddings — try nike, instagram, leomessi). Or wait a few minutes and retry.

Hit 429 repeatedly during normal use

Cause: Per-key rate-limit fired. Starter = 30 req/min, Pro = 60, Enterprise = 120.

Fix: Stagger calls, or upgrade the workspace's plan. The Retry-After header tells you the seconds to wait.

enhance charged credits despite dry_run

Cause: The route honours dry_run: true, NOT confirmed: false. The MCP enhance_profiles tool translates between them, but direct REST callers must use dry_run.

Fix: meta.credits_used in the response envelope is the source of truth — if it's 0, you weren't charged. Set dry_run: true in the request body.

curl shows Deprecation: true on the SSE endpoint

Cause: /api/mcp/sse is sunsetting on 2026-08-06.

Fix: Switch your client URL from /api/mcp/sse to /api/mcp/mcp. JSON-RPC body and Authorization header are identical; only the transport differs.

---

Still stuck? Open an issue at github.com/efraijo/celavii-toolkit/issues with the exact error string and the client (Claude Code, Claude Desktop, Cursor, Windsurf), and we'll route it.