Skip to main content
Glama
TropiPay MCP Server

TropiPay MCP Server

by yosle

TropiPay MCP Server

TypeScript Node.js License: MIT

A Model Context Protocol (MCP) server for interacting with TropiPay's payment platform. This server provides a standardized interface for AI assistants in various development environments to perform TropiPay operations through tools and resources.

✨ Features

  • Authentication: Handles OAuth 2.0 client credentials flow with TropiPay

  • Modular Architecture: Clean separation of concerns with TypeScript

  • TropiPay API Integration: Comprehensive wrapper around TropiPay's functionality

  • Tool-Based Interface: Easy integration with AI assistants

  • Environment Support: Configure for sandbox or production environments

  • Editor Compatibility: Works with VS Code, Cursor, Windsurf, and other MCP-compatible editors

Related MCP server: @striderlabs/mcp-cashapp

πŸ› οΈ Available Tools

Account Management

  • get_default_account_balance: Retrieve current default account balance

  • get_profile_data: Get user profile information

  • get_accounts_list: List all TropiPay accounts

Transactions

  • get_movement_list: View transaction history with pagination

  • list_deposit_accounts: List deposit accounts/beneficiaries (bank accounts, crypto wallets, etc.)

  • list_paymentcards: Get list of payment cards (payment links) created by the user

Beneficiary Management

  • create_internal_beneficiary: Create a new internal TropiPay beneficiary

    • Required Fields: alias, searchValue (email)

  • create_external_beneficiary: Create a new external bank account beneficiary

    • Required Fields: firstName, lastName, accountNumber, currency, countryDestinationId/countryISO

  • create_crypto_beneficiary: Create a new crypto wallet beneficiary

    • Required Fields: firstName, lastName, accountNumber (wallet address), currency, network

  • create_paymentcard: Create payment links (called payment cards in TropiPay)

    • Required Fields: amount, currency, concept, description

    • Optional Fields: reference, favorite, singleUse, expirationDays, reasonId, lang, urlSuccess, urlFailed, urlNotification, serviceDate, accountId

System

  • test_connection: Verify API connectivity and authentication

πŸ“š Available Resources

The TropiPay MCP Server provides the following reference resources:

  • tropipay://config: Current TropiPay API configuration and environment settings

  • tropipay://status: TropiPay API connection status and health check

  • tropipay://movement-types: Complete reference of TropiPay movementType IDs and their meanings

  • tropipay://movement-states: Complete reference of TropiPay movement state codes and their meanings

  • tropipay://account-states: Complete reference of TropiPay account state codes and their meanings

πŸš€ Getting Started

Prerequisites

  • Node.js 20+

  • npm or yarn

  • TropiPay API credentials (Client ID and Client Secret)

Installation

  1. Clone the repository:

    git clone https://github.com/yosle/tropipay-mcp-server.git
    cd tropipay-mcp-server
    npm install
  2. Install dependencies:

    npm install

MCP Client Configuration

This MCP server can be used with any MCP-compatible client such as Claude Desktop, Windsurf, Cline, or other AI assistants that support the Model Context Protocol.

Configuration File Locations

Locate your client's MCP configuration file:

  • Claude Desktop:

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Linux: ~/.config/Claude/claude_desktop_config.json

  • Windsurf:

    • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

    • MacOS: ~/.codeium/windsurf/mcp_config.json

    • Linux: ~/.codeium/windsurf/mcp_config.json

  • Cline: Refer to the Cline documentation for configuration details

Installation Methods

You can run the server directly with npx:

{
  "mcpServers": {
    "tropipay": {
      "command": "npx",
      "args": ["-y", "tropipay-mcp-server"],
      "env": {
        "TROPIPAY_CLIENT_ID": "your_client_id",
        "TROPIPAY_CLIENT_SECRET": "your_client_secret",
        "TROPIPAY_BASE_URL": "https://sandbox.tropipay.me"
      }
    }
  }
}
Option 2: Local Development/Installation

For local development or if you've cloned the repository:

{
  "mcpServers": {
    "Tropipay MCP Server": {
      "command": "node",
      "args": [
        "D:\\proyectos\\tropipay-mcp-server\\tropipay-mcp-server\\build\\index.js"
      ],
      "env": {
        "TROPIPAY_CLIENT_ID": "your_client_id",
        "TROPIPAY_CLIENT_SECRET": "your_client_secret",
        "TROPIPAY_BASE_URL": "https://sandbox.tropipay.me"
      }
    }
  }
}

