Mercury Invoicing Mcp

List all deposit bank accounts in your Mercury workspace (checking, savings, treasury). USE WHEN: enumerating Mercury bank accounts before drilling into transactions, balances, or statements. Typically the first call when you have an account ID in hand or need one. DO NOT USE: for IO Credit card accounts (use `mercury_list_credit_accounts` — `/credit` is a separate endpoint). For a single account whose ID is already known, prefer `mercury_get_account` to skip the list payload. RETURNS: `{ accounts: [{ id, name, kind, status, availableBalance, currentBalance, accountNumber, routingNumber, ... }] }`.

Retrieve details for a specific Mercury deposit account by ID. USE WHEN: fetching the full detail of a single account whose ID is already known (typically from `mercury_list_accounts`). Faster than re-listing when you already have the ID. DO NOT USE: to enumerate accounts (use `mercury_list_accounts`). For IO Credit accounts (use the `mercury_list_credit_accounts` endpoint). RETURNS: `{ id, name, kind, status, availableBalance, currentBalance, accountNumber, routingNumber, ... }`.

List physical and virtual cards attached to a Mercury account. USE WHEN: enumerating cards (debit, virtual debit, IO Credit) issued against an account — for spend audits, freezing review, or cardholder lookups. DO NOT USE: to list IO Credit transactions (use `mercury_list_credit_transactions`). Card creation, freezing, and PIN ops are not exposed by this MCP — the Mercury API does not currently support them. RETURNS: `{ cards: [{ id, last4, type, status, holderName, expiry, ... }] }`.

List Mercury IO Credit card accounts (charge cards, distinct from deposit accounts). USE WHEN: enumerating IO Credit accounts to find their balance, statement closing date, or to feed an ID into `mercury_list_credit_transactions`. Wraps `GET /credit` (documented under Credit › List all credit accounts in the Mercury API reference). DO NOT USE: for deposit accounts (checking/savings/treasury) — use `mercury_list_accounts`, which hits a different endpoint (`/accounts`). RETURNS: `{ accounts: [{ id, status, availableBalance, currentBalance, ... }] }`.

List transactions on a Mercury IO Credit card account, including pending (not-yet-settled) card authorisations. USE WHEN: auditing IO Credit card spend, reconciling a statement, or building a card-level transaction view. Wraps `GET /account/{id}/transactions` — same path Mercury exposes for deposit-account transactions; both this tool and `mercury_list_transactions` hit it. Supports the same filters. DO NOT USE: for deposit-account transactions (use `mercury_list_transactions`). For posted transactions only, filter by `status: "sent"`. RETURNS: `{ transactions: [{ id, amount, status, postedAt, counterpartyName, ... }] }`. `pending` items are card authorisations that may still be reversed.

List transactions for a Mercury deposit account, with optional filters (date range, status, search). USE WHEN: auditing deposit-account activity, reconciling a statement, or building a per-account ledger view. Filters server-side: `status`, `start`, `end`, `search`, `limit`, `offset`. DO NOT USE: for IO Credit transactions (use `mercury_list_credit_transactions`, which targets the IO Credit account surface). For Treasury, use `mercury_list_treasury_transactions`. RETURNS: `{ transactions: [{ id, amount, status, postedAt, counterpartyName, ... }] }`.

Retrieve a specific transaction by ID for a Mercury deposit account. USE WHEN: fetching the full detail of one transaction whose ID is already known (typically from `mercury_list_transactions`). Faster than relisting + filtering. DO NOT USE: to enumerate transactions (use `mercury_list_transactions`). For IO Credit transactions, use `mercury_list_credit_transactions` and filter by id client-side. RETURNS: `{ id, amount, status, postedAt, counterpartyName, memo, ... }`.

Send money from a Mercury account to an external recipient via ACH, wire, or check. **REAL FUNDS LEAVE YOUR ACCOUNT.** USE WHEN: paying a vendor / contractor / counterparty whose `recipientId` already exists. ALWAYS confirm amount, recipient name, and payment method with the user before calling — the action is high-impact and largely irreversible (wires especially). DO NOT USE: to move money between your own Mercury accounts (use `mercury_create_internal_transfer`). To submit a payment that ALWAYS requires human approval regardless of workspace policy, use `mercury_request_send_money` instead. SIDE EFFECTS: **moves real money out of the account**. Whether the payment executes immediately or queues for approval depends entirely on **your Mercury workspace's approval policy** (Settings → Approvals on app.mercury.com) — the MCP cannot enforce this; Mercury does. On a $0-threshold workspace every send waits for sign-off; on a permissive workspace small payments may settle without re-prompting. Wires are usually irreversible once executed. **Idempotent via `idempotencyKey`** — auto-generated if not passed; pass an explicit one to make retries safe. Audit log entry on Mercury. RETURNS: `{ id, status, amount, ... }`. `status` reflects either immediate execution or pending-approval state, depending on workspace policy.

