MCP

Use Conductor’s MCP server to let you and your co-workers interact with QuickBooks Desktop through Claude, Cursor, Codex, and other AI tools. Ask questions about your QuickBooks Desktop data in plain English, and the agent searches your company file and finds the answer: overdue invoices, a vendor’s payment history, last month’s sales. By default the agent can read and write your data; agents generally change data only when you ask, and read-only mode blocks writes outright.

Setup

You need two things: a Conductor secret key (get one here) and at least one QuickBooks Desktop connection, with QuickBooks and the Web Connector running on that computer. In every example below, replace sk_conductor_... with your actual secret key.

claude mcp add --transport http conductor https://mcp.conductor.is/ --header "Authorization: Bearer sk_conductor_..."

Add --scope user to make it available in all your projects.

Claude Desktop’s custom connectors support only OAuth servers, so use our npm package. It needs two free tools: Node.js and Deno. Install Node.js first, then open a terminal (on macOS: Applications > Utilities > Terminal) and run npm install -g deno.Open Settings > Developer > Edit Config to edit the config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json) and add:

claude_desktop_config.json

{
  "mcpServers": {
    "conductor": {
      "command": "npx",
      "args": ["-y", "conductor-node-mcp"],
      "env": { "CONDUCTOR_SECRET_KEY": "sk_conductor_..." }
    }
  }
}

If the file already has an mcpServers section, add the conductor entry inside it instead of pasting the whole block. Restart Claude Desktop to load it.On Windows, the npm package does not currently work (its sandbox needs POSIX-only features). Use this config instead; it connects through our hosted server and needs only Node.js:

claude_desktop_config.json

{
  "mcpServers": {
    "conductor": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.conductor.is/", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer sk_conductor_..." }
    }
  }
}

claude.ai in the browser cannot connect: its custom connectors support only OAuth, so there is no way to send the key.

In CoWork’s connector settings, add a connector with our server URL and one request header, or ask Claude in CoWork to add it for you:

URL: https://mcp.conductor.is/
Header: Authorization: Bearer sk_conductor_...

~/.cursor/mcp.json

{
  "mcpServers": {
    "conductor": {
      "url": "https://mcp.conductor.is/",
      "headers": { "Authorization": "Bearer sk_conductor_..." }
    }
  }
}

Use .cursor/mcp.json inside a project to scope it to that project. After saving, the server appears in Cursor Settings under MCP with a toggle; no restart is needed.

Run MCP: Open User Configuration from the Command Palette (or use .vscode/mcp.json in a workspace). Note the top-level key is servers:

mcp.json

{
  "servers": {
    "conductor": {
      "type": "http",
      "url": "https://mcp.conductor.is/",
      "headers": { "Authorization": "Bearer sk_conductor_..." }
    }
  }
}

VS Code asks you to trust the server on first use; after any config change, click the restart link that appears above the entry.

~/.codex/config.toml

[mcp_servers.conductor]
url = "https://mcp.conductor.is/"
bearer_token_env_var = "CONDUCTOR_SECRET_KEY"

Set CONDUCTOR_SECRET_KEY to your raw sk_conductor_... key in your shell profile, so it is set wherever you run Codex; Codex adds the Bearer prefix.

Any client that supports HTTP servers with custom headers works:

{
  "url": "https://mcp.conductor.is/",
  "headers": { "Authorization": "Bearer sk_conductor_..." }
}

ChatGPT on the web accepts only OAuth connectors, so it cannot add the hosted server; use Codex CLI instead.If your client only supports local (stdio) servers, run npx -y conductor-node-mcp with the CONDUCTOR_SECRET_KEY environment variable set. It requires Node.js and Deno on your PATH (npm install -g deno).

Read-only mode

Read-only mode lets the agent look up your data and run reports, but blocks requests that create, update, or delete data before they reach QuickBooks. Use it for a trial, an accountant, or co-workers who should see your data without changing it. Turn it on for your tool below; as in Setup, replace sk_conductor_... with your actual secret key.

claude mcp add --transport http conductor https://mcp.conductor.is/ --header "Authorization: Bearer sk_conductor_..." --header 'x-stainless-mcp-client-permissions: {"allow_http_gets":true}'

If you already added the server, run claude mcp remove conductor first.

