mercury_get_transaction

Instructions

Implementation Reference

• src/tools/transactions.ts:60-63 (handler)

  The async handler function that executes the tool logic. It calls client.get() with the account ID and transaction ID to retrieve a specific transaction from the Mercury API, then returns the result via textResult().

  async ({ accountId, transactionId }) => {
    const data = await client.get(`/account/${accountId}/transaction/${transactionId}`);
    return textResult(data);
  },

• src/tools/transactions.ts:56-59 (schema)

  Input schema/validation for the tool. Defines two required parameters: accountId (UUID) and transactionId (UUID), both described with Zod validators.

  {
    accountId: z.string().uuid().describe("The Mercury account ID"),
    transactionId: z.string().uuid().describe("The transaction ID"),
  },

• src/tools/transactions.ts:44-64 (registration)

  Registration of the tool via defineTool() — binds the name 'mercury_get_transaction', its description, input schema, and handler to the MCP server.

  defineTool(
    server,
    "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, ... }`.",
    ].join("\n"),
    {
      accountId: z.string().uuid().describe("The Mercury account ID"),
      transactionId: z.string().uuid().describe("The transaction ID"),
    },
    async ({ accountId, transactionId }) => {
      const data = await client.get(`/account/${accountId}/transaction/${transactionId}`);
      return textResult(data);
    },
  );

• src/tools/transactions.ts:7-38 (registration)

  The parent function registerTransactionTools() which registers all transaction tools including mercury_get_transaction on the MCP server.

  export function registerTransactionTools(server: McpServer, client: MercuryClient): void {
    defineTool(
      server,
      "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, ... }] }`.",
      ].join("\n"),
      {
        accountId: z.string().uuid().describe("The Mercury account ID"),
        limit: z
          .number()
          .int()
          .min(1)
          .max(500)
          .optional()
          .describe("Max results to return (1-500). Default: 500"),
        offset: z.number().int().min(0).optional().describe("Pagination offset"),
        status: z
          .enum(["pending", "sent", "cancelled", "failed"])
          .optional()
          .describe("Filter by transaction status"),
        start: z.iso.date().optional().describe("Filter posted on/after this date (YYYY-MM-DD)"),
        end: z.iso.date().optional().describe("Filter posted on/before this date (YYYY-MM-DD)"),
        search: z.string().optional().describe("Search query (counterparty name, memo, etc.)"),
      },
      async ({ accountId, ...query }) => {

• src/tools/_shared.ts:29-39 (helper)

  The defineTool helper function used to register each tool. It wraps the handler with middleware and calls server.registerTool().

  export function defineTool<S extends ZodRawShape>(
    server: McpServer,
    name: string,
    description: string,
    inputSchema: S,
    handler: (args: z.infer<z.ZodObject<S>>) => Promise<ToolResult>,
  ): void {
    const wrapped = wrapToolHandler(name, handler);
    const strictSchema = z.object(inputSchema).strict();
    server.registerTool(name, { description, inputSchema: strictSchema }, wrapped);
  }