Update a transaction's internal note or category (no money movement). USE WHEN: tagging a transaction with a category for bookkeeping, or attaching an internal memo. Send `null` to clear a field, omit the key to keep the current value. DO NOT USE: to change the amount, counterparty, or status — those are immutable post-execution. Mercury endpoint is `PATCH /transaction/{id}` (no `accountId` in the path). SIDE EFFECTS: overwrites the note / category on Mercury's side. Persistent. Audit log on Mercury records the change. No effect on the booked transaction itself or on the counterparty. RETURNS: `{ id, note, categoryId, ... }` — the updated transaction.

Move money between two of your own Mercury accounts (e.g. Checking → Savings). Funds stay inside your organisation. USE WHEN: rebalancing cash between your own Mercury accounts — sweeping idle deposits to Treasury, funding a sub-account before issuing cards, etc. Both accounts must belong to your workspace. DO NOT USE: to send money to an external counterparty (use `mercury_send_money`). To request approval-gated movement, use `mercury_request_send_money` (different surface, external only). SIDE EFFECTS: **moves real money** between two accounts you own. Settles immediately, no approval workflow because no external recipient is involved. Persistent ledger entries on both sides. **Idempotent via `idempotencyKey`** — auto-generated if omitted, but pass an explicit one to make retries safe. RETURNS: `{ id, amount, status, ... }` — the booked transfer.

Request to send money — Mercury creates a **pending approval request** that a human must approve before any funds move. ALWAYS creates an approval request, regardless of workspace policy. USE WHEN: submitting an outbound payment that should always wait for human sign-off — for safety, audit, or because workspace policy demands it. Pairs naturally with the "submit, then wait for approver" workflow. DO NOT USE: when you intend to transfer between your own accounts (use `mercury_create_internal_transfer` — no external recipient). For payments that may execute immediately under workspace policy, use `mercury_send_money` (different surface). SIDE EFFECTS: creates a **pending approval request** on Mercury — no money has moved at this point. A human approver must sign off in the Mercury web/mobile app. Once approved, Mercury executes the underlying ACH / wire / check. **Idempotent via `idempotencyKey`** — auto-generated if not passed; pass an explicit one to make retries safe. Audit log entry on Mercury for the request itself. RETURNS: `{ id, status: "pendingApproval", amount, ... }` — track via `mercury_get_transaction` once executed.

List all payment recipients (counterparties for outbound ACH/wire/check) in your Mercury workspace. USE WHEN: enumerating recipients before sending money — need a `recipientId` to feed into `mercury_send_money` or `mercury_request_send_money`. Also useful for an audit of who can receive funds from this account. DO NOT USE: for AR customers (use `mercury_list_customers` — different surface, different scope). Recipients are bank-payment counterparties; customers are who you invoice. RETURNS: `{ recipients: [{ id, name, nickname, defaultPaymentMethod, electronicRoutingInfo, status, ... }] }`.

Update an existing payment recipient (legal name, nickname, contact emails, default payment method). USE WHEN: amending a recipient's contact info or default payment method after creation. Useful for re-routing future payments to a recipient via a different method (e.g. ACH → wire) without recreating it. DO NOT USE: to change the bank account number / routing number — that requires a fresh recipient (security policy on Mercury's side). Use `mercury_add_recipient` for the new banking info. SIDE EFFECTS: writes the recipient record on Mercury. Persistent. Only the fields you pass are changed. Mercury endpoint is `POST /recipient/{id}` (SINGULAR — not the plural `/recipients/{id}`). RETURNS: `{ id, name, nickname, defaultPaymentMethod, ... }` — the updated recipient.

Add a new payment recipient (a counterparty you can later send money to via ACH/wire/check). USE WHEN: onboarding a new vendor, contractor, or other payee before sending money. The returned `id` is what `mercury_send_money` and `mercury_request_send_money` expect as `recipientId`. DO NOT USE: for AR customers (use `mercury_create_customer` — recipients receive money, customers pay invoices). Mercury enforces strict KYC/banking validation on bank fields — invalid routing numbers or account numbers are rejected at create time. SIDE EFFECTS: writes a new recipient to Mercury. Persistent. **Idempotent via `idempotencyKey`** — the MCP auto-generates one if not provided, so repeated calls with the same generated key would not duplicate; pass an explicit `idempotencyKey` to make this stable across retries you control. RETURNS: `{ id, name, status, defaultPaymentMethod, ... }` — keep `id` for the send-money tools.

