Finix MCP Server

Instructions

Implementation Reference

• src/tools/payment-links/createPaymentLink.ts:28-66 (handler)

  The main handler function that executes the tool's core logic: validates credentials, constructs payload from merchant_id, price, quantity, posts to /payment_links endpoint, and returns the link id and url.

  const createPaymentLink = 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 { merchant_id, price, quantity } = params;
  
      const total_price = price * quantity;
  
      const payload = {
        merchant_id,
        payment_frequency: 'ONE_TIME',
        allowed_payment_methods: ['PAYMENT_CARD', 'ACH'],
        nickname: `Payment Link`,
        items: [{
          name: 'Payment',
          quantity,
          unit_price: price,
          total_price
        }]
      };
  
      const response = await client.post('/payment_links', payload);
      
      if (response.error) {
        throw new Error(`Error creating payment link: ${response.error.message}`);
      }
      
      // Return ID and URL so users can actually use the payment link
      return { 
        id: response.data.id, 
        url: response.data.url 
      };
  
    } catch (error) {
      throw error;
    }
  };

• src/tools/payment-links/createPaymentLink.ts:14-18 (schema)

  Zod schema for input parameters: merchant_id (string), price (positive integer in cents), quantity (positive integer).

  const createPaymentLinkParameters = () => z.object({
    merchant_id: z.string().describe('The ID of the merchant the payment link is created under'),
    price: z.number().int().min(1).describe('The unit price in cents'),
    quantity: z.number().int().min(1).describe('The quantity of the product to include in the payment link')
  });

• src/tools/payment-links/createPaymentLink.ts:68-80 (registration)

  Tool factory object defining the tool with method name 'create_payment_link', description, parameters schema, annotations, actions, and linking to the execute handler.

  const tool: ToolFactory = () => ({
    method: 'create_payment_link',
    name: 'Create Payment Link',
    description: createPaymentLinkPrompt(),
    parameters: createPaymentLinkParameters(),
    annotations: createPaymentLinkAnnotations(),
    actions: {
      payment_links: {
        create: true
      }
    },
    execute: createPaymentLink
  });

• src/tools/index.ts:25-27 (registration)

  Inclusion of the createPaymentLink tool in the exported allTools array for global tool registration.

    // Payment Links
    createPaymentLink,
  ];

• src/tools/payment-links/createPaymentLink.ts:5-12 (helper)

  Prompt string providing natural language description of the tool's purpose and parameters.

  const createPaymentLinkPrompt = () => `
  This tool will create a payment link in Finix.
  
  It takes three arguments:
  - merchant_id (str): The ID of the merchant the payment link is created under.
  - price (int): The unit price in cents.
  - quantity (int): The quantity of the product to include in the payment link.
  `;