Gotas Commerce MCP Server

Drops Commerce API & MCP Integration

A robust solution for cryptocurrency payments integration using the MCP (Model Context Protocol), allowing AI assistants like Claude to create and verify USDT transactions through the Gotas Commerce API.

🚀 Overview

This project provides a bridge between AI assistants and cryptocurrency payment services. With the MCP server implemented, assistants can generate payment links, check transaction status, and obtain detailed information about USDT payments without requiring specialized blockchain technical knowledge.

✨ Resources

MCP Tools

create-payment

Creates a new USDT payment transaction and returns all required details including payment URL and wallet address.

Parameters:

• amount : Payment amount (ex: 100.50)
• currency : Currency code (currently just "USDT")
• return_url : URL to redirect the customer after payment
• description : Optional payment description

Return:

• Complete JSON object with all payment details:
  • Unique Payment ID
  • Payment URL
  • Wallet address
  • Status (pending, completed, failed, expired)
  • Creation and expiration dates
  • Other relevant metadata

check-payment-status

It checks the current status of an existing payment through its unique identifier.

Parameters:

• payment_id : Unique ID of the payment to be verified

Return:

• Full JSON object with current payment status
• Timestamp information for creation, expiration, and completion (where applicable)
• Blockchain transaction hash (when payment is confirmed)

MCP Resources

payment-status://{payment_id}

It provides a formatted and simplified version of the payment status as an MCP resource.

Return:

• Formatted text with the most relevant payment information
• Identifier, status, value, timestamps, and description

MCP Prompts

create-payment-prompt

A guided prompt to help the user provide the information needed to create a new payment.

🔧 Architecture

The MCP server acts as an abstraction layer over the Drops Commerce API, translating API capabilities into tools, resources, and prompts that are easily usable by AI assistants like Claude.

📋 Prerequisites

• Python 3.8 or higher
• Gotas Commerce API Key (get it at: commerce.gotas.com )
• Access to an MCP-compatible assistant (such as Claude)

🔌 Installation

1. Clone this repository:
   git clone https://github.com/caiovicentino/mcpGOTAS.git cd mcpGOTAS
2. Install dependencies:
   pip install -r requirements.txt
   Or use the automated setup script:
   ./setup.bat
3. Configure environment variables:
   • Create a .env file with the following values:
     GOTAS_API_KEY=sua_chave_api_aqui GOTAS_BASE_URL=https://commerce.gotas.com

🏃‍♂️ Execution

MCP Server

Run the server to make the tools available via MCP:

Integration with Claude Desktop

To use directly with Claude Desktop:

Alternatively, install manually:

Direct API Usage (Test Scripts)

For direct testing without a wizard:

• Create payment : python test_client.py
• Check status : python check_payment.py

📊 Payment Flow

1. Payment Initialization :
   • The attendant obtains the amount and other payment details from the user.
   • The wizard calls the create-payment tool with the required parameters
   • A new payment is created in Gotas Commerce
   • The payment link is returned to the user
2. Payment Process :
   • The user accesses the payment link provided
   • User transfers USDT to the displayed wallet address
   • Gotas Commerce monitors blockchain to confirm transaction
3. Status Check :
   • The assistant can check the payment status by calling check-payment-status status
   • The status can be: pending, completed, expired or failed.
   • When the payment is confirmed, the blockchain transaction hash is made available.

🔍 Technical Specifications

API Details

Drops Commerce API Endpoints :

1. Create Payment
   • POST /api/v1/payments
   • Request body:
     { "amount": "100.00", "currency": "USDT", "return_url": "https://exemplo.com/retorno", "description": "Descrição do pagamento" }
2. Check Payment Status
   • GET /api/v1/payments/{payment_id}

MCP Communication

• Transport : SSE (Server-Sent Events)
• Format : JSON for communication between assistant and MCP server
• Authentication : API key stored as environment variable

📂 Project Structure

🔒 Security

• The API key is stored as an environment variable, not in the source code
• Communication with Gotas Commerce API is done via HTTPS
• The MCP server validates all parameters before sending to the API
• Proper error handling to avoid exposing sensitive information

🧩 Extensibility

The project is designed to be easily extended:

1. New Features : Add new MCP tools implementing functions decorated with @mcp.tool() on the server
2. Integration with Other Services : The architecture allows you to easily integrate other services besides Gotas Commerce
3. New Coin Support : The framework is prepared to support other cryptocurrencies besides USDT in the future

📚 Usage Examples

Creating a Payment (via Claude)

Checking Status (via Claude)

📞 Support and Contact

For support or additional information, please contact the Gotas development team or open an issue in the GitHub repository.

📜 License

MIT License