> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for the most common MCP installation and runtime issues

If something is not working, the cause is almost always one of: the MCP client cannot reach the server, the OAuth flow did not complete, your assistant is in a mode that does not call tools, or you hit a permission or rate-limit error coming back from Qonto.

## The MCP client does not see any tools

After installing, your assistant lists zero tools or claims it cannot reach Qonto.

* **Confirm the URL** is exactly `https://mcp.qonto.com/mcp` (with the trailing `/mcp`). Several clients silently fail when the path is missing.
* **Restart the client** after adding the server. Claude Desktop, Cursor, and VS Code only refresh their tool catalog on startup or on an explicit MCP refresh.
* **Run the OAuth flow once.** Until the client has a valid token, `tools/list` returns an empty result. In Claude Code, type `/mcp` and click **Authenticate**. In Cursor / VS Code, invoke any Qonto tool from chat to trigger the browser flow.

## The OAuth window opens but never finishes

You sign in to Qonto, consent, and the window hangs.

* **Disable pop-up blockers** for the redirect URL. The flow uses two short windows; aggressive blockers swallow the second one.
* **Check your network**. Corporate proxies that strip `Authorization` headers break the token-exchange step. Try from a personal network to confirm.
* **Try again from a fresh browser tab.** Stale state in the original tab is the most common cause.

If the issue persists, remove the server from your MCP client, revoke the in-flight consent from the **connected apps** section of your Qonto account, and reinstall.

## Tools are listed but every call returns an authentication error

The MCP client has a token, but the server rejects every call.

* The token may have been **revoked** while you were chatting. Open the **connected apps** section of your Qonto account and confirm the entry is still listed.
* The client may be **using a stale token** because of a clock drift. Restart the MCP client; it will refresh the token.
* If you switched organizations on Qonto's side, you may need to **re-run the consent flow** so the token is bound to the right organization.

## Tools return "forbidden" or "scope missing"

The call reached Qonto but Qonto refused it.

* Some operations require **owner or admin** privileges (member invitations, certain card lifecycle transitions). Depending on your role, you may not have permission to perform them and the call will fail.
* The MCP client only requested the **scopes it needs**. If a tool was added after you authorized, you may need to remove the server and reinstall to trigger a fresh consent that includes the new scopes.

## Tools time out or rate-limit

* The MCP server is subject to the same rate limits as the Business API. See [Rate limitations](/get-started/general/rate-limitations) for the current ceilings. Ask your assistant to slow down or batch the work.
* A few list endpoints page heavily. If you ask for "all transactions since 2024" in one go, the assistant may exhaust the page budget. Constrain by date range, account, or counterparty.

## My assistant says it called a tool, but I see no result

* In **VS Code Copilot Chat**, MCP tools only run in **Agent mode**. The default Ask mode does not invoke them. Switch via the model picker in the chat composer.
* In **Claude Desktop**, the **Connectors** toggle in the composer must include **Qonto**. The first time you use a tool in a conversation, Claude asks you to allow it.
* In **ChatGPT**, you have to **enable the Custom Connector** in the composer for each conversation.

## SCA prompt never arrives

A write operation needs SCA, and the Qonto mobile app does not buzz.

* Make sure **push notifications** are enabled for Qonto on the device that holds your SCA factor.
* Open the Qonto app manually. Pending SCA prompts are listed inside the app even if the push never arrived.
* If the prompt expired, the assistant will need to **re-run the tool**, which queues a fresh SCA challenge.

## Where to ask for help

* Check the [Business API troubleshooting guide](/get-started/general/troubleshooting) for issues that are not MCP-specific.
* For OAuth and connector questions, the [Developer Portal](https://developers.qonto.com) and the [Business API authentication overview](/get-started/business-api/authentication/introduction) cover the underlying flow.
* For account-level issues (your Qonto role, plan limits, SCA factors), reach out via the in-app support chat.