Quick Start - MCP - Dolfin AI

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 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)
An MCP-capable client — Claude Desktop, Cursor, Claude Code, VS Code, Windsurf, etc.

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.

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

Cursor
Claude Desktop
Claude Code
VS Code
Windsurf

Cursor reads MCP servers from ~/.cursor/mcp.json (global) or .cursor/mcp.json inside a project. Create the file if it doesn’t exist:

{
  "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.

Claude Desktop only speaks stdio, so we bridge to the HTTP server with 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

{
  "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.

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.

The fastest path is the CLI:

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:

{
  "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.

Create .vscode/mcp.json in your workspace (or use MCP: Add Server from the command palette):

{
  "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.

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "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.

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:

The organisation ID in the URL is a valid UUID for an organisation under your client.
The API key is correct and not revoked.
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.

Authentication reference

Header conventions, key rotation, and bearer-token alternatives.

​Prerequisites

​The endpoint

​Configure your client

​Verify it works

​What the agent can do

Authentication reference

Prerequisites

The endpoint

Configure your client

Verify it works

What the agent can do