# Troubleshoot an MCP connection

- HTML page: https://www.billabex.com/en/help/billabex-with-ai/troubleshoot-mcp-connection/
- Language: en
- Version française: https://www.billabex.com/fr/aide/billabex-avec-ia/depanner-connexion-mcp.md
- Updated: 2026-07-17
- Site index: https://www.billabex.com/llms.txt

<section class="help-summary" aria-labelledby="in-short"><h2 id="in-short">In short</h2><p>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.</p></section>

## 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

1. Compare the client URL with the one shown by Billabex, character by character.
2. Disconnect and reconnect once to complete OAuth with the correct account.
3. Check `mcp:read` for reading and `mcp:write` only for a modification.
4. Test the organization list, then a targeted read with a known identifier.
5. 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.