PayPal MCP

Instructions

Implementation Reference

• src/index.ts:1169-1182 (handler)

  The core handler logic for the 'create_payment' tool. It validates the input arguments, makes a POST request to the PayPal v2/payments/payment endpoint using axios, and returns the API response as formatted JSON text.

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

• src/index.ts:819-873 (registration)

  Tool registration in the ListTools response, defining name, description, and detailed JSON input schema for parameter validation.

    name: 'create_payment',
    description: 'Create a payment',
    inputSchema: {
      type: 'object',
      properties: {
        intent: { type: 'string' },
        payer: {
          type: 'object',
          properties: {
            payment_method: { type: 'string' },
            funding_instruments: {
              type: 'array',
              items: {
                type: 'object',
                properties: {
                  credit_card: {
                    type: 'object',
                    properties: {
                      number: { type: 'string' },
                      type: { type: 'string' },
                      expire_month: { type: 'number' },
                      expire_year: { type: 'number' },
                      cvv2: { type: 'string' },
                      first_name: { type: 'string' },
                      last_name: { type: 'string' }
                    }
                  }
                }
              }
            }
          },
          required: ['payment_method']
        },
        transactions: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              amount: {
                type: 'object',
                properties: {
                  total: { type: 'string' },
                  currency: { type: 'string' }
                },
                required: ['total', 'currency']
              },
              description: { type: 'string' }
            },
            required: ['amount']
          }
        }
      },
      required: ['intent', 'payer', 'transactions']
    }
  },

• src/index.ts:66-90 (schema)

  TypeScript interface defining the structure of PayPalPayment used for type safety in the handler and validation.

  interface PayPalPayment {
    id?: string;
    intent: string;
    payer: {
      payment_method: string;
      funding_instruments?: Array<{
        credit_card?: {
          number: string;
          type: string;
          expire_month: number;
          expire_year: number;
          cvv2: string;
          first_name: string;
          last_name: string;
        };
      }>;
    };
    transactions: Array<{
      amount: {
        total: string;
        currency: string;
      };
      description?: string;
    }>;
  }

• src/index.ts:349-401 (helper)

  Helper function validatePayment that parses, validates, and structures the tool arguments according to the PayPalPayment interface, throwing MCP errors on invalid input.

  private validatePayment(args: unknown): PayPalPayment {
    if (typeof args !== 'object' || !args) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid payment data');
    }
  
    const payment = args as Record<string, unknown>;
    
    if (typeof payment.intent !== 'string' ||
        !payment.payer || typeof payment.payer !== 'object' ||
        !Array.isArray(payment.transactions) ||
        payment.transactions.length === 0) {
      throw new McpError(ErrorCode.InvalidParams, 'Missing required payment fields');
    }
  
    const payer = payment.payer as Record<string, unknown>;
    if (typeof payer.payment_method !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid payment method');
    }
  
    const transactions = payment.transactions.map(transaction => {
      const trans = transaction as Record<string, unknown>;
      if (!trans.amount || typeof trans.amount !== 'object') {
        throw new McpError(ErrorCode.InvalidParams, 'Invalid transaction amount');
      }
  
      const amount = trans.amount as Record<string, unknown>;
      if (typeof amount.total !== 'string' || typeof amount.currency !== 'string') {
        throw new McpError(ErrorCode.InvalidParams, 'Invalid amount fields');
      }
  
      const validatedTransaction = {
        amount: {
          total: amount.total,
          currency: amount.currency
        }
      };
  
      if (typeof trans.description === 'string') {
        (validatedTransaction as any).description = trans.description;
      }
  
      return validatedTransaction;
    });
  
    return {
      intent: payment.intent,
      payer: {
        payment_method: payer.payment_method,
        funding_instruments: payer.funding_instruments as PayPalPayment['payer']['funding_instruments']
      },
      transactions
    };
  }