List monthly statements for a Mercury deposit account. Each statement has a downloadable PDF URL. USE WHEN: fetching the URL of a past statement (e.g. for accounting export, audit, or sharing with a CPA). The PDF URL is short-lived — re-fetch it shortly before download. DO NOT USE: for IO Credit account statements (Mercury exposes them only via the dashboard, not the API). For Treasury statements use `mercury_list_treasury_statements`. RETURNS: `{ statements: [{ id, periodStart, periodEnd, downloadUrl, ... }] }`.

Retrieve Mercury Treasury account information (balance, current yield, eligibility, etc.). USE WHEN: checking treasury cash balance or yield for cash-management decisions, or to confirm the workspace has Treasury enabled. DO NOT USE: for deposit accounts (use `mercury_get_account`). For Treasury transactions or statements, use the dedicated list tools. RETURNS: `{ id, currentBalance, yield, eligibility, ... }`.

List transactions for a Mercury Treasury account (sweeps, dividend accruals, etc.). USE WHEN: auditing Treasury cash flows, reconciling yield accruals, or building a Treasury-only ledger view. DO NOT USE: for deposit-account transactions (use `mercury_list_transactions`). For IO Credit transactions, use `mercury_list_credit_transactions`. RETURNS: `{ transactions: [{ id, amount, kind, postedAt, ... }] }`.

List monthly statements for a Mercury Treasury account. USE WHEN: fetching the URL of a past Treasury statement for tax/audit export. PDF URL is short-lived — fetch it shortly before download. DO NOT USE: for deposit-account statements (use `mercury_list_statements`). IO Credit statements are not exposed via the API. RETURNS: `{ statements: [{ id, periodStart, periodEnd, downloadUrl, ... }] }`.

List transaction categories available in your Mercury workspace (e.g. Office Supplies, Meals, Travel). USE WHEN: discovering valid `categoryId` values before calling `mercury_update_transaction` to recategorise a transaction. Also useful for category-based reporting in downstream tooling. DO NOT USE: to list transactions in a category (use `mercury_list_transactions` and filter client-side). Category creation/edit is not exposed by this MCP — the Mercury API does not currently support it. RETURNS: `{ categories: [{ id, name, ... }] }`.

Retrieve information about your Mercury organization (legal name, EIN, registered address, etc.). USE WHEN: fetching the workspace's legal identity for invoice generation, tax documents, or to confirm which organization the API token is bound to. DO NOT USE: for per-account info (use `mercury_get_account`). The Mercury API exposes only one organization per token, so there is no list variant. RETURNS: `{ id, legalName, ein, address, ... }`.

List invoices in your Mercury workspace, with cursor-based pagination. USE WHEN: enumerating invoices for an AR audit, finding the ID of an invoice to update/cancel, or building a dunning report. Use `startAfter` / `endBefore` to page beyond the limit. DO NOT USE: for one invoice whose ID is known (prefer `mercury_get_invoice`). Mercury does not currently support filtering by status or customer at the API level — filter client-side after listing. RETURNS: `{ invoices: [{ id, status, amount, customerId, dueDate, ... }] }`.

Retrieve a specific invoice by ID, including line items, status, and the payment URL. USE WHEN: fetching the full detail of one invoice (line items, current status, balance due, payment URL) whose ID is already known. DO NOT USE: to enumerate invoices (use `mercury_list_invoices`). For attachments use `mercury_list_invoice_attachments`. RETURNS: `{ id, status, amount, customerId, lineItems, paymentUrl, dueDate, ... }`.

Create a new invoice (one-shot or to be sent recurrently). Requires AR write scope. USE WHEN: billing a customer that already exists in Mercury (`customerId` from `mercury_create_customer` or `mercury_list_customers`). Set `sendEmailOption: "SendNow"` to email the invoice immediately to the customer's contact email. DO NOT USE: when the customer does not exist yet (call `mercury_create_customer` first). To attach a file to the invoice, use the Mercury web app at creation time — the API attachment-upload endpoint is not exposed by this MCP currently. SIDE EFFECTS: writes a new invoice to Mercury. Persistent. With `sendEmailOption: "SendNow"` (the default), Mercury also sends a real email with a payment link to the customer — confirm the customer's email and the line items before calling. Mercury Plus tier required for the AR write scope. RETURNS: `{ id, status, amount, paymentUrl, ... }` — `paymentUrl` is the Mercury-hosted page where the customer pays.

