Skip to main content
Glama
klodr

mercury-invoicing-mcp

by klodr
OverviewSchemaSourceRelated ServersDiscussions(1)Admin
TypeScript
Remote

mercury_add_recipient

Idempotent

Add a new payment recipient (a counterparty you can later send money to via ACH/wire/check).

Instructions

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.

Input Schema

NameRequiredDescriptionDefault
nameYesRecipient legal name
emailsYesList of email addresses
paymentMethodYesPayment method to send to this recipient
idempotencyKeyNoUnique key to prevent duplicates
defaultPaymentMethodNoDefault payment method
electronicRoutingInfoNoBank account info for ACH/wire

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.20.3
    • changedInput schema / properties / emails / 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.5/5.0
Behavior4/5

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

Goes well beyond the annotations by disclosing a persistent write, server-side KYC/banking validation that rejects bad routing/account numbers at create time, and the retry/idempotency contract. The idempotency sentence is awkwardly worded ('repeated calls with the same generated key would not duplicate'), which could lead an agent to assume auto-generated keys make blind retries safe; that nuance is worth tightening but is not a contradiction of idempotentHint=true.

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

Conciseness4/5

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

Sectioned and front-loaded (definition, USE WHEN, DO NOT USE, SIDE EFFECTS, RETURNS), so an agent can scan to the relevant block. Slightly long, and the idempotency sentence is the one piece of prose that costs more words than it returns in clarity.

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

Completeness4/5

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

Covers the things that matter for a 6-param, nested-object mutation with no output schema: persistence, validation failure modes, the returned id and its downstream use. The remaining gap is the paymentMethod vs defaultPaymentMethod distinction, which the agent must infer from the schema alone.

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 baseline is 3; the description adds real meaning by warning that electronicRoutingInfo bank fields are validated and rejected at create time, and by explaining the purpose of idempotencyKey across retries. It does not, however, clarify the relationship between the required paymentMethod and the optional defaultPaymentMethod, which is the one genuine ambiguity left in the schema.

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 ('Add a new payment recipient') and immediately disambiguates with a parenthetical definition ('a counterparty you can later send money to via ACH/wire/check'). It also explicitly contrasts with the nearest confusing sibling, mercury_create_customer, so an agent can route correctly without opening a 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 (onboarding vendors/contractors before sending money) and explicit DO NOT USE with the named alternative for the AR-customer case. It also names the downstream consumers (mercury_send_money, mercury_request_send_money) and which field they consume, which is exactly the routing information an agent needs.

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