OpenAI Codex connects to QuickBooks Online through DeepLedger's hosted MCP server: add https://mcp.deepledger.ai/mcp to Codex as a Streamable HTTP server and sign in with your DeepLedger account. The same configuration serves the Codex CLI, the Codex desktop app and the IDE extension on one computer. This guide covers the OAuth route for everyday use and the API-key route for codex exec on a machine without a browser.
What are you connecting?
DeepLedger runs a hosted QuickBooks MCP server. An admin connects each QuickBooks Online company to DeepLedger once, through Intuit's sign-in. Codex then signs in to DeepLedger as you and reaches the companies you can access. Codex never sees an Intuit token, and you don't need an Intuit developer app or a local server.
| Codex surface | Where the setting lives | Sign-in |
|---|---|---|
| Codex CLI | ~/.codex/config.toml | OAuth, or an API key from an environment variable |
| Codex desktop app | Settings → MCP servers | OAuth |
| Codex IDE extension | Gear menu → MCP servers | OAuth |
| ChatGPT on the web | Does not read the local file | Use the ChatGPT guide |
Before you start
- A DeepLedger account with access to the intended QuickBooks Online company.
- A current Codex CLI, desktop app or IDE extension. As of October 2026, OpenAI's plan page lists Codex across ChatGPT plans with different usage limits; workspace policy can restrict MCP servers.
- A demo company for the first run.
How do I connect Codex CLI to QuickBooks Online?
- Connect the QuickBooks company in DeepLedger. In DeepLedger, open Companies, select the company, open its Connections tab and choose Connect to QuickBooks. Complete Intuit's sign-in.
- Add DeepLedger to the Codex configuration. Add the DeepLedger server to
~/.codex/config.toml, keeping your other settings.
[mcp_servers.deepledger]
url = "https://mcp.deepledger.ai/mcp"
The equivalent command is codex mcp add deepledger --url https://mcp.deepledger.ai/mcp. Use one method, not both.
- Sign in with DeepLedger. Run the login command and sign in with your DeepLedger account in the browser that opens.
codex mcp login deepledger
- Check the server and tools. Run
codex mcp list, then type/mcpin a Codex session to see DeepLedger and its tools. - Ask which company you are in. Start a Codex session and ask which company DeepLedger is using.
Using DeepLedger, which company am I in?
Codex reads the company profile and names the company, its currency and its fiscal year start. DeepLedger supports OAuth discovery and dynamic client registration, so there is no client ID or token to paste.
How do I connect the Codex desktop app or IDE extension?
- In the desktop app, open Settings → MCP servers. In the IDE extension, open the gear menu and choose MCP servers.
- Choose Add server and name it DeepLedger.
- Select Streamable HTTP and enter
https://mcp.deepledger.ai/mcp. - Save, then restart the app or extension.
- Choose Authenticate if Codex asks, and sign in with DeepLedger.
Local Codex clients on the same computer share this configuration. See OpenAI's MCP instructions if a menu has moved.
How do I use a DeepLedger API key with Codex?
Use a key when Codex runs without a browser, for example codex exec on a build server. Any team member can create one.
- In DeepLedger, open Settings → API keys and choose Create key.
- Name it for the machine, pick an Expiration, and choose All my companies or One company.
- Copy the key. It starts with
dl_live_and is shown once. - Export it on the machine and tell Codex which variable holds it:
export DEEPLEDGER_API_KEY="dl_live_..."
[mcp_servers.deepledger]
url = "https://mcp.deepledger.ai/mcp"
bearer_token_env_var = "DEEPLEDGER_API_KEY"
bearer_token_env_var is Codex's documented setting for a bearer token read from the environment, so the key never sits in the config file. The key acts as the person who created it, with that person's access. A One company key works only in that company. There is no read-only switch on a key.
A script that runs codex exec on a timer is your own job acting as the key's owner. DeepLedger does not start anything on its own.
Next step: verify one company and one report
Ask Codex:
Using DeepLedger, list the companies I can access and identify the active company. Ask me which company to use, then switch to it and confirm its name. Do not create or change accounting records.
Then a bounded report:
Using DeepLedger for [confirmed company], retrieve the profit and loss for September 1 through September 30, 2026, on an accrual basis. Show the company name, dates, basis, currency, income, expenses and net income. Do not create or change accounting records.
In QuickBooks Online → Reports → Profit and Loss, run the same company, dates and basis, and compare the totals. Your active company is shared across your connected AI apps, so confirm it again when you change sessions. See selecting the right QuickBooks company. Follow the P&L analysis and verification workflow for what to compare.
What can Codex do in QuickBooks after connecting?
DeepLedger works when you ask: Codex acts only when you tell it to. Ask it to read the company's AI Brain and skills first, so it follows that client's rules.
- Purchases: bills, expenses, bill payments and vendor credits.
- Sales: estimates, invoices, customer payments, sales receipts and credits.
- Other transactions: deposits, transfers and journal entries.
- Reports: profit and loss, balance sheet, cash flow, aging, general ledger and trial balance, plus saved custom reports.
- Month-end close: close checks, proposed entries and statements in the Close Sheet, which a person signs off.
- Tasks: questions and handoffs between you and the AI in DeepLedger's Tasks.
Try these prompts after the report check:
Using DeepLedger for [company], prepare an unpaid bill from this attached vendor invoice. Check for duplicates, propose the expense categories, and show me the bill before recording it.
In DeepLedger for [company], save a custom report called "Monthly business review": last month's accrual profit and loss compared with the prior month, plus the balance sheet as of last month-end. Run it now.
Is it safe to let Codex write to QuickBooks?
DeepLedger keeps the guardrails on the server, not in the prompt:
- Every write must carry its company (
companyId). If it is missing or differs from the active company, DeepLedger refuses withCOMPANY_REQUIREDorCOMPANY_MISMATCHand nothing is written. - Voids and deletes need confirmation. A void keeps the record; a delete of a posted transaction is refused on or before the company's closing date.
- Duplicate and open-document checks on supported recording paths.
DeepLedger also instructs the AI to send uncertain work to Tasks for a person to decide. That is guidance the AI follows, not a server lock, so review what it proposes.
Review each proposed write in Codex's approval prompt. A prompt that says "do not change records" is not a read-only permission. More in AI write access to QuickBooks, safely.
Troubleshooting
DeepLedger is missing from /mcp. The config belongs to a different host or profile. A project-level .codex/config.toml loads only in a trusted project. Restart Codex after editing.
OAuth stays pending or returns 401. Run codex mcp login deepledger again with the right DeepLedger account. In a remote terminal where the browser callback can't reach Codex, finish login on the machine running Codex, or use the API-key route. Never paste authorization codes into chat.
401 with an API key. Check that DEEPLEDGER_API_KEY is set in the shell that starts Codex, and that the key hasn't expired or been revoked under Settings → API keys.
Tools are blocked. Your workspace's MCP policy may not allow the server. Ask an administrator to approve the DeepLedger URL.
A write fails with COMPANY_MISMATCH. Another app switched your active company. Nothing was written. Ask Codex to confirm the company, then try again.
Reports fail after a successful switch. That company's QuickBooks connection needs an admin to reconnect it on its Connections tab in DeepLedger.
Use a demo company for the first run.
Documentation and configuration last verified November 7, 2026. This guide was checked against the linked vendor documentation and DeepLedger's server implementation. We did not complete a new OAuth grant or retrieve an account-level report in this client during this revision. The prompts are suggested checks, not claimed test results. Have the account owner complete sign-in and the demo-company report comparison above before using business data.
Frequently asked questions
How do I connect OpenAI Codex to QuickBooks Online?
Add DeepLedger's MCP server to Codex with codex mcp add deepledger --url https://mcp.deepledger.ai/mcp, or add the same URL under mcp_servers.deepledger in ~/.codex/config.toml. Run codex mcp login deepledger and sign in with your DeepLedger account. Codex then has DeepLedger's QuickBooks tools for the companies you can access.
Do I need an API key to use Codex with QuickBooks?
No, not for interactive use. Codex signs in to DeepLedger with OAuth in your browser. Use a DeepLedger API key only when Codex runs without a browser, such as codex exec on a build server; any team member can create one under Settings, API keys, Create key.
Does ChatGPT on the web use my Codex MCP configuration?
No. ChatGPT on the web does not read your local ~/.codex/config.toml file. The configuration applies to the Codex CLI, the desktop app and the IDE extension on the same computer. For ChatGPT itself, follow DeepLedger's ChatGPT setup guide.
Can Codex change my QuickBooks books?
Yes, if you ask it to and approve the action. DeepLedger exposes write tools for bills, invoices, expenses, deposits and journal entries. Every write must carry its company in companyId or DeepLedger refuses it and nothing is written, and voids and deletes need confirmation.
How do I disconnect Codex from DeepLedger?
Run codex mcp logout deepledger to clear the stored sign-in, and codex mcp remove deepledger to remove the server from Codex. If you used an API key, revoke it in DeepLedger under Settings, API keys. None of these steps deletes accounting records.
Related guides
- QuickBooks MCP server guide
- Connect Cursor to QuickBooks Online
- Build a custom QuickBooks AI agent with an API key
- First real task: review journal entries with AI
Browse all AI platforms and integrations.