Update an existing invoice. Pass only the fields you want to change. USE WHEN: amending an outstanding invoice (line items, due date, memo, PO number) before the customer pays. The MCP fetches the current invoice and merges your changes before submitting — Mercury's update endpoint requires the full payload despite the API docs implying PATCH. DO NOT USE: to cancel an invoice (use `mercury_cancel_invoice`). To change the customer or the destination account, cancel + recreate. Once an invoice is paid, updates are likely rejected by Mercury — fetch first to confirm status. SIDE EFFECTS: overwrites the invoice on Mercury's side. The customer-facing payment URL stays the same. If the invoice was already emailed, the customer is NOT re-notified of the change — communicate the change out-of-band if needed. RETURNS: `{ id, status, amount, ... }` — the updated invoice.

Cancel an outstanding invoice. **Mercury sends a cancellation notice to the customer if the invoice was already emailed.** USE WHEN: voiding an invoice that was issued in error, that the customer disputes, or that needs to be re-issued under a corrected line-item set. ALWAYS confirm with the user before calling — the customer-facing notification is automatic. DO NOT USE: on an invoice already paid (Mercury rejects cancellation). To refund a paid invoice, refund out-of-band via the bank, then optionally update the internal note. SIDE EFFECTS: marks the invoice as `cancelled` on Mercury. The customer-facing payment URL stops accepting payments. If the invoice was emailed, **Mercury notifies the customer of the cancellation by email** — confirm with the user before calling. The action is logged in Mercury's audit trail. Cancellation is final from the API perspective. RETURNS: `{ id, status: "cancelled", ... }`.

List attachments associated with an invoice (PDF copies, supporting documents). USE WHEN: discovering which files were attached to an invoice — for archival, audit, or to share with a customer. The download URL is short-lived; refetch shortly before download. DO NOT USE: to upload an attachment — this MCP currently exposes only the read side. Mercury's API does support attachment upload (`POST /ar/invoices/{id}/attachments`); a write tool can be added if needed. RETURNS: `{ attachments: [{ id, filename, downloadUrl, ... }] }`.

