MCP Server Pro

The LUCA MCP Server

Let an AI agent keep the books. The MCP server gives Claude, ChatGPT, Cursor and any other MCP client LUCA's accounting as tools it can call: record sales and bills, take payments, post journals, and read the reports.

What you need

A LUCA login, and a company you can create API tokens in. Today that means a company on the Pro plan.
An AI app that speaks MCP over Streamable HTTP: Claude, ChatGPT, Cursor, VS Code and others.

Connect

Add the server address as a connector in your AI app. The app opens LUCA in your browser: sign in, pick the company, and approve. That's all. No token to copy.

Server URL: https://api.luca.pro/mcp
Transport: Streamable HTTP
Authentication: OAuth sign-in (your app handles it)

Each connection works in the one company you pick. To work in another company, connect it separately. To cut an app off, revoke it under Settings → API Tokens → Connected apps.

Claude Code

Terminal

claude mcp add --transport http luca https://api.luca.pro/mcp

Start Claude Code, type /mcp, choose luca and sign in. Then ask “List my companies.”

Optional: to let lookups and reports run without asking each time, add this to your project's .claude/settings.json. Anything that records or changes something still asks.

JSON

{
  "permissions": {
    "allow": [
      "mcp__luca__aged_payables",
      "mcp__luca__aged_receivables",
      "mcp__luca__balance_sheet",
      "mcp__luca__chart_of_accounts",
      "mcp__luca__document_pdf",
      "mcp__luca__find_customer",
      "mcp__luca__find_item",
      "mcp__luca__find_vendor",
      "mcp__luca__general_ledger",
      "mcp__luca__get_bill",
      "mcp__luca__get_journal",
      "mcp__luca__get_quotation",
      "mcp__luca__get_sale",
      "mcp__luca__list_bills",
      "mcp__luca__list_companies",
      "mcp__luca__list_journal_drafts",
      "mcp__luca__list_journals",
      "mcp__luca__list_quotations",
      "mcp__luca__list_sales",
      "mcp__luca__payment_methods",
      "mcp__luca__profit_and_loss",
      "mcp__luca__report_file",
      "mcp__luca__tax_codes",
      "mcp__luca__trial_balance"
    ]
  }
}

Scripts and apps that can't sign in

Create an API token under Settings → API Tokens and send it as a bearer credential on every request. It is the same token the REST API uses.

JSON

{
  "mcpServers": {
    "luca": {
      "type": "http",
      "url": "https://api.luca.pro/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Warning Anyone holding a token can post to that company's books. Keep it out of chat, screenshots and committed files, and revoke it under Settings → API Tokens if it leaks.

How it behaves

One company per connection. An app you connect, or an API token, works in one company, and list_companies marks it as current. For another company, connect it separately or create a token with that company selected.
Your permissions, no more. Tools act as the person who connected the app or created the token. The tool list only shows the tools that person can use, so a view-only user is offered no write tools.
Live books, no sandbox. Unlike the API reference, there is no mock behind /mcp. Sales, bills, payments and notes post to the ledger the moment they are recorded. Try it on a test company first.
Safe to retry a posting. Every tool that records something new in the ledger takes an idempotency_key taken from the source document: an invoice number, a supplier's bill reference, a bank statement line. Reusing a key is refused with a 409 error carrying existing_id, the original document's id, so nothing posts twice. The create_*, update_* and send_* tools take no key: check with a find_* tool before retrying a create, and don't retry a send, because each call emails the customer again.
Journals can wait for a person. post_journal posts straight away. draft_journal stages a journal for someone to approve or reject first.
Corrections follow the accounting rules. Once money has moved against a document, it is corrected with a credit or debit note, not by amending or voiding it.
Same rate limit as the API. Each MCP request counts once against the 60 requests per minute per user that the REST API allows.

Tools

55 tools, grouped the way a bookkeeper works. The names are accounting words, not LUCA screen names, so an agent that knows double entry but has never seen LUCA can use them. Each tool carries its own description, and every write tool a worked example, which your client shows the agent.

Group	What it covers	Tools
Set-up and lookups16 tools	Resolve ids before posting, and add the accounts, customers, vendors, items and payment methods that don't exist yet.	`list_companies` `chart_of_accounts` `create_account` `update_account` `tax_codes` `payment_methods` `create_payment_method` `find_customer` `create_customer` `update_customer` `find_vendor` `create_vendor` `update_vendor` `find_item` `create_item` `update_item`
Sales8 tools	Record cash and credit sales and invoices, renew recurring invoices, take payments, issue credit notes, and email invoices and reminders.	`record_sale` `renew_invoice` `get_sale` `list_sales` `receive_payment` `issue_credit_note` `send_invoice` `send_payment_reminder`
Quotations5 tools	Draft and send quotations, and turn an accepted one into an invoice.	`record_quotation` `list_quotations` `get_quotation` `send_quotation` `convert_quotation`
Purchases6 tools	Record and pay supplier bills, raise debit notes, and attach the supplier's PDF.	`record_bill` `get_bill` `list_bills` `pay_bills` `record_debit_note` `attach_source_document`
Corrections2 tools	Amend or void a document nothing has happened to yet.	`amend_document` `void_document`
Banking1 tool	Move money between the company's own bank and cash accounts.	`transfer_funds`
Journals9 tools	Post, reverse and read journals, or stage drafts for approval.	`post_journal` `reverse_journal` `get_journal` `list_journals` `draft_journal` `list_journal_drafts` `amend_journal_draft` `approve_journal_draft` `reject_journal_draft`
Reports6 tools	Trial balance, profit and loss, balance sheet, general ledger, and aged receivables and payables.	`trial_balance` `profit_and_loss` `balance_sheet` `general_ledger` `aged_receivables` `aged_payables`
Files2 tools	Fetch the PDF of an invoice, credit or cash sale, receipt, credit note or quotation, or the source document filed against a bill, journal or journal draft. Or the same PDF or Excel file the LUCA app downloads for a report: profit and loss, balance sheet, trial balance, account transactions, aged receivables and payables.	`document_pdf` `report_file`

Resources

luca://documents/{type}/{id} — the file behind a document. document_pdf gives the exact link.
luca://report-files/{id} — the PDF or Excel file behind a report. report_file gives the exact link; read it again if the file was still being prepared.
luca://knowledge/… — accounting notes the agent reads before an unfamiliar posting. The first covers customer deposits and advance payments.

When a call is refused

You see	Why	What to do
`401`	The sign-in or token is missing, expired or revoked.	Reconnect the app. With a token, check the header, or create a new token if it expired.
`403` with `pro_required`	The company is not on LUCA Pro.	Upgrade the company, or connect a company that is on Pro.
`403` mentioning a browser extension	The token was made for the browser extension.	Create a token under Settings → API Tokens instead.
Tools act on the wrong company	The app was connected, or the token created, with another company picked.	Reconnect the app and pick the right company, or create a token with the right company selected.
A tool you expect is missing	The person who connected does not have that permission.	Grant the permission, or connect as someone who has it.
`429`	More than 60 requests in a minute.	Wait a minute, then retry.

When LUCA refuses a posting, its message is the answer. The agent should repeat it to you rather than work around it, and it should never move a document to another date to get it through.

Next steps

Every tool goes through the same External API v1, with the same validation and permissions. Browse the API reference for the rules behind each one, or start with invoice automation.