> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/mcp/introduction/troubleshooting/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Troubleshooting

## Authentication problems

If you're experiencing issues connecting to the MCP server, try these debugging steps.

### Use a custom connector in Claude

If Claude Desktop login fails, add Ada as a custom connector. Do not use `mcp-remote` unless you cannot add a connector.

See [Connect Claude](/mcp/introduction/authentication#connect-claude) and the [Claude](/mcp/introduction/getting-started/claude) walk-through.

On a Team or Enterprise plan, a Claude organization Owner must add the URL first. If you do not see Ada in **Customize > Connectors**, ask a Claude organization Owner to add it.

### Two login tabs in Claude Desktop

This applies only if you use `mcp-remote`. Claude Desktop can start two copies of the helper. Each copy can open a browser tab. This is expected.

1. Complete login in one tab.
2. Close the other tab.
3. If Claude still shows a failed connection, restart Claude Desktop.

After a successful login, the helper saves login data on disk. A restart reuses that login data.

If browser login keeps failing, add a [custom connector](/mcp/introduction/authentication#connect-claude) instead. If you cannot add a connector, use an API key.

### Unverified application warning on the authorization page

Desktop clients such as ChatGPT finish OAuth on a local address. The authorization page shows a redirect to `127.0.0.1` with a port number. It warns that the application is unverified. This is expected.

1. Confirm that the redirect address starts with `127.0.0.1`.
2. Click **Allow access**.
3. Return to your client. Confirm that the server shows as connected.

If the redirect address is not a local address, click **Cancel**. Then check the URL you entered in your client.

### Connection fails after a successful login

If the browser shows success and Claude shows a failure, restart Claude Desktop. If you use `mcp-remote`, the helper reuses the saved login data.

### Check the helper version

This applies only if you use `mcp-remote`. Open `claude_desktop_config.json`. Confirm the `args` list includes `mcp-remote@0.2.5`. If the list has `mcp-remote` with no version, add `@0.2.5`. Restart Claude Desktop.

See [Authentication](/mcp/introduction/authentication#pin-the-local-helper-version).

### 1. Kill existing MCP connections

```bash
pkill -f mcp-remote
```

### 2. Clear the MCP auth cache

Clear the cache only if a restart does not fix the problem. Clearing the cache deletes saved login data. You must log in again.

```bash
rm -rf ~/.mcp-auth
```

After you run these commands, restart your MCP client. Then connect again.

> **Tip**
>
> If a tool returns a permission error, your dashboard role may not allow that tool. See [Permissions](/mcp/introduction/authentication#permissions) for the role-to-tool mapping.

## ADK-specific issues

**401 Unauthorized**

* Ensure your API key is valid.
* Verify the Authorization header is formatted as `Bearer <key>`.

**405 Method Not Allowed**

* Ensure you are sending POST requests to `/mcp`.
* SSE (GET streaming) is not supported.

See the [Google ADK setup page](/mcp/introduction/getting-started/google-adk) for the expected configuration.