Environment Variables

Configure the following environment variables in your MCP client configuration:

Variable

Required

Description

Default

TROPIPAY_CLIENT_ID

βœ… Yes

Your TropiPay API client ID

-

TROPIPAY_CLIENT_SECRET

βœ… Yes

Your TropiPay API client secret

-

TROPIPAY_ENVIRONMENT

❌ No

Environment: sandbox or production

sandbox

TROPIPAY_BASE_URL

❌ No

Custom API base URL (overrides environment)

Based on environment

Base URL Options

  • Sandbox: https://sandbox.tropipay.me (default)

  • Production: https://www.tropipay.com

  • Local Development: http://localhost:3001 (or your custom endpoint)

Important Notes:

  • For Windows paths, use double backslashes: "D:\\folder\\tropipay-mcp-server\\build\\index.js"

  • For Linux/Mac paths, use forward slashes: "/home/user/tropipay-mcp-server/build/index.js"

  • The -y flag in npx automatically confirms package installation

  • Make sure to run npm run build before using the local installation method

πŸ—οΈ Project Structure

src/
β”œβ”€β”€ client/         # TropiPay client initialization and management
β”œβ”€β”€ config/         # Configuration management
β”œβ”€β”€ resources/      # MCP resource handlers
β”œβ”€β”€ tools/          # Tool definitions and handlers
β”‚   β”œβ”€β”€ definitions.ts
β”‚   └── handlers.ts
β”œβ”€β”€ types/          # TypeScript type definitions
└── index.ts        # Main server entry point

πŸ” Usage Examples

Get a list of my beneficiaries 

Getting Account Balance

Get the balance in all my Tropipay accounts 

πŸ“ License

This project is licensed under the MIT License - see the LICENSE file for details.

🀝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

πŸ“§ Contact

For questions or support, please open an issue on GitHub.

Available Tools

11 tools
create_crypto_beneficiaryA

Create a new crypto wallet beneficiary using TropiPay API.

Required: firstName, lastName, accountNumber (wallet address), currency, network

Example:

{
  "firstName": "John",
  "lastName": "Doe",
  "accountNumber": "5Hw3k2c4Z5oLWxfTMT8nBnhqWF4SWcAFQLnJTJPzNe2y",
  "currency": "USDC",
  "network": "SOLANA"
}

Inputs: network (required), currency (required), lastName (required), firstName (required), +7 more.

create_external_beneficiaryA

Create a new external bank account beneficiary using TropiPay API.

Required: firstName, lastName, accountNumber, currency, countryDestinationId/countryISO

Example:

{
  "firstName": "Panfilo",
  "lastName": "Epifanio",
  "accountNumber": "ES91 2100 0418 4502 0005 1332",
  "currency": "EUR",
  "countryDestinationId": 1,
  "swift": "CAIXESBBXXX",
  "address": "Gran Via de les Corts Catalanes, 765",
  "city": "Barcelona",
  "province": "Barcelona",
  "postalCode": "08013"
}

Inputs: currency (required), lastName (required), firstName (required), accountNumber (required), +22 more.

create_internal_beneficiaryA

Create a new internal TropiPay beneficiary using TropiPay API.

Required: alias, searchValue (email)

Example:

{
  "alias": "MR Buchman",
  "searchValue": "wick@gmail.com",
  "searchBy": 1
}

Inputs: alias (required), searchValue (required), type, email, +11 more.

create_paymentcardA

Create a new payment card (payment link) using TropiPay API. IMPORTANT:- NEVER create payment cards without first asking the user for required information- ALWAYS collect: amount, currency, concept, and description before proceeding- DO NOT generate or assume default values for required fields- Ask clarifying questions if any information is missing or unclearRequired Information to Collect from User:

  • amount, currency, concept, description

  • Any specific requirements (expiration, single use, etc.)

πŸ“‹ Optional Fields:

  • reference

  • favorite

  • singleUse

  • expirationDays

  • reasonId

  • lang

  • urlSuccess

  • urlFailed

  • urlNotification

  • serviceDate

  • accountId πŸ” Process Flow:

  1. First ask user for: amount, currency, concept, and description

  2. Optionally ask about: expiration days, single use, reference, redirect URLs

  3. Then create the payment card with provided information

  4. Return the payment card information to the user

Inputs: amount (required), concept (required), currency (required), lang, +11 more.

