Kushki MCP Server

A Model Context Protocol (MCP) server for Kushki payment integrations. This server provides tools for retrieving Kushki integration documentation and creating payment buttons for payment processing.

Table of Contents

• Overview
• Project Structure
• Installation
• Usage
• Available Tools
  • Get Kushki Integration
  • Get Kushki Docs
  • Create Payment Button
  • Void Transaction
  • Get Subscription Info
  • List transactions
• Development
• Building for Production
• Using the Published MCP Server
  • Using with npx
  • Installing as a Project Dependency
• Integrating with AI Models and IDE Extensions
  • Using with Claude Desktop App
  • Using with Cursor
  • Using with Visual Studio Code (GitHub Copilot)
  • Using with Cline (VS Code Extension)
  • Using with Anthropic API Directly
  • Troubleshooting MCP Integration
• Configuration Options

Overview

This MCP server provides tools for integrating with Kushki payment services. It allows you to:

• Retrieve documentation for Kushki payment integrations
• Get integration templates for different frontend frameworks and backend languages
• Create payment buttons using the webcheckout API
• Void or refund transactions that have been processed
• Retrieve detailed information about recurring subscriptions
• List transactions within a specified date range

Project Structure

src/
├── index.ts                  # Main entry point
├── server.ts                 # Server setup and initialization
├── types/
│   └── index.ts              # Type definitions
├── tools/
│   ├── index.ts              # Tool exports
│   ├── getKushkiIntegration.ts  # Get Kushki integration tool
│   ├── getKushkiDocs.ts      # Get Kushki docs tool
│   ├── createPaymentButton.ts # Payment button tool
│   ├── voidTransaction.ts    # Void transaction tool
│   └── getSubscriptionInfo.ts # Subscription info tool
│   └── listTransactions.ts   # List transactions tool
└── utils/
    ├── index.ts              # Utility exports
    ├── fileUtils.ts          # File handling utilities
    └── httpClient.ts         # HTTP client for API requests

Installation

Prerequisites

• Node.js v22 or later
• npm v10 or later

1. Clone the repository:

git clone <repository-url>
cd kushki-mcp

2. Install dependencies:

npm install

Usage

Running in Development Mode

To run the server in development mode with hot reloading:

npm run dev

Running in Production Mode

To build and run the server in production mode:

npm run build
npm run start

Available Tools

The MCP server provides the following tools:

Get Kushki Integration

Retrieves Kushki payment method integration prompts.

Parameters:

• frontend_framework (optional): Frontend integration framework (e.g., "React", "Angular")
• backend_language (optional): Backend integration language (e.g., "Node.js", "Python")

Example:

{
  "tool": "get-kushki-integration",
  "params": {
    "frontend_framework": "React",
    "backend_language": "Node.js"
  }
}

Get Kushki Docs

Retrieves Kushki payment method integration documentation.

Parameters:

• frontend_framework (optional): Frontend integration framework
• backend_language (optional): Backend integration language

Example:

{
  "tool": "get-kushki-docs",
  "params": {
    "frontend_framework": "React",
    "backend_language": "Node.js"
  }
}

Create Payment Button

Creates a Kushki payment button using the webcheckout API.

Parameters:

• private_merchant_id (required if not provided as environment variable): Private Merchant ID for authentication
• redirect_url (required): URL to redirect after payment
• products (required): Array of products with the following structure:

  [
    {
      "description": "Product description",
      "name": "Product name",
      "quantity": 1,
      "unitPrice": 10.00
    }
  ]

• payment_config (required): Payment configuration object with the following structure:

  {
    "amount": {
      "subtotalIva0": 10.00,
      "currency": "USD",
      "iva": 0,
      "subtotalIva": 0
    },
    "paymentMethod": ["credit-card"]
  }

• contact_detail (optional): Contact details with the following structure:

  {
    "email": "[email protected]",
    "name": "Customer Name"
  }

• additional_information (optional): Additional information to be included in the webhook metadata

Note: For better security, it's recommended to provide the Private Merchant ID as an environment variable (KUSHKI_PRIVATE_MERCHANT_ID) when starting the server, rather than passing it as a parameter to the tool.

Response Format:

{
  "id": "mpEtCyMJV",
  "url": "https://uat-webcheckout.kushkipagos.com/webcheckout/mpEtCyMJV"
}

Example:

