Connect Custom AI Agents to QuickBooks with an API Key

Your custom AI agent can connect to DeepLedger using an API key and the hosted MCP endpoint. Connect your QuickBooks Online company in DeepLedger, create a personal key, and send it as a bearer token from your agent's server or local runtime.

This works with an agent host that supports remote MCP and custom authentication headers. If you already use LangChain or LangGraph or CrewAI, those guides show their framework-specific configuration. The example below uses the MCP SDK directly, so you can reuse the connection inside your own agent loop.

1. Connect Your QuickBooks Company

Sign in to DeepLedger. In Settings > Companies, find the intended company, choose Connect to QuickBooks and complete Intuit's authorization flow.

Your custom agent connects to DeepLedger; DeepLedger handles the connection to QuickBooks Online. You do not need a separate Intuit developer app for this hosted setup. The DeepLedger key is different from an Intuit access token and from your model provider's API key.

2. Create a DeepLedger API Key

A DeepLedger firm owner or admin can open Settings > API Access and select Create API Key. Enter a descriptive name, choose an expiration, and copy the full key when it appears. It is shown once.

Store the key in your runtime's secret manager. For the local example below, put it in a .env file:

DEEPLEDGER_API_KEY=your_full_key_here

Add .env to your project's .gitignore. Keep the key out of browser code, prompts, source control, and logs. The secret belongs in the process that makes the MCP request, not in the model's conversation.

A personal key acts as its creator and can reach every company that person can access. It is not a read-only key or automatically limited to the company visible when you created it. You can revoke it in Settings > API Access when the integration is retired or the key needs replacing.

3. Test the Connection with Node.js

Use Node.js 22 or newer. In a new project folder, install the SDK version used by this example:

npm init -y
npm install @modelcontextprotocol/sdk@1.30.0 zod@4

The imports below follow the MCP TypeScript SDK's v1 client API. Its Streamable HTTP transport accepts custom request headers through requestInit.

Save this as connect-deepledger.mjs:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const apiKey = process.env.DEEPLEDGER_API_KEY;
if (!apiKey) throw new Error("Set DEEPLEDGER_API_KEY before running.");

const client = new Client({ name: "custom-bookkeeping-agent", version: "1.0.0" });
const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.deepledger.ai/mcp"),
  { requestInit: { headers: { Authorization: `Bearer ${apiKey}` } } },
);

try {
  await client.connect(transport);

  const tools = [];
  let cursor;
  do {
    const page = await client.listTools(cursor ? { cursor } : {});
    tools.push(...page.tools);
    cursor = page.nextCursor;
  } while (cursor);

  if (!tools.some((tool) => tool.name === "qbCompanyProfile")) {
    throw new Error("The company-profile tool was not returned.");
  }

  const result = await client.callTool({
    name: "qbCompanyProfile",
    arguments: { operation: "profile" },
  });
  if (result.isError) {
    throw new Error("Company check failed. Review the connection and active company.");
  }

  const text = result.content.find((item) => item.type === "text");
  const profile = result.structuredContent ?? JSON.parse(text?.text ?? "{}");
  if (profile.success !== true) {
    throw new Error(
      `${profile.errorCode ?? "PROFILE_FAILED"}: ${profile.message ?? "Check your active company and QuickBooks connection."}`,
    );
  }

  console.log(JSON.stringify(profile, null, 2));
} finally {
  await client.close();
}

Run it from the folder containing your .env file:

node --env-file=.env connect-deepledger.mjs

This example discovers the tools and reads the active company's profile. It does not ask a model to make decisions or change QuickBooks records. Review the returned company identity and settings before adding a report or recording workflow. The output contains company information, so keep the terminal output private.

4. Select the Right Company

If no company is active, call qbCompanyProfile with operation: "list". Choose an accessible company from that result, then call the same tool with operation: "switch" and its returned organizationId. Read the profile again to confirm the selection.

A switch changes the person's active company across their connected AI clients. Separate keys created by the same person do not create separate company contexts. Coordinate jobs that switch companies, and verify the company returned with each result. See the multiple-company connection guide for details.

5. Use the Connection in Your Agent

Keep the MCP client connected for the duration of your agent run. Your host application connects the model's tool requests to MCP:

1. Discover the tools with listTools(). Each tool supplies a name, description, and inputSchema.
2. Give your model only the tools needed for its current task. For a first reporting workflow, start with company-profile reads and qbReports.
3. Validate the model's requested tool name and arguments in your application, then dispatch it through client.callTool({ name, arguments }). Limit qbCompanyProfile to the profile operation unless your application explicitly supports company switching.
4. Return the tool result to the model using your model provider's tool-result format. Preserve errors; an unsuccessful call is not an empty report.
5. Close the client when the run finishes.

These are host responsibilities: an MCP connection alone does not implement a model loop. The MCP client concepts describe the distinction between the host application and its MCP client.

A local tool filter narrows what your agent can choose; it does not reduce the permissions of the underlying API key. Before adding writes, implement the review and validation flow for those specific operations, including the company, duplicate checks, and recovery from failed calls. Start in a demo company and check results in QuickBooks.

Next step: verify one company and one report

In DeepLedger Settings → Companies, find the intended company. If it is not connected, choose Connect to QuickBooks 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.

Troubleshooting

401 Unauthorized: Check that the key is complete, unexpired, and not revoked. The header must include Bearer before the key. Do not send an Intuit token or a model-provider key to the DeepLedger endpoint.

No active company: List accessible companies, select one explicitly, and repeat the profile check.

QuickBooks connection error: Reconnect the intended company in Settings > Companies. Repeatedly changing the MCP configuration will not repair a disconnected QuickBooks authorization.

The host asks for a local command instead of a URL: Use its remote HTTP/MCP option. This connection uses a hosted Streamable HTTP server, not a local stdio subprocess.

The company is different from the one you expected: Stop the workflow and check whether another client using the same person's access changed the active company. Creating another personal key for that person does not isolate the selection.

Browse the supported integrations for ready-made client guides, or read the QuickBooks MCP server overview to compare hosted and self-managed connections.