DeepLedgerA connected MCP server does not necessarily mean your AI agent can read the QuickBooks company you intend to use. There are several separate checks: the agent must discover the tools, sign in to DeepLedger, select a company you can access and reach that company's authorized QuickBooks connection.
This guide covers DeepLedger's QuickBooks MCP connection. Other servers may have different errors and recovery steps. Start with the symptom you see rather than disconnecting everything at once.
| What you see | First thing to check |
|---|---|
| The agent says it has no QuickBooks tools | Whether DeepLedger is enabled for this conversation |
| Sign-in fails or you see an authentication error | The agent's authorization to DeepLedger |
NO_ACTIVE_COMPANY | Choose a company from the accessible company list |
Tools load, but reports return QB_NOT_CONNECTED or TOKEN_EXPIRED | That company's QuickBooks authorization |
| A report runs but looks wrong | Company, dates, basis, filters and missing detail pages |
1. Check whether the agent can see the tools
An agent can explain QuickBooks from general knowledge without having any access to your books. Ask it to inspect its available tools:
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, check the app, connector or plugin settings in your AI client. Confirm the configured DeepLedger endpoint is:
https://mcp.deepledger.ai/mcp
Enable the connection for the conversation where the client requires it. If you recently changed or reauthorized the connector, refresh its tools or start a new conversation before testing again.
Follow the instructions for your actual client: Claude, ChatGPT, Grok or Muse. Their setup screens are different. For example, xAI documents a Custom connector flow for Grok chat; that is not evidence that the same screen exists in Grok Bot. xAI connector documentation.
2. Check the DeepLedger sign-in
Your AI client authenticates to DeepLedger. DeepLedger separately holds the QuickBooks authorization for each connected company. Fixing one does not automatically repair the other.
For an interactive connector, complete its DeepLedger sign-in flow using the account that has access to your company. If the connector reports an expired or revoked authorization, use its reconnect flow and then repeat the company-profile test.
For a custom agent using an API key, check that it is using a current DeepLedger key. An xAI or other model-provider key cannot authenticate to the DeepLedger MCP server. Check the key's status and expiration in Settings > API Access; 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 has access to every company in your business.
3. Resolve an absent or ambiguous company
If DeepLedger returns NO_ACTIVE_COMPANY, 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.
Replace the fictional company name with yours. If the company is missing, check your DeepLedger membership and company access. Repeating the same prompt cannot grant access you do not have.
For similar company names, choose from the organization IDs returned by the tool. Do not invent an ID or substitute a QuickBooks realm ID.
Your personal connection normally shares its active company across your AI clients. A company switch in one conversation can affect another. For parallel developer jobs, use the company-pinning instructions in our multiple-company guide. A SWITCH_NOT_ALLOWED response can mean the request is already pinned to a company; it is not necessarily a broken connection.
4. Repair the company's QuickBooks connection
If the agent can list companies but a report returns QB_NOT_CONNECTED or TOKEN_EXPIRED, inspect the selected company in DeepLedger under Settings > Company and QBO Connect.
Have someone with the appropriate QuickBooks access complete the reconnect flow for that company. Then rerun the company profile and one report. Refreshing the AI client's tool list alone will not repair an expired Intuit authorization.
For Intuit Enterprise Suite, check the particular entity you need. A connection to one entity is not proof of authorized access to every related entity. Our IES connection guide explains the supported route and limits.
5. Test with a small, explicit report
Once the company profile succeeds, 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.
If this succeeds, compare it with the same report in QuickBooks. A different date range or cash/accrual basis can produce a different answer even when the connection works correctly.
For detail reports, ask the agent to retrieve every required page before explaining the transactions. DeepLedger exposes row counts and offsets; a successful first page may not contain the whole report. Its summary totals can cover the full report even when only part of the detail is returned.
If QuickBooks refuses a particular report or filter, inspect the error and the company's feature settings. Do not assume that reconnecting will enable a feature the company does not have.
If you still need help
Send the AI client name, the step that failed, the error code, the approximate time and whether the company-profile test succeeded through DeepLedger support. A redacted screenshot can help. Leave passwords, API keys, authorization tokens and private financial documents out of an initial support message.
Once the profile and report succeed for the intended company, return to your original workflow. If an earlier write timed out, inspect QuickBooks for the resulting record before trying that write again; an unclear response does not prove that nothing was saved.