{
  "tool": "create-payment-button",
  "params": {
    "private_merchant_id": "your-private-merchant-id",
    "redirect_url": "https://your-website.com/thank-you",
    "products": [
      {
        "description": "Premium T-shirt",
        "name": "T-shirt",
        "quantity": 1,
        "unitPrice": 25.00
      },
      {
        "description": "Stylish cap",
        "name": "Cap",
        "quantity": 2,
        "unitPrice": 15.00
      }
    ],
    "payment_config": {
      "amount": {
        "subtotalIva0": 55.00,
        "currency": "USD",
        "iva": 0,
        "subtotalIva": 0
      },
      "paymentMethod": ["credit-card", "card-async"]
    },
    "contact_detail": {
      "email": "[email protected]",
      "name": "John Doe"
    },
    "additional_information": {
      "orderId": "ORD-12345",
      "customerType": "regular"
    }
  }
}

Void Transaction

Voids or refunds a Kushki transaction that was previously processed.

Parameters:

• private_merchant_id (required if not provided as environment variable): Private Merchant ID for authentication
• ticket_number (required): The ticket number of the transaction to void or refund
• full_response (optional): Set to "v2" to get a more detailed response
• amount (optional): For partial voids/refunds (only available in Chile, Colombia, Mexico and Peru)

  {
    "subtotalIva": 500,
    "subtotalIva0": 0,
    "ice": 0,
    "iva": 0,
    "currency": "MXN"
  }

• external_reference_id (optional): Your own reference ID for the transaction (5-64 characters)

Note: When the date of the transaction to void surpasses the timeframe for automatic voiding, it becomes a refund. Partial voids are only available in Chile, Colombia, Mexico and Peru.

Response Format:

{
  "details": {
    "transactionId": "123456789",
    "transactionStatus": "INITIALIZED",
    "transactionType": "VOID",
    "approvalCode": "123456",
    "responseText": "Transaction voided successfully",
    "ticketNumber": "123456789012"
  }
}

Example:

{
  "tool": "void-transaction",
  "params": {
    "private_merchant_id": "your-private-merchant-id",
    "ticket_number": "123456789012",
    "full_response": "v2",
    "amount": {
      "subtotalIva": 500,
      "subtotalIva0": 0,
      "ice": 0,
      "iva": 0,
      "currency": "MXN"
    }
  }
}

Get Subscription Info

Retrieves detailed information about a Kushki recurring subscription.

Parameters:

• private_merchant_id (required if not provided as environment variable): Private Merchant ID for authentication
• subscription_id (required): The ID of the subscription to retrieve information for

Response Format:

{
  "amount": {
    "subtotalIva0": 19.99,
    "subtotalIva": 0,
    "iva": 0,
    "ice": 0,
    "currency": "USD"
  },
  "bin": "411111",
  "cardHolderName": "John Doe",
  "cardType": "credit",
  "contactDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]"
  },
  "created": "2023-01-15T10:30:00.000Z",
  "lastFourDigits": "1111",
  "maskedCardNumber": "411111******1111",
  "merchantId": "merchant123",
  "metadata": {
    "customerId": "cust123",
    "plan": "premium"
  },
  "paymentBrand": "Visa",
  "periodicity": "monthly",
  "planName": "Premium Subscription",
  "startDate": "2023-01-15T10:30:00.000Z",
  "subscriptionId": "sub_123456789"
}

Example:

{
  "tool": "get-subscription-info",
  "params": {
    "private_merchant_id": "your-private-merchant-id",
    "subscription_id": "sub_123456789"
  }
}

List Transactions

Retrieves a list of transactions processed through Kushki within a specified date range.

Parameters:

• private_merchant_id (required if not provided as environment variable): Private Merchant ID for authentication
• from (required): Start date of search in ISO format (YYYY-MM-DDTHH:MM:SS). Example: 2022-03-10T13:39:00
• to (required): End date of search in ISO format (YYYY-MM-DDTHH:MM:SS). Example: 2022-03-10T23:00:00

Notes:

• The date range should not exceed 30 days
• Dates must be in ISO format (YYYY-MM-DDTHH:MM:SS)
• The maximum number of transactions returned is limited by the Kushki API

Response Format:

{
  "total": 2,
  "count": 2,
  "transactions": [
    {
      "id": "123456789",
      "ticketNumber": "123456789012",
      "amount": 25.00,
      "currency": "USD",
      "status": "APPROVED",
      "type": "SALE",
      "date": "2022-03-10T14:30:00",
      "cardInfo": {
        "brand": "Visa",
        "lastFourDigits": "1234",
        "cardHolderName": "John Doe",
        "maskedNumber": "411111******1234"
      },
      "contactDetails": {
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe"
      }
    },
    {
      "id": "987654321",
      "ticketNumber": "987654321098",
      "amount": 50.00,
      "currency": "USD",
      "status": "APPROVED",
      "type": "SALE",
      "date": "2022-03-10T16:45:00",
      "cardInfo": {
        "brand": "Mastercard",
        "lastFourDigits": "5678",
        "cardHolderName": "Jane Smith",
        "maskedNumber": "511111******5678"
      },
      "contactDetails": {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Smith"
      }
    }
  ]
}

