Introduction

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 and the 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 instead. If you cannot add a connector, use an API key.

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.

1. Kill existing MCP connections

$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.

$rm -rf ~/.mcp-auth

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

If a tool returns a permission error, your dashboard role may not allow that tool. See 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 for the expected configuration.