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

# Quick Start - MCP

> Connect Dolfin to Claude, Cursor, and other MCP-compatible clients

The Dolfin MCP server exposes the same Accounts Receivable, Accounts Payable, and organisation tools available to the Dolfin agent — directly inside any [Model Context Protocol](https://modelcontextprotocol.io) client. Drop a small block of JSON into your client's config file and the assistant gains the ability to create customers, draft invoices, schedule payments, and more on behalf of an organisation.

## Prerequisites

* A Dolfin **API key**
* An **organisation ID** to scope tool calls to (see [Client Integration](/guides/client-integration))
* An MCP-capable client — Claude Desktop, Cursor, Claude Code, VS Code, Windsurf, etc.

<Note>
  The MCP server is a single streamable HTTP endpoint authenticated with the same `x-dolfin-api-key` header used elsewhere in the API. The organisation is encoded in the URL path, so you do **not** send `x-dolfin-organisation-id` separately.
</Note>

## The endpoint

```
https://api.dolfinai.co/mcp/{organisationId}
```

| Required | Header / Path      | Value                                                     |
| -------- | ------------------ | --------------------------------------------------------- |
| Path     | `{organisationId}` | The UUID of the organisation the assistant should act for |
| Header   | `x-dolfin-api-key` | Your Dolfin API key                                       |

That's the entire contract. Every client below is just a different way of expressing those two values in a config file.

***

## Configure your client

<Tabs>
  <Tab title="Cursor">
    Cursor reads MCP servers from `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` inside a project. Create the file if it doesn't exist:

    ```json theme={null}
    {
      "mcpServers": {
        "dolfin": {
          "url": "https://api.dolfinai.co/mcp/9a658587-fe02-402e-b1ac-bfaf53274ef8",
          "headers": {
            "x-dolfin-api-key": "dol_live_abc123"
          }
        }
      }
    }
    ```

    Restart Cursor. Open **Settings → MCP** and confirm `dolfin` appears with a green dot.
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop only speaks stdio, so we bridge to the HTTP server with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) (no install needed — `npx` fetches it on first run).

    Edit the config file:

    * **macOS** — `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows** — `%APPDATA%\Claude\claude_desktop_config.json`

    ```json theme={null}
    {
      "mcpServers": {
        "dolfin": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://api.dolfinai.co/mcp/9a658587-fe02-402e-b1ac-bfaf53274ef8",
            "--header",
            "x-dolfin-api-key:${DOLFIN_API_KEY}"
          ],
          "env": {
            "DOLFIN_API_KEY": "dol_live_abc123"
          }
        }
      }
    }
    ```

    Quit and reopen Claude Desktop — the tools icon in the input bar should now list Dolfin tools.

    <Note>
      The `${DOLFIN_API_KEY}` indirection keeps the key out of the `args` array (which appears in process listings). Replace the literal value if you don't care.
    </Note>
  </Tab>

  <Tab title="Claude Code">
    The fastest path is the CLI:

    ```bash theme={null}
    claude mcp add --transport http dolfin \
      https://api.dolfinai.co/mcp/9a658587-fe02-402e-b1ac-bfaf53274ef8 \
      --header "x-dolfin-api-key: dol_live_abc123"
    ```

    Or edit `~/.claude.json` directly:

    ```json theme={null}
    {
      "mcpServers": {
        "dolfin": {
          "type": "http",
          "url": "https://api.dolfinai.co/mcp/9a658587-fe02-402e-b1ac-bfaf53274ef8",
          "headers": {
            "x-dolfin-api-key": "dol_live_abc123"
          }
        }
      }
    }
    ```

    Run `/mcp` inside Claude Code to verify the server is connected.
  </Tab>

  <Tab title="VS Code">
    Create `.vscode/mcp.json` in your workspace (or use **MCP: Add Server** from the command palette):

    ```json theme={null}
    {
      "servers": {
        "dolfin": {
          "type": "http",
          "url": "https://api.dolfinai.co/mcp/9a658587-fe02-402e-b1ac-bfaf53274ef8",
          "headers": {
            "x-dolfin-api-key": "${input:dolfinApiKey}"
          }
        }
      },
      "inputs": [
        {
          "id": "dolfinApiKey",
          "type": "promptString",
          "description": "Dolfin API key",
          "password": true
        }
      ]
    }
    ```

    The `inputs` block prompts for the key the first time the server starts and caches it for the session — keys never get committed to source.
  </Tab>

  <Tab title="Windsurf">
    Edit `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "dolfin": {
          "serverUrl": "https://api.dolfinai.co/mcp/9a658587-fe02-402e-b1ac-bfaf53274ef8",
          "headers": {
            "x-dolfin-api-key": "dol_live_abc123"
          }
        }
      }
    }
    ```

    Reload Windsurf and check **Settings → Cascade → MCP Servers**.
  </Tab>
</Tabs>

***

## Verify it works

Once your client reconnects, ask the assistant something like:

> List the last 5 invoices and tell me which are overdue.

The assistant will call the `list_invoices` tool against your organisation and summarise the result. If you instead see an authentication or 404 error, check:

1. The organisation ID in the URL is a valid UUID for an organisation under your client.
2. The API key is correct and not revoked.
3. Your client is sending the header — some clients silently drop unknown header keys.

## What the agent can do

The MCP server exposes the same tool surface as the Dolfin AR/AP agents:

* **Customers, products, invoices** — create, list, search, send, mark paid
* **Suppliers, bills, payments** — create from staged uploads, approve, schedule, confirm paid
* **Organisations & tax rates** — read and update org settings, manage tax rates
* **Payment accounts** — check status and enable for an organisation

Mutating tools (`approve_bill`, `schedule_payment`, `send_invoice`) prompt the assistant to confirm with you before running. Read tools (`list_*`, `get_*`, `search_*`) are cheap and the assistant will lean on them before making changes.

<Card title="Authentication reference" icon="key" href="/guides/authentication">
  Header conventions, key rotation, and bearer-token alternatives.
</Card>