Example:

{
  "tool": "list-transactions",
  "params": {
    "private_merchant_id": "your-private-merchant-id",
    "from": "2022-03-10T13:39:00",
    "to": "2022-03-10T23:00:00"
  }
}

Development

Adding New Tools

To add a new tool to the MCP server:

1. Create a new file in the src/tools directory
2. Implement the tool using the MCP server's tool registration API
3. Export the tool registration function
4. Import and register the tool in src/server.ts

Modifying Existing Tools

To modify an existing tool:

1. Locate the tool implementation in the src/tools directory
2. Make the necessary changes
3. Rebuild the server if running in production mode

Building for Production

To build the server for production:

npm run build

This will compile the TypeScript code to JavaScript in the dist directory.

Using the Published MCP Server

Once the Kushki MCP server is published to npm, you can use it in your projects in several ways:

Using with npx

You can run the MCP server directly with npx without installing it:

npx -y @kushki/mcp-server

You can also set environment variables:

PORT=4000 NODE_ENV=production npx -y @kushki/mcp-server

Or use command-line arguments:

npx -y @kushki/mcp-server --private-merchant-id=your-private-id

Installing as a Project Dependency

To use the MCP server as a dependency in your project:

npm install @kushki/mcp-server

Then, you can use it in your code:

import { startServer } from '@kushki/mcp-server';

// Start the MCP server with configuration options
startServer({
  // You can provide the Private Merchant ID directly
  privateMerchantId: 'your-private-merchant-id'
})
  .then(() => {
    console.log('Kushki MCP server started successfully');
  })
  .catch((error) => {
    console.error('Failed to start Kushki MCP server:', error);
  });

// Alternatively, you can let the server get the Private Merchant ID
// from environment variables or command-line arguments
startServer()
  .then(() => {
    console.log('Kushki MCP server started successfully');
  })
  .catch((error) => {
    console.error('Failed to start Kushki MCP server:', error);
  });

Integrating with AI Models and IDE Extensions

Once the Kushki MCP server is published to npm, you can use it with various AI assistants and IDE extensions that support the Model Context Protocol (MCP). Here's how to set it up with popular tools:

Using with Claude Desktop App

1. Open the Claude Desktop app and navigate to Settings.

2. Under the Developer tab, click Edit Config to open the configuration file.

3. Add the following configuration:

   {
     "mcpServers": {
       "kushki": {
         "command": "npx",
         "args": ["-y", "@kushki/mcp-server", "--private-merchant-id=your-private-id"]
       }
     }
   }

4. Save the configuration file and restart Claude Desktop.

5. From the new chat screen, you should see a hammer (MCP) icon appear with the Kushki MCP server available.

6. You can now ask Claude to use the Kushki tools:

   Please use the get-kushki-docs tool to show me the documentation for Kushki payment integrations.

Using with Cursor

1. Create a .cursor directory in your project root if it doesn't exist.

2. Create a .cursor/mcp.json file and add the following configuration:

   {
     "mcpServers": {
       "kushki": {
         "command": "npx",
         "args": ["-y", "@kushki/mcp-server", "--private-merchant-id=your-private-id"]
       }
     }
   }

3. Save the configuration file.

4. Open Cursor and navigate to Settings/MCP. You should see a green active status after the server is successfully connected.

5. You can now ask Cursor to use the Kushki tools:

   Please use the get-kushki-integration tool with frontend_framework=React and backend_language=Node.js to show me how to integrate Kushki payments.

Using with Visual Studio Code (GitHub Copilot)

1. Create a .vscode directory in your project root if it doesn't exist.

2. Create a .vscode/mcp.json file and add the following configuration:

   {
     "servers": {
       "kushki": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@kushki/mcp-server", "--private-merchant-id=your-private-id"]
       }
     }
   }

3. Save the configuration file.

