DeepLedger
Menu
← All articlesFor developers

For developers

Connect Codex to QuickBooks Online with DeepLedger MCP

Configure DeepLedger in local Codex CLI, desktop or IDE, authorize with OAuth, and verify a fixed-period QuickBooks report.

Published by DeepLedger7 min read

Local Codex clients can use DeepLedger's hosted MCP server to work with QuickBooks Online. Your Codex host stores the connection configuration; DeepLedger connects to the company authorized through Intuit. Start with a reporting task before considering bookkeeping writes.

What you can do after connecting

Through DeepLedger, you can ask your AI agent to:

  • Record purchases: bills, expenses, bill payments, and vendor credits.
  • Manage sales records: estimates, invoices, customer payments, sales receipts, customer credits, and refund receipts.
  • Record other transactions: bank deposits, transfers between accounts, and journal entries.
  • Run reports: profit and loss, balance sheet, cash flow, accounts receivable and payable aging, general ledger, and trial balance.
  • Prepare month-end close: track close checks, flag issues, assemble financial statements, and propose adjusting entries in DeepLedger's Close Sheet. You review the work and sign off in the portal.
  • Work through tasks: raise questions, request missing documents, hand work between you and the AI agent, and track resolution in DeepLedger's Tasks.
  • Find supporting information: look up customers, vendors, accounts, transactions, connected bank-feed entries, and uploaded documents.

Before you start

Step 1: Configure the local Codex host

In ~/.codex/config.toml, add this table without replacing your other settings:

[mcp_servers.deepledger]
url = "https://mcp.deepledger.ai/mcp"

This is a Streamable HTTP endpoint. The equivalent CLI command is:

codex mcp add deepledger --url https://mcp.deepledger.ai/mcp

Use one method. The installed CLI's codex mcp add --help confirms the URL option; check your version if it differs.

Step 2: Complete OAuth and check tools

If prompted during setup, complete browser authorization with your DeepLedger account. Otherwise run:

codex mcp login deepledger
codex mcp list

Use /mcp in the CLI session to inspect active servers. DeepLedger advertises OAuth discovery and dynamic client registration; no Intuit developer app or pasted token is needed for this route.

Desktop and IDE setup

Open Settings → MCP servers in desktop, or the gear menu's MCP servers in the IDE. Choose Add server, name it DeepLedger, select Streamable HTTP, enter the URL above, save, and restart the client or extension. Choose Authenticate if sign-in is required. These local clients share configuration on the same host. See OpenAI's MCP instructions.

Local configuration versus cloud plugins

ChatGPT web does not read your local TOML file. Hosted ChatGPT tools come through plugins and workspace controls; cloud environments need their own available tools and authentication. Do not treat a working local server as a tested cloud connection. This guide verifies local configuration syntax, not DeepLedger catalog availability or a cloud plugin installation.

Next step: verify one company and one report

In DeepLedger Settings → Company and QBO Connect, find the intended company under Companies. If it is not connected, choose Connect QB and have an authorized person complete Intuit sign-in. Start with a demo company when testing a new AI provider; do not send private business reports until your organization has approved that provider and its data settings.

With DeepLedger enabled in your AI client, ask:

Using DeepLedger, list the companies I can access and identify the active company. Ask me which company to use. After I choose, select it and confirm its name and company identifier. Do not create or change accounting records.

Company selection can persist across your connected AI clients. Confirm it again when changing sessions; a company-bound credential may not allow switching. See selecting the right QuickBooks company.

Then replace the bracketed name with that confirmed company:

Using DeepLedger for [confirmed company], retrieve the profit and loss for September 1 through September 30, 2026, on an accrual basis. Show the returned company name and identifier, exact dates, accounting basis, currency, income, expenses and net income. Do not create or change accounting records. If the company or report settings cannot be confirmed, stop and explain the missing information.

In QuickBooks Online → Reports → Profit and Loss, run the report for the same company, September 1–30, 2026, accrual basis, currency and filters. Compare income, expenses and net income, then investigate any differing account lines. A successful tool response includes report data and matching context; a “connected” badge or an AI summary alone is not verification. If totals differ, correct the context and rerun before relying on the result. Follow the P&L analysis and verification workflow.

A read-only prompt is not read-only permissions. The connection can expose write tools; review permissions and proposed actions. After the report agrees, choose a real task from the journal-entry review workflow or overdue-invoice workflow, adapting the client-specific steps to your AI app.

Example prompts to try next

Replace the bracketed details with your own company, dates and account names.

Record a paid expense

Using DeepLedger for [company], record a [currency and amount] software subscription paid to [vendor] on [date] from [bank or credit card account], categorized to [expense account]. Check for an existing transaction and show me the proposed entry before saving. After I confirm, record it and return the QuickBooks transaction reference.

Record an unpaid bill

Using DeepLedger for [company], prepare an unpaid bill from this attached vendor invoice. Check for duplicates, use the invoice number, date, due date, line amounts and taxes, and propose the expense categories. Ask me for missing details and show the bill for confirmation before recording it.

Run financial reports

Using DeepLedger for [company], get the profit and loss for [start date] through [end date] and the balance sheet as of [end date], using [cash or accrual] basis. Show the company, dates, currency and report totals, then summarize the main changes from the previous period.

Save and reuse a custom report

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. Include instructions to highlight the largest changes in income and expenses. Run it now.

Next time:

Using DeepLedger for [company], run my saved "Monthly business review" for [start date] through [end date].

The custom report definition is saved in DeepLedger and retrieves current QuickBooks data each time you run it.

Troubleshooting

  • Server missing: verify the config belongs to the host running the session. A project-scoped .codex/config.toml only loads in a trusted project. Restart after editing.
  • OAuth pending or 401: retry the login command with the correct DeepLedger account. If browser callbacks fail in a remote terminal, finish login on the intended host; do not paste authorization codes or tokens into chat.
  • Tools blocked: inspect /mcp and your workspace's MCP policy. Ask an administrator to approve the intended server; do not disable organization controls.
  • Wrong company or report: use the company check above, reconnect QuickBooks in DeepLedger if required, and rerun with explicit settings.
  • Disconnect: codex mcp logout deepledger clears stored OAuth credentials; codex mcp remove deepledger removes the local server configuration. Neither deletes accounting records.

Testing scope and next action

Documentation and configuration last verified October 2, 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.

Return to AI platforms and integrations or resolve a connection error with the MCP troubleshooting guide.

Ready to get started?

Connect QuickBooks and try your first task with an AI agent.

Create an Account