Resolve the download URL of an invoice's PDF via Mercury's documented `getinvoicepdf` endpoint. USE WHEN: you need the actual invoice PDF — to archive it, or to attach it to an email / bank KYB / compliance reply. `mercury_list_invoice_attachments` does NOT return it (that lists only files a human manually uploaded, empty on a normal invoice). This tool fetches the invoice (for its number / status / slug) and returns `downloadUrl` = `{baseUrl}/ar/invoices/{id}/pdf`, the documented endpoint (https://docs.mercury.com/reference/getinvoicepdf) that returns the PDF with `Content-Disposition: attachment`. AUTH: `downloadUrl` is an **authenticated** Mercury API URL — fetch it with the same `Authorization: Bearer <token>` and `Accept: application/pdf` as every other call (it is NOT a public pre-signed link). Because it is derived from the client's configured base URL, it stays correct under the sandbox / proxy host, not just production. DO NOT USE: for statement PDFs (use `mercury_list_statements`); for manually-uploaded attachments (use `mercury_list_invoice_attachments`). A draft invoice that was never issued may return `404` when the URL is fetched. RETURNS: `{ invoiceId, invoiceNumber, status, slug, downloadUrl }`.

List Accounts Receivable customers, with cursor-based pagination. USE WHEN: enumerating AR customers before creating an invoice (need a `customerId` for `mercury_create_invoice`), or for a customer-level audit. Use `startAfter` / `endBefore` for paging beyond the limit. DO NOT USE: for payment recipients (`mercury_list_recipients` is the bank-payment counterparty list, distinct from AR customers). For one customer whose ID is known, prefer `mercury_get_customer`. RETURNS: `{ customers: [{ id, name, email, address, ... }] }`.

Retrieve a specific Accounts Receivable customer by ID. USE WHEN: fetching the full detail of one customer whose ID is already known. Faster than relisting + filtering when you have the ID. DO NOT USE: to enumerate customers (use `mercury_list_customers`). For payment recipients use `mercury_list_recipients` (different surface). RETURNS: `{ id, name, email, address, ... }`.

Create a new Accounts Receivable customer (a billable entity you will later invoice). USE WHEN: onboarding a new customer before issuing them an invoice. The returned `id` is what `mercury_create_invoice` expects as `customerId`. DO NOT USE: for payment recipients (use `mercury_add_recipient` — different surface, used for outbound bank transfers, not invoicing). SIDE EFFECTS: writes a new customer to your Mercury workspace. Persistent. NOT idempotent at the API level — calling twice with the same payload creates two customers; check `mercury_list_customers` for existing entries before creating to avoid duplicates. RETURNS: `{ id, name, email, address, ... }` — keep `id` for the invoicing tools.

Update an existing Accounts Receivable customer. Pass only the fields you want to change. USE WHEN: amending a customer's contact details (name, email, billing address) after creation. Existing invoices are not retroactively modified. DO NOT USE: to delete a customer (use `mercury_delete_customer`). To change the customer of an existing invoice, cancel + recreate the invoice. SIDE EFFECTS: writes the new customer record to Mercury. Persistent. Only the fields you pass are changed — omitted fields keep their current value. RETURNS: `{ id, name, email, address, ... }` — the updated customer.

Permanently delete an Accounts Receivable customer. **DESTRUCTIVE.** USE WHEN: removing a customer that was created by mistake, or that the user explicitly wants to purge. ALWAYS confirm with the user before calling — there is no undo. DO NOT USE: when the customer has invoices in `paid` / `outstanding` status — Mercury rejects deletion in those cases and returns a 409. Cancel outstanding invoices first via `mercury_cancel_invoice`. SIDE EFFECTS: **permanent deletion** on Mercury's side. The customer disappears from the AR list. Past invoices' `customerId` may dangle (Mercury does not cascade-delete invoices). NOT recoverable from API. ALWAYS confirm with the user. RETURNS: confirmation payload from Mercury (`{ deleted: true, ... }` or similar).

List all webhook endpoints configured for your Mercury workspace. USE WHEN: enumerating registered webhook endpoints — for audit, finding a webhook ID before update/delete, or to confirm a delivery target is registered. DO NOT USE: to inspect webhook delivery history (Mercury exposes that only via the dashboard, not the API). RETURNS: `{ webhooks: [{ id, url, status, events, ... }] }`.

Retrieve a specific webhook endpoint by ID. USE WHEN: fetching the full detail of one webhook (URL, current status, subscribed events) whose ID is already known. DO NOT USE: to enumerate webhooks (use `mercury_list_webhooks`). RETURNS: `{ id, url, status, events, ... }`.

Register a new webhook endpoint. Mercury will POST events as JSON to the provided URL. USE WHEN: subscribing an external system to Mercury events (transaction.posted, invoice.paid, etc.) so you can react in near real-time without polling. DO NOT USE: with non-HTTPS URLs, loopback / RFC 1918 / link-local / cloud-metadata IPs — the MCP enforces a defense-in-depth gate on top of Mercury's own validation to block accidental SSRF or exfiltration via prompt injection. SIDE EFFECTS: writes a new webhook subscription to Mercury. Persistent. Once registered, Mercury immediately starts delivering matching events to your URL — make sure the endpoint is ready to receive (and ideally verify Mercury's signature). NOT idempotent at the API level — calling twice creates two subscriptions firing duplicate events. RETURNS: `{ id, url, status, events, ... }` — keep `id` for `mercury_update_webhook` / `mercury_delete_webhook`.

Update an existing webhook endpoint (URL, status, or subscribed events). USE WHEN: rotating a webhook's destination URL, changing the event subscription, or reactivating a webhook Mercury auto-disabled after consecutive delivery failures (set `status: "active"`). DO NOT USE: to inspect delivery history. Same SSRF / non-HTTPS URL guard as `mercury_create_webhook` applies to the new URL. SIDE EFFECTS: overwrites the webhook record. Persistent. If `status` flips to `active`, Mercury resumes delivery on the next matching event. The new URL takes effect immediately for future events. RETURNS: `{ id, url, status, events, ... }` — the updated webhook.

Delete a webhook endpoint. **DESTRUCTIVE — Mercury stops delivering events to that URL.** USE WHEN: decommissioning a webhook (URL no longer reachable, integration retired, accidental duplicate). ALWAYS confirm with the user — there is no undo, and any downstream system that depended on the events stops being notified. DO NOT USE: to temporarily silence a webhook (use `mercury_update_webhook` with `status: "paused"` instead — reversible). SIDE EFFECTS: **permanent deletion** on Mercury's side. Future events that would have fired this webhook are silently dropped — no replay. Past delivery history is also lost from the Mercury dashboard. RETURNS: confirmation payload (`{ deleted: true, ... }` or similar).