PayPal MCP

Instructions

Implementation Reference

• src/index.ts:1184-1197 (handler)

  Executes the create_payout tool: validates input with validatePayout, posts to PayPal /v1/payments/payouts API, returns JSON response.

  case 'create_payout': {
    const args = this.validatePayout(request.params.arguments);
    const response = await axios.post<PayPalPayout>(
      'https://api-m.sandbox.paypal.com/v1/payments/payouts',
      args,
      { headers }
    );
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(response.data, null, 2)
      }]
    };
  }

• src/index.ts:877-912 (schema)

  Input schema definition for create_payout tool, defining structure for sender_batch_header and items array.

  inputSchema: {
    type: 'object',
    properties: {
      sender_batch_header: {
        type: 'object',
        properties: {
          sender_batch_id: { type: 'string' },
          email_subject: { type: 'string' },
          recipient_type: { type: 'string' }
        },
        required: ['sender_batch_id']
      },
      items: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            recipient_type: { type: 'string' },
            amount: {
              type: 'object',
              properties: {
                value: { type: 'string' },
                currency: { type: 'string' }
              },
              required: ['value', 'currency']
            },
            receiver: { type: 'string' },
            note: { type: 'string' },
            sender_item_id: { type: 'string' }
          },
          required: ['recipient_type', 'amount', 'receiver']
        }
      }
    },
    required: ['sender_batch_header', 'items']
  }

• src/index.ts:874-913 (registration)

  Tool registration in server.setTools array with name, description, and inputSchema.

  {
    name: 'create_payout',
    description: 'Create a batch payout',
    inputSchema: {
      type: 'object',
      properties: {
        sender_batch_header: {
          type: 'object',
          properties: {
            sender_batch_id: { type: 'string' },
            email_subject: { type: 'string' },
            recipient_type: { type: 'string' }
          },
          required: ['sender_batch_id']
        },
        items: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              recipient_type: { type: 'string' },
              amount: {
                type: 'object',
                properties: {
                  value: { type: 'string' },
                  currency: { type: 'string' }
                },
                required: ['value', 'currency']
              },
              receiver: { type: 'string' },
              note: { type: 'string' },
              sender_item_id: { type: 'string' }
            },
            required: ['recipient_type', 'amount', 'receiver']
          }
        }
      },
      required: ['sender_batch_header', 'items']
    }
  },

• src/index.ts:403-460 (helper)

  Helper method to validate and type-check input arguments for create_payout, ensuring required fields and structure match PayPalPayout.

  private validatePayout(args: unknown): PayPalPayout {
    if (typeof args !== 'object' || !args) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid payout data');
    }
  
    const payout = args as Record<string, unknown>;
    
    if (!payout.sender_batch_header || typeof payout.sender_batch_header !== 'object' ||
        !Array.isArray(payout.items) || payout.items.length === 0) {
      throw new McpError(ErrorCode.InvalidParams, 'Missing required payout fields');
    }
  
    const header = payout.sender_batch_header as Record<string, unknown>;
    if (typeof header.sender_batch_id !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid sender batch ID');
    }
  
    const items = payout.items.map(item => {
      const payoutItem = item as Record<string, unknown>;
      if (typeof payoutItem.recipient_type !== 'string' ||
          !payoutItem.amount || typeof payoutItem.amount !== 'object' ||
          typeof payoutItem.receiver !== 'string') {
        throw new McpError(ErrorCode.InvalidParams, 'Invalid payout item');
      }
  
      const amount = payoutItem.amount as Record<string, unknown>;
      if (typeof amount.value !== 'string' || typeof amount.currency !== 'string') {
        throw new McpError(ErrorCode.InvalidParams, 'Invalid amount fields');
      }
  
      const validatedItem: PayPalPayout['items'][0] = {
        recipient_type: payoutItem.recipient_type,
        amount: {
          value: amount.value,
          currency: amount.currency
        },
        receiver: payoutItem.receiver
      };
  
      if (typeof payoutItem.note === 'string') {
        validatedItem.note = payoutItem.note;
      }
      if (typeof payoutItem.sender_item_id === 'string') {
        validatedItem.sender_item_id = payoutItem.sender_item_id;
      }
  
      return validatedItem;
    });
  
    return {
      sender_batch_header: {
        sender_batch_id: header.sender_batch_id,
        email_subject: typeof header.email_subject === 'string' ? header.email_subject : undefined,
        recipient_type: typeof header.recipient_type === 'string' ? header.recipient_type : undefined
      },
      items
    };
  }