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'
  });