Troubleshoot an MCP connection

In short

Troubleshoot MCP in a fixed order: confirm the official URL, observe the OAuth handoff, check scopes, then run a simple read in the correct organization. Opening the URL directly in a browser does not test the connector. Keep the exact message and time if the error persists.

Expected result

You identify whether the block comes from client configuration, Billabex authorization, data scope, or excessive calls.

Before you start

Keep access to AI client settings and Settings > Integrations in Billabex.
Do not expose secrets in a screenshot or support request.

Procedure

Compare the client URL with the one shown by Billabex, character by character.
Disconnect and reconnect once to complete OAuth with the correct account.
Check mcp:read for reading and mcp:write only for a modification.
Test the organization list, then a targeted read with a known identifier.
If the error mentions a limit, space out calls; otherwise keep the time, client, tool, and exact message for support.

What Billabex does

The server requires valid authentication, rate-limits excessive calls, and rejects a tool when its scope or organization does not match. Client-facing error codes and formats belong to the versioned developer documentation.

If the result is not what you expected

A response obtained by opening the URL in a browser does not prove that the server is unavailable.
Empty data can indicate the wrong organization rather than a transport failure.
Mask tokens, cookies, and Authorization headers before sending a screenshot to support.