Finix MCP Server

Instructions

Implementation Reference

• src/tools/identities/listBuyers.ts:30-63 (handler)

  The main handler function that executes the tool logic: fetches identities from Finix API using provided limit and email filters, filters for buyers (those with identity_roles including 'BUYER'), and returns an array of buyer IDs.
  const listBuyers = async (client: FinixClient, _context: FinixContext, params: any): Promise<any> => { try { if (!client.hasCredentials()) { throw new Error('Finix username and password are required for this operation. Please configure FINIX_USERNAME and FINIX_PASSWORD in your environment.'); } const { limit, email } = params; // Build query parameters const queryParams = new URLSearchParams(); if (limit) queryParams.append('limit', limit.toString()); if (email) queryParams.append('email', email); const response = await client.get(`/identities?${queryParams.toString()}`); if (response.error) { throw new Error(`Error listing buyers: ${response.error.message}`); } const data = response.data; const identities = data._embedded?.identities || []; // Filter for buyers only and return just IDs like Stripe const buyers = identities .filter((identity: any) => identity.identity_roles?.includes('BUYER')) .map((buyer: any) => ({ id: buyer.id })); return buyers; } catch (error) { throw error; } };
• src/tools/identities/listBuyers.ts:13-20 (schema)

  Zod input schema defining optional parameters: limit (integer 1-100) and email (string filter).
  const listBuyersParameters = () => z.object({ limit: z.number().int().min(1).max(100).optional().describe( 'A limit on the number of objects to be returned. Limit can range between 1 and 100.' ), email: z.string().optional().describe( 'A case-sensitive filter on the list based on the buyer\'s email field. The value must be a string.' ) });
• src/tools/identities/listBuyers.ts:65-79 (registration)

  ToolFactory registration defining the 'list_buyers' tool, including method name, name, description, parameters, annotations, actions, and reference to the execute handler. Exported as default.
  const tool: ToolFactory = () => ({ method: 'list_buyers', name: 'List Buyers', description: listBuyersPrompt(), parameters: listBuyersParameters(), annotations: listBuyersAnnotations(), actions: { identities: { read: true } }, execute: listBuyers }); export default tool;
• src/tools/index.ts:15-27 (registration)

  Central registration of all tools in the allTools array, including the listBuyers tool.
  export const allTools: ToolFactory[] = [ // Search & Documentation searchDocs, // Identities (Buyers/Sellers) createBuyer, createSeller, listBuyers, listSellers, // Payment Links createPaymentLink, ];
• src/tools/identities/listBuyers.ts:5-11 (schema)

  Prompt/description generator for the list_buyers tool.
  const listBuyersPrompt = () => ` This tool will fetch a list of Buyers from Finix. It takes two arguments: - limit (int, optional): The number of buyers to return. - email (str, optional): A case-sensitive filter on the list based on the buyer's email field. `;
• src/tools/identities/listBuyers.ts:22-28 (schema)

  Annotations for the list_buyers tool indicating it is read-only, idempotent, etc.
  const listBuyersAnnotations = () => ({ destructiveHint: false, idempotentHint: true, openWorldHint: true, readOnlyHint: true, title: 'List buyers' });