4. Make sure MCP support is enabled in VS Code settings (it's enabled by default in VS Code 1.99+).

5. Open GitHub Copilot chat and switch to "Agent" mode. You should see a tool icon that you can tap to confirm the MCP tools are available.

6. You can now ask Copilot to use the Kushki tools:

   Please use the get-kushki-docs tool to show me the documentation for Kushki payment integrations.

Using with Cline (VS Code Extension)

1. Open the Cline extension in VS Code and click the MCP Servers icon.

2. Click Configure MCP Servers to open the configuration file.

3. Add the following configuration:

   {
     "mcpServers": {
       "kushki": {
         "command": "npx",
         "args": ["-y", "@kushki/mcp-server", "--private-merchant-id=your-private-id"]
       }
     }
   }

4. Save the configuration file. Cline should automatically reload the configuration.

5. You should see a green active status after the server is successfully connected.

6. You can now ask Cline to use the Kushki tools:

   Please use the create-payment-button tool to create a payment button with the following parameters:
   - private_merchant_id: "your-private-merchant-id"
   - redirect_url: "https://your-website.com/thank-you"
   - products: [
     {
       "description": "Premium T-shirt",
       "name": "T-shirt",
       "quantity": 1,
       "unitPrice": 25.00
     }
   ]
   - payment_config: {
       "amount": {
         "subtotalIva0": 25.00,
         "currency": "USD",
         "iva": 0,
         "subtotalIva": 0
       },
       "paymentMethod": ["credit-card"]
     }
   - contact_detail: {
       "email": "[email protected]",
       "name": "John Doe"
     }

Using with Anthropic API Directly

If you're using the Anthropic API directly in your application:

1. In your API request to Anthropic, include the tool configuration:

   {
     "model": "claude-3-opus-20240229",
     "max_tokens": 4096,
     "messages": [
       {
         "role": "user",
         "content": "I need help with Kushki payment integration."
       }
     ],
     "tools": [
       {
         "name": "get-kushki-docs",
         "description": "Kushki payment method integration docs"
       },
       {
         "name": "get-kushki-integration",
         "description": "Kushki payment method integration prompts"
       },
       {
         "name": "create-payment-button",
         "description": "Create a Kushki payment button using webcheckout"
       },
       {
         "name": "void-transaction",
         "description": "Void or refund a Kushki transaction"
       },
       {
         "name": "get-subscription-info",
         "description": "Get information about a Kushki recurring subscription"
       },
       {
         "name": "list-transactions",
         "description": "List Kushki transactions within a specified date range"
       }
     ]
   }

2. Handle the tool calls in your application by forwarding them to the MCP server running with npx -y @kushki/mcp-server.

Troubleshooting MCP Integration

If you encounter issues with the AI model not recognizing the MCP server:

1. Make sure the MCP server is running and accessible.
2. Check that the AI model or extension supports the Model Context Protocol.
3. Try restarting both the MCP server and the AI application.
4. Verify that there are no firewall or network issues blocking the connection.
5. Check the logs of the MCP server for any error messages.
6. Ensure you're using the correct configuration format for each tool (they may vary slightly).

Configuration Options

You can configure the MCP server using either environment variables or command-line arguments.

Environment Selection

The MCP server can be configured to use either the test (UAT) or production environment for Kushki API calls.

• Test Environment: Uses https://api-uat.kushkipagos.com as the base URL (default)
• Production Environment: Uses https://api.kushkipagos.com as the base URL

You can specify the environment using:

# Using command-line argument
npx -y @kushki/mcp-server --environment=production

# Using environment variable
KUSHKI_ENVIRONMENT=production npx -y @kushki/mcp-server

Environment Variables

When running the MCP server with npx, you can set the following environment variables:

• KUSHKI_ENVIRONMENT: The environment to use (production or test, default: test)
• KUSHKI_PRIVATE_MERCHANT_ID: Your Kushki Private Merchant ID for authentication (recommended for security)
• NODE_ENV: The environment mode (development, production)

Example:

KUSHKI_ENVIRONMENT=production KUSHKI_PRIVATE_MERCHANT_ID=your-private-id npx -y @kushki/mcp-server

Command-Line Arguments

You can also provide configuration options as command-line arguments:

• --environment: The environment to use (production or test, default: test)
• --private-merchant-id: Your Kushki Private Merchant ID for authentication

Example:

npx -y @kushki/mcp-server --environment=production --private-merchant-id=your-private-id

You can combine environment variables and command-line arguments. Command-line arguments take precedence over environment variables.

Example:

PORT=4000 NODE_ENV=production npx -y @kushki/mcp-server --private-merchant-id=your-private-id

If you don't provide the Private Merchant ID (either via environment variable or command-line argument), you'll need to include it as a parameter when using the create-payment-button tool.

License

ISC