---
title: Connection troubleshooting
description: Fix a client that can't sign in, lost its tools, or gets a 401 or 402 when talking to looot.
sidebar:
  label: Troubleshooting
---

## 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`](/errors/rest-errors#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](https://looot.ai/usage?top_up=1) or ask the agent to call [`top_up`](/mcp-tools/top-up) and pay the link. The [`balance`](/mcp-tools/balance) tool reports the current minimum. Then run again with a new idempotency key. |
| [`forbidden`](/errors/rest-errors#forbidden) on [`run`](/mcp-tools/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`:

```bash
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:

```bash
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"}'
```

<Related />