When a QuickBooks MCP connection is not working, one of five links has failed: the AI app's tools, the DeepLedger sign-in, the company selection, that company's QuickBooks authorization, or the report settings. This guide covers DeepLedger's QuickBooks MCP server at https://mcp.deepledger.ai/mcp, used from Claude, ChatGPT, Grok, Cursor and other AI apps. Start with the symptom you see rather than disconnecting everything at once.
For first-time setup, start with the QuickBooks MCP server guide.
What is wrong? Symptom, cause and fix
| What you see | Likely cause | Fix |
|---|---|---|
| The AI says it has no QuickBooks tools | DeepLedger is not enabled in this conversation, or the tool list is stale | Check 1 |
| Sign-in fails or an authentication error appears | The AI app's authorization to DeepLedger expired, or the API key is wrong or revoked | Check 2 |
NO_ACTIVE_COMPANY | No company is selected | Check 3: list companies, then switch |
COMPANY_REQUIRED or COMPANY_MISMATCH on a write | The write named no company, or a different company from the active one | Check 3: the AI must ask you which company |
A switch is refused, or SWITCH_NOT_ALLOWED | A one-company API key, or a request pinned with an X-Organization-Id header | Check 3: use an all-companies key or change the header |
QB_NOT_CONNECTED or TOKEN_EXPIRED | That company's QuickBooks authorization expired or was revoked | Check 4: reconnect on the company's Connections tab |
| A report runs but looks wrong | Company, dates, basis, filters or missing detail pages | Check 5 |
1. Can the AI see the tools?
An AI can explain QuickBooks from general knowledge without any access to your books. Ask it to check:
Check whether DeepLedger's QuickBooks tools are available in this
conversation. If they are, use the company profile tool to read the
active company and report the result. Do not create or change any
QuickBooks records. If you cannot call the tool, say that clearly.
If no tools are available, open the connector or MCP settings in your AI app and confirm the address is:
https://mcp.deepledger.ai/mcp
Enable the connector for the conversation if your app requires it. After changing or reauthorizing the connector, refresh its tools or start a new conversation before testing again.
Setup screens differ by app: Claude, ChatGPT and Grok each have their own guide. For example, xAI documents a Custom connector flow for Grok chat in its connector documentation; Grok Bot uses a different path.
2. Is the DeepLedger sign-in valid?
Your AI app authenticates to DeepLedger. DeepLedger separately holds the QuickBooks authorization for each connected company. Fixing one does not repair the other.
Interactive AI apps such as Claude, ChatGPT, Grok and Cursor sign in with OAuth. If the connector reports an expired or revoked authorization, use its reconnect option, sign in with the DeepLedger account that has access to the company, and repeat the company-profile test.
A custom agent uses a DeepLedger API key. Check that it is sending a current DeepLedger key (dl_live_...), read from an environment variable. An xAI, OpenAI or other model-provider key cannot authenticate to DeepLedger. In DeepLedger, open Settings → API keys to see whether the key is active or revoked. Any team member can create a key there with Create key. Keep the full value out of chat messages and logs.
A successful sign-in proves who you are. It does not prove that your account can reach every company in the firm. Non-admin members see only the companies they are assigned to.
3. Is the right company selected?
NO_ACTIVE_COMPANY. No company is active yet. Ask:
List the companies I can access through DeepLedger and show their
QuickBooks connection status. I want to work in Pinebridge Studio.
If there is exactly one matching company, select it and read its
QuickBooks company profile. If there are several matches, ask me
which one to use. Do not create or change accounting records.
If the company is missing, an owner or admin needs to assign you to it in DeepLedger. Repeating the prompt cannot grant access you do not have. For similar names, choose by the organization ID the tool returns, never a QuickBooks realm ID.
COMPANY_REQUIRED or COMPANY_MISMATCH. These are DeepLedger's company write guard working as intended. Every write must name its company. If the company is missing, or differs from the active company, DeepLedger refuses the write and nothing is written. The AI must ask you which company you mean; it should not pick one and retry on its own. Reads and switching are not affected. A mismatch often means the active company changed: your active company is shared across your AI apps, so a switch in Claude carries over to ChatGPT.
Which company am I in? I meant to record this bill in Pinebridge Studio.
A switch is refused. A one-company API key works only in the company it was created for and cannot switch. Create a key with All my companies under Settings → API keys → Create key, or keep one key per company for jobs that must stay put. A request pinned with an X-Organization-Id header also cannot switch; change the header instead. The multiple-company guide explains pinning for parallel jobs.
4. Is the company's QuickBooks connection current?
If the AI can list companies but a report returns QB_NOT_CONNECTED or TOKEN_EXPIRED, that company's Intuit authorization has expired or been revoked. Refreshing the AI app's tools will not fix it.
- In DeepLedger, open Companies and select the company.
- Open its Connections tab.
- An admin chooses Connect to QuickBooks and completes the Intuit sign-in.
- Back in the AI app, ask "Which company am I in?" and run one report.
Tasks, documents and the company's AI Brain keep working for that company while QuickBooks is disconnected; only QuickBooks reads and writes wait for the reconnect.
For Intuit Enterprise Suite, check the entity you need. A connection to one entity does not authorize every related entity. The IES connection guide covers the supported route.
5. Does one small report agree with QuickBooks?
Once the company profile works, use one report to separate connection problems from report settings:
For Pinebridge Studio, retrieve Profit and Loss for August 1-31, 2026,
on the accrual basis, with no class, location or customer filters.
Show the company, home currency, date range, basis and report totals.
Do not create or change records. If the request fails, return the
error code and explain which step failed.
Compare the result with the same report in QuickBooks. A different date range or cash or accrual basis gives a different answer even when the connection is fine.
For detail reports, ask the AI to retrieve every page before explaining the transactions. A successful first page may not contain the whole report, although summary totals cover the full report.
If QuickBooks refuses a report or filter, read the error and the company's QuickBooks plan. Reconnecting does not enable a feature the company does not have.
If you still need help
Send the AI app name, the step that failed, the error code, the approximate time and whether the company-profile test succeeded to DeepLedger support. A redacted screenshot helps. Leave passwords, API keys, tokens and private financial documents out of the first message.
If an earlier write timed out, look in QuickBooks for the resulting record before trying the write again. An unclear response does not prove that nothing was saved.
Frequently asked questions
Why is my QuickBooks MCP connector not working?
Usually one of five links is broken: the AI app has not loaded the tools, the DeepLedger sign-in has expired, no company or the wrong company is selected, the company's QuickBooks authorization has expired, or the report settings differ from what you expected. Ask the AI which company it is in. The answer, or the error code it returns, tells you which link to fix.
What does COMPANY_REQUIRED or COMPANY_MISMATCH mean?
Every write through DeepLedger must name its company. COMPANY_REQUIRED means the write named no company, and COMPANY_MISMATCH means it named a different company from the active one. DeepLedger refused the write and nothing was saved. The AI should ask you which company you mean, then try again with that company.
How do I fix QB_NOT_CONNECTED or TOKEN_EXPIRED?
The company's QuickBooks authorization has expired or been revoked on Intuit's side. An admin opens Companies in DeepLedger, selects the company, opens its Connections tab and chooses Connect to QuickBooks to sign in to Intuit again. Reconnecting the AI app does not fix it.
Why can't my API key switch companies?
The key was created for one company. A one-company key works only in that company and cannot switch. Create a new key under Settings, API keys, Create key and choose All my companies, or keep one key per company for jobs that must stay in one company.
Do I need to reconnect everything when one company fails?
No. The AI app's sign-in to DeepLedger and each company's QuickBooks authorization are separate. Fix only the link that failed, then run the company profile and one report to confirm.
Related guides
- QuickBooks MCP server guide
- Connect Claude to QuickBooks Online
- Work in multiple QuickBooks companies with one sign-in
See every supported AI app on AI Platforms & Integrations. Once the report test passes, try a first real task: ask for last month's profit and loss and compare it with QuickBooks.