Connection troubleshooting
Fix a client that can't sign in, lost its tools, or gets a 401 or 402 when talking to looot.
Problems and solutions
| What you see | Why | What to do |
|---|---|---|
| The client lists looot as “needs authentication”, “needs login” or “not authenticated” | Adding the URL doesn’t sign in by itself. | Start the client’s sign-in: /mcp in Claude Code, codex mcp login looot, /mcp auth looot in Gemini CLI, or the Connect button in the app’s MCP settings. |
| Signed in, but the looot tools are missing | Some clients read the tool list only when they start. | Restart the client or start a new session. In Claude Code, run /mcp to check the status. |
401, “unauthorized”, or invalid_token after it worked |
The token was revoked in Settings, the “stay connected” time ran out, or the header token expired. | Browser sign-in: sign in again from the client. Header token: create a new one and update the header or secret. |
402 or insufficient_balance on a run |
The organization’s balance can’t cover the run. There is no free credit. | Top up at looot.ai/usage?top_up=1 or ask the agent to call top_up and pay the link. The balance tool reports the current minimum. Then run again with a new idempotency key. |
forbidden on run |
The token doesn’t have the runs.execute scope. |
Revoke the “(connected)” token in Settings, sign in again, and keep runs.execute ticked. |
A desktop app doesn’t see LOOOT_TOKEN |
Apps started from the Dock, Start menu or Finder don’t read your shell profile. | Use browser sign-in instead, or start the app from a terminal where the variable is set. |
| The browser didn’t open | Some terminals and remote sessions can’t open one. | The client prints the sign-in link. Copy it into a browser on the same machine. |
| Connected to the wrong organization | The consent page uses the organization you pick there. | Revoke the “(connected)” token in Settings, sign in again from the client, and pick the right organization before Connect. |
After Connect the browser shows “connection refused” or an error on localhost |
The client stopped listening for the answer (it timed out, or was closed), or a proxy blocked localhost. |
Start the sign-in again. Some clients, Claude Code included, also let you paste the full address from the browser’s address bar back into the client. |
| “Sign in as an organization owner or administrator to connect an app.” | Your role in that organization is member or viewer. | Ask an owner or admin to connect, or to change your role. |
| “Dynamic Client Registration rejected” or “No authorization support detected” | An old client version that doesn’t support MCP sign-in, or a network proxy blocking api.looot.ai/.well-known/* or /oauth/register. |
Update the client. On a company network, check that those paths reach api.looot.ai. Or use the header-token fallback. |
| “This connection request is invalid or has expired” on looot.ai | The sign-in link is old or was already used. | Start the sign-in again from the client. |
Check the server from a terminal
This should answer 401 with a www-authenticate header that names resource_metadata:
curl -s -o /dev/null -D - -X POST https://api.looot.ai/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | grep -i -E '^HTTP|www-authenticate'That header is how a compliant client finds looot’s sign-in in the first place. If you don’t see
www-authenticate, the request didn’t reach looot: check a proxy or firewall between you and
api.looot.ai.
With a header token, the same request should return the tool list instead:
curl -s https://api.looot.ai/mcp -X POST \
-H "Authorization: Bearer $LOOOT_TOKEN" \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'