mercury_update_recipient

Instructions

Implementation Reference

• src/tools/recipients.ts:51-54 (handler)

  The async handler function for mercury_update_recipient. It destructures recipientId from args and passes remaining fields as body to POST /recipient/{recipientId}.

  async ({ recipientId, ...body }) => {
    const data = await client.post(`/recipient/${recipientId}`, body);
    return textResult(data);
  },

• src/tools/recipients.ts:41-50 (schema)

  Zod input schema for mercury_update_recipient: requires recipientId (UUID), optional name, nickname, contactEmail (email), emails (array of emails), and defaultPaymentMethod (enum).

  {
    recipientId: z.string().uuid().describe("The recipient ID"),
    name: z.string().optional().describe("Recipient legal name"),
    nickname: z.string().optional().describe("Internal nickname"),
    contactEmail: z.string().email().optional().describe("Primary contact email"),
    emails: z.array(z.string().email()).optional().describe("List of email addresses"),
    defaultPaymentMethod: z
      .enum(["domesticAch", "internationalWire", "domesticWire", "check"])
      .optional(),
  },

• src/tools/recipients.ts:27-55 (registration)

  Registration of the mercury_update_recipient tool via defineTool() on the McpServer, with description, input schema, and handler.

  defineTool(
    server,
    "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.",
    ].join("\n"),
    {
      recipientId: z.string().uuid().describe("The recipient ID"),
      name: z.string().optional().describe("Recipient legal name"),
      nickname: z.string().optional().describe("Internal nickname"),
      contactEmail: z.string().email().optional().describe("Primary contact email"),
      emails: z.array(z.string().email()).optional().describe("List of email addresses"),
      defaultPaymentMethod: z
        .enum(["domesticAch", "internationalWire", "domesticWire", "check"])
        .optional(),
    },
    async ({ recipientId, ...body }) => {
      const data = await client.post(`/recipient/${recipientId}`, body);
      return textResult(data);
    },
  );

• src/tools/index.ts:9-26 (registration)

  Import and call of registerRecipientTools which registers all recipient tools including mercury_update_recipient.

  import { registerRecipientTools } from "./recipients.js";
  import { registerStatementTools } from "./statements.js";
  import { registerTreasuryTools } from "./treasury.js";
  import { registerInvoiceTools } from "./invoices.js";
  import { registerCustomerTools } from "./customers.js";
  import { registerWebhookTools } from "./webhooks.js";
  
  /**
   * Register all Mercury MCP tools on the server.
   * Tools are organized by domain.
   */
  export function registerAllTools(server: McpServer, client: MercuryClient): void {
    // Banking
    registerAccountTools(server, client);
    registerCardTools(server, client);
    registerCreditTools(server, client);
    registerTransactionTools(server, client);
    registerRecipientTools(server, client);

• src/middleware.ts:54-54 (helper)

  Maps mercury_update_recipient to the 'recipients_update' rate-limit bucket, and at line 75 sets default limits of 2/day and 15/month.

  mercury_update_recipient: "recipients_update",