Skip to navigation

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. An API key is an alternative if your organization permits it. With individual settings enabled, new keys need an Owner to allow tools.

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 you use a desktop client and the redirect address is not a local address, click Cancel. Then check the URL you entered in your client. Web clients such as Microsoft Copilot Studio finish OAuth on their own web address, not a local address.

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.

Tool access problems

Reconnecting does not change saved tool permissions.

A tool is missing or returns 403

  1. Go to Config > PLATFORM > MCP server with the account you use for OAuth.
  2. If you are not an Owner, check Allowed MCP tools.
  3. Ask an Owner to check Global settings and Individual settings.
  4. Check that your dashboard role permits the tool.
  5. If permissions changed, refresh the assistant’s tool list or reconnect.

API-key tools stop working

With individual settings enabled, new and replacement keys have no MCP tools until an Owner allows them.

  1. Ask an Owner to open API keys under Individual settings on the MCP server page.
  2. Find the integration’s key by its name and masked identifier.
  3. Check the key’s allowed tools and Global settings.
  4. Retry the tool call.

If the key does not appear, see Manage API key access.

Tool access is temporarily unavailable

If the server cannot check permissions, it blocks the tool request and returns 503. Retry after a short wait. If the error continues, contact Support with the time, tool name, and error message.

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.