Add --code-allow-http-gets to the args line of the config from Setup, then restart Claude Desktop:

claude_desktop_config.json

{
  "mcpServers": {
    "conductor": {
      "command": "npx",
      "args": ["-y", "conductor-node-mcp", "--code-allow-http-gets"],
      "env": { "CONDUCTOR_SECRET_KEY": "sk_conductor_..." }
    }
  }
}

On Windows (the mcp-remote config from Setup), add two args instead: "--header", "x-stainless-mcp-client-permissions:{\"allow_http_gets\":true}".

Ask Claude in CoWork to add this request header to your Conductor connector, or add it yourself in the connector settings next to your existing Authorization header:

x-stainless-mcp-client-permissions: {"allow_http_gets":true}

~/.cursor/mcp.json

{
  "mcpServers": {
    "conductor": {
      "url": "https://mcp.conductor.is/",
      "headers": {
        "Authorization": "Bearer sk_conductor_...",
        "x-stainless-mcp-client-permissions": "{\"allow_http_gets\":true}"
      }
    }
  }
}

mcp.json

{
  "servers": {
    "conductor": {
      "type": "http",
      "url": "https://mcp.conductor.is/",
      "headers": {
        "Authorization": "Bearer sk_conductor_...",
        "x-stainless-mcp-client-permissions": "{\"allow_http_gets\":true}"
      }
    }
  }
}

~/.codex/config.toml

[mcp_servers.conductor]
url = "https://mcp.conductor.is/"
bearer_token_env_var = "CONDUCTOR_SECRET_KEY"
http_headers = { "x-stainless-mcp-client-permissions" = '{"allow_http_gets":true}' }

Add one extra header alongside your secret key:

{
  "headers": {
    "Authorization": "Bearer sk_conductor_...",
    "x-stainless-mcp-client-permissions": "{\"allow_http_gets\":true}"
  }
}

If your client runs the local package (conductor-node-mcp) instead, add the --code-allow-http-gets flag to its arguments.

To verify, ask the agent to create a test customer: it should report that the method is blocked by the MCP server. If it creates the customer instead, the header value is malformed (it must be exact JSON) and the connection is still full-access.

Read-only mode is a guardrail for normal agent behavior, not a hard security boundary: it works by inspecting the agent’s code for write-method names. And it limits the connection, not the key: someone with your secret key can still make changes by using it directly against our API. Share keys only with people you trust, and create a separate secret key for each shared connection so you can revoke one without affecting the rest.

Verify it works

Ask the agent to “list my QuickBooks Desktop connections and show the 5 most recent invoices”. If it returns real data from your company file, you are set up. Do not trust your client’s “connected” indicator alone: the key is only checked when the agent actually requests data. If it errors, see Troubleshooting below.

Troubleshooting

It connects, but says the API key is missing or invalid

If you see Failed to initialize client: The CONDUCTOR_SECRET_KEY environment variable is missing or empty, your key never reached the server (wrong header name, stripped header, or missing env variable). If you see a 401 with "code":"API_KEY_INVALID", the error echoes the key masked (sk_conductor_...last4) so you can see which key your client actually sent.

Setup is correct, but requests to QuickBooks still fail

QuickBooks Desktop must be running on the connected computer for data calls to succeed. MCP needs no Web Connector changes: its requests travel through your existing connection like any other Conductor API call, and share that connection’s queue.

Can my co-workers use the same key on other computers?

Yes. The same key and URL work from any number of machines and AI clients. Pricing is per QuickBooks company file, not per connection or seat.

I see SEO or marketing tools, not QuickBooks (wrong Conductor)

An unrelated SEO company at conductor.com runs its own MCP server, and AI tools sometimes find it instead of ours. If you see SEO tools like ai_brand_insights or keyword_insights, or “couldn’t identify the caller” errors, you connected to that server. Remove it and use https://mcp.conductor.is/; ours is conductor.is and exposes only execute and search_docs.

Running the local server fails with a Deno error

The local package needs Deno. Install it from deno.land or run npm install -g deno. The hosted server needs no install.

Getting Started

Usage

QuickBooks Desktop

Setup

Read-only mode

Verify it works

Troubleshooting

​Setup

​Read-only mode

​Verify it works

​Troubleshooting

Setup

Read-only mode

Verify it works

Troubleshooting