Mercury Invoicing Mcp

- 34 tools across Banking (accounts, transactions, recipients, statements), Treasury, Invoicing (AR), Customers (AR), and Webhooks.
- Internal transfers between your own Mercury accounts.
- Recurring invoices + invoice attachments.
- Webhooks full CRUD (incl. update_webhook).
- Built-in safeguards: dual-window rate limit (daily + monthly), dry-run mode, redacted audit log.
- Sandbox auto-detect — tokens starting with mercury_sandbox_ automatically point at api-sandbox.mercury.com.

- mercury_list_accounts: 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, ... }] }.
- mercury_get_account: 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, ... }.
- mercury_list_cards: 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, ... }] }.
- mercury_list_credit_accounts: 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, ... }] }.
- mercury_list_credit_transactions: 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.
- mercury_list_transactions: 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, ... }] }.
- mercury_get_transaction: 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, ... }.
- mercury_send_money: 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.
- mercury_update_transaction: 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.
- mercury_create_internal_transfer: 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.
- mercury_request_send_money: 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.
- mercury_list_recipients: 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, ... }] }.
- mercury_update_recipient: 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.
- mercury_add_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.
- mercury_list_statements: 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, ... }] }.
- mercury_get_treasury: 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, ... }.
- mercury_list_treasury_transactions: 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, ... }] }.
- mercury_list_treasury_statements: 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, ... }] }.
- mercury_list_categories: 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, ... }] }.
- mercury_get_organization: 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, ... }.
- mercury_list_invoices: 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, ... }] }.
- mercury_get_invoice: 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, ... }.
- mercury_create_invoice: 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.
- mercury_update_invoice: 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.
- mercury_cancel_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", ... }.
- mercury_list_invoice_attachments: 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, ... }] }.
- mercury_get_invoice_pdf: 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 }.
- mercury_list_customers: 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, ... }] }.
- mercury_get_customer: 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, ... }.
- mercury_create_customer: 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.
- mercury_update_customer: 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.
- mercury_delete_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).
- mercury_list_webhooks: 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, ... }] }.
- mercury_get_webhook: 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, ... }.
- mercury_create_webhook: 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.
- mercury_update_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.
- mercury_delete_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).