get_accounts_listB

Get list of TropiPay accounts associated with the user

Inputs: no named parameters.

get_default_account_balanceA

Get the current selected as default account balance from TropiPay

Inputs: no named parameters.

get_movement_listA

Get list of account movements/transactions (requires ALLOW_GET_MOVEMENT_LIST scope).

πŸ“‹ Response Structure:

  • count: Total number of movements available

  • rows: Array of movement objects with the following key fields:

  • id: Unique movement identifier

  • amount: Transaction amount (+ for credits, - for debits)

  • currency: Currency code (USD, EUR, etc.)

  • movementTypeId: Type classification (1=Transfer, 2=Card Credit, 3=Refund, 4=Card Refund, 5=Top Up, 6=Exchange, 7=ATM, 8=Fee, 9=Adjustment)

  • state: Transaction status (2=Charged, 3=Paid, 4=Error, 5=Pending In, 6=Cancelled)

  • bankOrderCode: Transaction identifier (TX prefix for regular, DEV for refunds)

  • balanceBefore/balanceAfter: Account balance before/after transaction

  • reference: User-defined reference

  • conceptTransfer: Transaction description

  • completedAt/createdAt: Transaction timestamps

  • fee: Transaction fee (if applicable)

  • accountId: Id of the account that this movement belongs

  • originalCurrencyAmount: Amount in original currency

  • destinationAmount: Amount in destination currency

  • destinationCurrency: Destination currency code

  • conversionRate: Applied rate for this movement

  • paymentcard: uuid of asociated paymentcard to this movement or null otherwise πŸ’‘ Tip: Use the 'tropipay_movements_schema' prompt for detailed field explanations.

Inputs: limit, offset.

get_profile_dataA

Get user profile information from TropiPay account

Inputs: no named parameters.

list_deposit_accountsA

Get list of deposit accounts (a.k.a beneficiaries).

πŸ’‘ Tip: deposit accounts are also refered as beneficiaries can be internal (other Tropipay accounts) or external (bank accounts, external cripto wallets)

πŸ“‹ Response Structure:

  • `Array of depositaccounts objects:

  • id: Unique deposit account identifier

  • accountNumber: IBAN for external bank accounts, wallet address for external crypto accounts, email of user for internal beneficiaries)

  • alias: if not null, User-friendly account name/alias set by user

  • currency: Account currency

  • type: Account type (9=Tropipay account, 12=Crypto wallet, 7=Other, 8=BANDEC card, 4= BPA card, 3=BANMET card)

  • state: Account status (0=Active, 1=Inactive, 2=Deleted)

  • countrydestination: Object with info about the country where the account is registered,slug, name etc

  • userRelationTypeId: Type of relation with the user (0=myself, 3=commercial)

  • createdAt/updatedAt: Account creation and modification timestamps

  • firstName: First name of the beneficiary with the account

  • lastName: Last name of the beneficiary with the account

Inputs: no named parameters.

list_paymentcardsA

Get list of paymentcards (paylinks) created by the user

Inputs: no named parameters.

test_connectionA

Test the connection to TropiPay API and verify authentication by retrieving the selected default account balance

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 11 tools

    Disambiguation3/5

    Most tools target distinct resources (balance, profile, accounts, movements, payment cards, beneficiaries), but test_connection overlaps with get_default_account_balance by also retrieving the balance, and the three create_*_beneficiary tools are very similar in function though differentiated by beneficiary type. Agents may struggle to pick between these without careful reading.

    Naming Consistency4/5

    Tools generally follow a verb_noun pattern in snake_case (get_profile_data, list_deposit_accounts), but there is inconsistency with compound nouns: 'list_paymentcards' and 'create_paymentcard' lack the expected underscore between 'payment' and 'card', unlike 'get_default_account_balance' and 'list_deposit_accounts'. This is a minor deviation from an otherwise predictable pattern.

    Tool Count5/5

    With 11 tools, the set is well-sized for a payment server covering balance, profile, accounts, movements, payment cards, and beneficiaries. Each tool addresses a distinct need without excessive granularity or bloat.

    Completeness3/5

    The read side is solid (profile, balance, accounts, movements, cards, beneficiaries) and creation is supported for payment cards and all beneficiary types. However, there are no update/delete operations for cards or beneficiaries, nor any transfer/payment initiation tools, leaving clear gaps in the expected lifecycle for a payment platform.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers