> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conductor.is/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect AI tools like Claude, Cursor, and Codex to QuickBooks Desktop

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](#read-only-mode) blocks writes outright.

## Setup

1. In the [Dashboard](https://dashboard.conductor.is), open your project's **MCP** tab. Pick your tool, click **Create key and fill in config**, and copy the block; it already contains a new secret key.
2. Paste the block where your tool expects it, shown in the tabs below.
3. Your AI tool can run on any computer, but QuickBooks Desktop and the Web Connector must be running on the computer you connected to Conductor. Then ask the agent a question.

The examples below show `sk_conductor_...` where the Dashboard fills in your real key.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={"system"}
    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.
  </Tab>

  <Tab title="Claude Desktop">
    Open **Settings > Developer > Edit Config** in Claude Desktop and add:

    ```json claude_desktop_config.json theme={"system"}
    {
      "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. The config needs [Node.js](https://nodejs.org) (the LTS version) installed. Fully quit and reopen Claude Desktop. The same config works on macOS and Windows.

    claude.ai in the browser cannot connect because its connectors support only OAuth.
  </Tab>

  <Tab title="Claude Cowork">
    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:

    ```text theme={"system"}
    URL: https://mcp.conductor.is/
    Header: Authorization: Bearer sk_conductor_...
    ```
  </Tab>

  <Tab title="Cursor">
    ```json ~/.cursor/mcp.json theme={"system"}
    {
      "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.
  </Tab>

  <Tab title="VS Code">
    Run **MCP: Open User Configuration** from the Command Palette (or use `.vscode/mcp.json` in a workspace). Note the top-level key is `servers`:

    ```json mcp.json theme={"system"}
    {
      "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.
  </Tab>

  <Tab title="Codex CLI">
    ```bash theme={"system"}
    codex mcp add conductor --url https://mcp.conductor.is/ --bearer-token-env-var CONDUCTOR_SECRET_KEY
    ```

    This adds the server to `~/.codex/config.toml`. Then 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.
  </Tab>

  <Tab title="ChatGPT and other clients">
    Any client that supports HTTP servers with custom headers works:

    ```json theme={"system"}
    {
      "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 needs only Node.js and forwards everything to our hosted server.
  </Tab>
</Tabs>

## 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, using the same key as in Setup (above). Update your existing Conductor entry instead of adding a second one; with two entries, your tool may ignore the read-only one or fail to load its config.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={"system"}
    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.
  </Tab>

  <Tab title="Claude Desktop">
    Add `--code-allow-http-gets` to the `args` line of the config from Setup (the same on macOS and Windows), then fully quit and reopen Claude Desktop:

    ```json claude_desktop_config.json theme={"system"}
    {
      "mcpServers": {
        "conductor": {
          "command": "npx",
          "args": ["-y", "conductor-node-mcp", "--code-allow-http-gets"],
          "env": { "CONDUCTOR_SECRET_KEY": "sk_conductor_..." }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Cowork">
    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:

    ```text theme={"system"}
    x-stainless-mcp-client-permissions: {"allow_http_gets":true}
    ```
  </Tab>

  <Tab title="Cursor">
    ```json ~/.cursor/mcp.json theme={"system"}
    {
      "mcpServers": {
        "conductor": {
          "url": "https://mcp.conductor.is/",
          "headers": {
            "Authorization": "Bearer sk_conductor_...",
            "x-stainless-mcp-client-permissions": "{\"allow_http_gets\":true}"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    ```json mcp.json theme={"system"}
    {
      "servers": {
        "conductor": {
          "type": "http",
          "url": "https://mcp.conductor.is/",
          "headers": {
            "Authorization": "Bearer sk_conductor_...",
            "x-stainless-mcp-client-permissions": "{\"allow_http_gets\":true}"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex CLI">
    The `codex mcp add` command cannot set headers, so add the `http_headers` line to the server entry in `~/.codex/config.toml`:

    ```toml ~/.codex/config.toml theme={"system"}
    [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}' }
    ```
  </Tab>

  <Tab title="ChatGPT and other clients">
    Add one extra header alongside your secret key:

    ```json theme={"system"}
    {
      "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.
  </Tab>
</Tabs>

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 isn't reaching the server, so the connection is still full-access. If your tool can't connect after you add the header, the header value is malformed; it must be exact JSON.

<Warning>
  Read-only mode is a guardrail, not a security boundary: it inspects the
  agent's code for write methods, and it limits the connection, not the key.
  Anyone with your secret key can still make changes through our API directly,
  so create a separate key for each person you share with and revoke it when
  needed.
</Warning>

## Verify it works

Ask the agent: *"Show the 5 most recent invoices using my most recently successful QuickBooks Desktop connection."* 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

<Accordion title="The API key is missing or invalid, or Claude Desktop says the server failed to start">
  Create a fresh key and copy the config from the Dashboard's **MCP** tab, then
  restart your tool. A 401 error echoes the key masked (`sk_conductor_...last4`)
  so you can see which key your client sent. If Claude Desktop still says the
  server failed to start, install [Node.js](https://nodejs.org) (the LTS
  version), which provides the `npx` command its config runs, then fully quit
  and reopen Claude Desktop.
</Accordion>

<Accordion title="Setup is correct, but requests to QuickBooks still fail">
  QuickBooks Desktop and the Web Connector must be running on the computer you
  connected to Conductor, which does not have to be the one running your AI
  tool. MCP requests travel through your existing connection like any other
  Conductor API call, so no Web Connector changes are needed.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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`.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.