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

# AI integration

> Connect an AI assistant to your books over MCP.

Equated runs an MCP server at `/mcp`. It's how an assistant turns "prepare month-end" into Equated actions — reading the review checklist, inspecting transactions, linking documents, and proposing changes you approve.

Everything below is also available from **Settings → AI Agents** in the app, with the URL filled in for your workspace.

## Connect your assistant

<Tip>
  **Let your agent handle setup.** Paste `Read https://app.equated.co/setup.md and follow it to connect Equated.` into ChatGPT desktop Work mode, Claude Code, Codex CLI, Cursor, or Antigravity (desktop app or CLI). It registers the server, guides you through sign-in, and verifies the connection. Hosted chat apps use the account-level steps below.
</Tip>

<Tabs>
  <Tab title="Claude.ai / Desktop / Claude Cowork">
    <Steps>
      <Step title="Add a custom connector">
        Go to **Customize → Connectors** (or **Settings → Connectors** in desktop), then **+ → Add custom connector**. On Team and Enterprise plans, an owner must first add Equated under **Organization settings → Connectors**.
      </Step>

      <Step title="Paste the server URL">
        ```
        https://app.equated.co/mcp
        ```
      </Step>

      <Step title="Sign in">
        Click **Connect** and sign in to Equated. Leave advanced OAuth client credentials empty.
      </Step>

      <Step title="Turn it on in a session">
        In a chat or Claude Cowork session, open the **+** menu → **Connectors** and switch Equated on. One connector covers claude.ai, the desktop app, Claude Cowork, and mobile, so an agent running inside those apps can't register it for you.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Register the server">
        ```bash theme={null}
        claude mcp add --scope user --transport http equated https://app.equated.co/mcp
        ```

        `--scope user` registers Equated for every Claude Code session on your machine. Without it, Claude Code files the server under the directory you ran the command in, and it won't be there in your other projects.
      </Step>

      <Step title="Sign in">
        Run `/mcp`, select Equated, and choose **Authenticate**. Complete sign-in in your browser. Reuse an existing working connection instead of registering it again.
      </Step>

      <Step title="Use it">
        Ask Claude to use Equated for a books task. Run `/mcp` to inspect the connection and its tools.
      </Step>
    </Steps>
  </Tab>

  <Tab title="ChatGPT desktop app (Work mode)">
    Paste the setup prompt into Work mode. Your agent checks the existing connection, registers it if needed, and starts browser sign-in. You approve access; the agent verifies it by calling `list_accounts`.

    Desktop Work mode shares local MCP configuration with Codex CLI and the Codex IDE extension on the same computer. It does not configure ChatGPT web. If you prefer terminal setup, use the Codex CLI tab.
  </Tab>

  <Tab title="ChatGPT web (Work mode)">
    <Steps>
      <Step title="Enable developer mode">
        Turn it on under **Settings → Security and login → Developer mode**. Availability depends on your account and workspace policy.
      </Step>

      <Step title="Connect a custom MCP">
        Open **Plugins**, click **+**, and enter Equated as the name with a short description. A published directory listing is not required.
      </Step>

      <Step title="Connect the public endpoint">
        Under **Connection**, enter the hosted MCP URL:

        ```
        https://app.equated.co/mcp
        ```

        No local command or tunnel is needed. Web Work does not read your computer's Codex MCP configuration.
      </Step>

      <Step title="Sign in">
        Create the connection, sign in, and review the discovered tools. Enable Equated from the tools menu in a new conversation.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Codex CLI">
    <Steps>
      <Step title="Register the server">
        Check `codex mcp get equated` first. If the correct connection already exists, reuse it. Otherwise:

        ```bash theme={null}
        codex mcp add equated --url https://app.equated.co/mcp
        ```
      </Step>

      <Step title="Sign in">
        The add command may start OAuth automatically. Let it finish; do not run a second login. Only if authentication is still required:

        ```bash theme={null}
        codex mcp login equated
        ```

        Finish signing in to Equated in your browser.
      </Step>

      <Step title="Use it">
        Ask Codex to call Equated's `list_accounts` and report the account count. Try the current session before starting a new one.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    Merge this entry into `~/.cursor/mcp.json`, preserving other servers:

    ```json theme={null}
    {
      "mcpServers": {
        "equated": { "url": "https://app.equated.co/mcp" }
      }
    }
    ```

    Follow Equated's authentication prompt in **Customize**, or let the agent initiate it if an authentication tool is available. Then ask for `list_accounts`.
  </Tab>

  <Tab title="Antigravity desktop app">
    Antigravity is Google's agentic app, not the Gemini web chat at [gemini.google.com](https://gemini.google.com/app) — that one has no MCP support, so the setup prompt does nothing there.

    Paste the setup prompt into the desktop agent. It can merge Equated into the app's global `mcp_config.json` itself; the CLI is not required. Confirm the path used by your installed app through its MCP settings before editing.

    ```json theme={null}
    {
      "mcpServers": {
        "equated": { "serverUrl": "https://app.equated.co/mcp" }
      }
    }
    ```

    Preserve other servers, refresh Equated in MCP settings, and choose **Authenticate** under **Settings → Customizations** when needed. Complete browser sign-in and enter any returned code only in the authentication panel. Ask the agent to call `list_accounts` to verify access.

    Equated uses hosted Streamable HTTP and OAuth. No local package, command, environment variables, or API key is needed. See [Antigravity's desktop MCP documentation](https://antigravity.google/docs/mcp).
  </Tab>

  <Tab title="Antigravity CLI">
    In `agy`, open `/mcp`. Confirm the global config location for your installed version; current docs use `~/.gemini/config/mcp_config.json`. Merge without replacing other entries:

    ```json theme={null}
    {
      "mcpServers": {
        "equated": { "serverUrl": "https://app.equated.co/mcp" }
      }
    }
    ```

    Use `serverUrl`, not Gemini CLI's `httpUrl`. The Gemini web chat is a separate product and cannot connect to MCP servers. Reload through `/mcp`, follow the OAuth prompt, and ask for `list_accounts`. No OAuth client credentials or Google credentials are needed. Enter any authorization code only in the client's authentication UI, not agent chat.
  </Tab>

  <Tab title="VS Code">
    Run **MCP: Add Server** from the Command Palette. Choose **HTTP**, enter `https://app.equated.co/mcp`, name it `equated`, and select **Global**. Approve trust and sign in when prompted. Inspect it with **MCP: List Servers**, enable its tools in agent chat, and ask for `list_accounts`.

    Manual setup uses **MCP: Open User Configuration** with a `servers` object, not `mcpServers`:

    ```json theme={null}
    {
      "servers": {
        "equated": { "type": "http", "url": "https://app.equated.co/mcp" }
      }
    }
    ```
  </Tab>
</Tabs>

<Note>Replace the host with your own Equated workspace URL.</Note>

Setup is verified when `list_accounts` succeeds, including an empty account list. A saved configuration alone does not prove access. If tools are missing, check the URL, enabled state, authentication, and client logs before reloading or starting a new session.

Client instructions checked September 9, 2026 against [Claude Code](https://code.claude.com/docs/en/mcp), [Claude connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp), [ChatGPT desktop and CLI](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), [ChatGPT web](https://developers.openai.com/plugins/deploy/connect-chatgpt), [Cursor](https://cursor.com/docs/mcp), [Antigravity CLI](https://antigravity.google/docs/cli/mcp), and [VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers).

## Authentication

Connecting through the app is keyless — your assistant signs in with OAuth and Equated issues it a token scoped to your organization.

For a script or a server-side client that can't complete a browser sign-in, pass an API token from **Settings → API Tokens** instead:

```bash theme={null}
Authorization: Bearer int_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

The same token works for the REST API. Browser session cookies are deliberately rejected on `/mcp`, so a signed-in tab can't be used as credentials. See [Authentication](/api/authentication).

## What your agent already knows

Your assistant doesn't need to be taught your accounting model, and you don't need to paste it a procedure. On connect the server hands it the rules it has to follow plus a map of every job it can do, so an ordinary sentence — "pay my open bills and link the transactions that paid them" — is enough. It looks up the steps for that job before it touches anything, which is why the steps can improve without you rewriting a prompt.

From the first message it knows:

* **How a transaction moves.** Imported, then categorized in your inbox, then confirmed and counted in your balances. A confirmed transaction has to be unconfirmed before it can be changed or deleted; while it's still in the inbox you can delete it outright, and a deleted bank-synced transaction won't come back on the next sync.
* **What it can categorize onto.** Your chart of accounts is a mix of folders and the postable accounts inside them; only the latter are valid targets.
* **When to ask first.** Your explicit request or standing instructions can authorize work. Otherwise the assistant shows the proposed change and asks before committing it. Any instruction to ask first still applies.
* **How splitting actually works.** There's no split tool. A split replaces a journal entry's posting set with a balanced one, keeping the bank side untouched.
* **To work in batches.** Confirming sixty transactions is one call, not sixty.

## Available tools

Your assistant lists the current tools when it connects, so the set it sees is always the live one. Today that covers transactions, documents, bills and invoices, the chart of accounts, merchants, reconciliation and opening balances, financial reports (profit and loss, balance sheet, cash flow, general ledger), journal entries and their audit history, QuickBooks migration checks, and automation rules.

For exact request and response shapes, see the API Reference — the MCP tools and the REST endpoints run on the same services.

<Tip>
  See [Action safety](/api/action-safety) for the preview-and-execute contract, and [Connect your AI](/for-agents) for what you can hand off.
</Tip>