Finix MCP Server

Instructions

Implementation Reference

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

  The main handler function that implements the list_sellers tool. It queries the Finix identities endpoint with optional limit and email filters, filters the results for sellers (identity_roles includes 'SELLER'), and returns an array of seller IDs.

  const listSellers = 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 sellers: ${response.error.message}`);
      }
      
      const data = response.data;
      const identities = data._embedded?.identities || [];
      
      // Filter for sellers only and return just IDs like Stripe
      const sellers = identities
        .filter((identity: any) => identity.identity_roles?.includes('SELLER'))
        .map((seller: any) => ({ id: seller.id }));
      
      return sellers;
  
    } catch (error) {
      throw error;
    }
  };

• src/tools/identities/listSellers.ts:13-20 (schema)

  Zod schema defining the input parameters for the list_sellers tool: optional limit (1-100) and email filter.

  const listSellersParameters = () => 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 seller\'s email field. The value must be a string.'
    )
  });

• src/tools/identities/listSellers.ts:65-79 (registration)

  Tool factory registration defining the 'list_sellers' method, its name, description, parameters, annotations, permissions, and linking to the execute handler. Exported for use in the tools index.

  const tool: ToolFactory = () => ({
    method: 'list_sellers',
    name: 'List Sellers',
    description: listSellersPrompt(),
    parameters: listSellersParameters(),
    annotations: listSellersAnnotations(),
    actions: {
      identities: {
        read: true
      }
    },
    execute: listSellers
  });
  
  export default tool;

• src/tools/identities/listSellers.ts:5-11 (helper)

  Prompt providing the natural language description of the list_sellers tool, used in the tool's description field.

  const listSellersPrompt = () => `
  This tool will fetch a list of Sellers from Finix.
  
  It takes two arguments:
  - limit (int, optional): The number of sellers to return.
  - email (str, optional): A case-sensitive filter on the list based on the seller's email field.
  `;

• src/tools/identities/listSellers.ts:22-28 (helper)

  Annotations providing metadata hints for the list_sellers tool such as idempotent, read-only, etc.

  const listSellersAnnotations = () => ({
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: true,
    readOnlyHint: true,
    title: 'List sellers'
  });