Skip to main content
Glama
klodr

mercury-invoicing-mcp

by klodr
OverviewSchemaSourceRelated ServersDiscussions(1)Admin
TypeScript
Remote

mercury_create_invoice

Create a new invoice (one-shot or to be sent recurrently). Requires AR write scope.

Instructions

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.

Input Schema

NameRequiredDescriptionDefault
dueDateYesDue date (YYYY-MM-DD)
ccEmailsNoCC emails for notifications
poNumberNoPurchase order number
lineItemsYesInvoice line items
payerMemoNoMemo shown to payer
customerIdYesCustomer ID (created via mercury_create_customer)
invoiceDateYesInvoice date (YYYY-MM-DD)
internalNoteNoNote visible only to your org
invoiceNumberNoCustomer-facing invoice number (≤255 chars; Mercury rejects 300+ characters on the edit endpoint)
achDebitEnabledNoAllow ACH debit payments. Default: true
sendEmailOptionNoWhether to email the invoice immediately. Default: SendNow
creditCardEnabledNoAllow credit card payments. Default: true
destinationAccountIdYesMercury account ID where invoice payments will be deposited
servicePeriodEndDateNoService period end (YYYY-MM-DD)
useRealAccountNumberNoShow real (vs virtual) account number on the invoice. Default: false
servicePeriodStartDateNoService period start (YYYY-MM-DD)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.20.3
    • changedInput schema / properties / ccEmails / items / pattern
      Previous value: -"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"New value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
  2. Addedv0.15.6
  3. Removedv0.15.5
  4. Addedv0.15.4
  5. Removedv0.15.2
  6. Changed1 schema field changedv0.12.0
    • addedInput schema / additionalProperties
      Added value: +false
  7. First observedv0.9.1

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (openWorldHint, destructiveHint=false): it warns that the write is persistent, that the default SendNow option sends a real email with a payment link (a real-world side effect), and that Mercury Plus / AR write scope is required. It also discloses the API attachment limitation, which annotations do not cover at all.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Sectioned with front-loaded labels (USE WHEN / DO NOT USE / SIDE EFFECTS / RETURNS) and every sentence carries actionable information. No filler despite the length, which is justified by a 16-parameter, email-sending mutation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description provides the return shape (id, status, amount, paymentUrl) and explains paymentUrl. Combined with prerequisites, tier requirement and side effects, an agent has everything needed to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: sendEmailOption controls whether a real customer email is sent, and customerId provenance is tied to mercury_create_customer. It doesn't explain destinationAccountId or the other optional fields beyond schema, so not a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create a new invoice') and scopes it ('one-shot or to be sent recurrently'), immediately distinguishing it from mercury_update_invoice, mercury_send_money and the customer tools it references. An agent can identify the tool's role without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit USE WHEN and DO NOT USE blocks name the prerequisite (customer must exist, via mercury_create_customer or mercury_list_customers) and route the agent to mercury_create_customer when it does not. It also calls out the attachment workaround, which prevents a failed call attempt.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools