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.

Related MCP server: Yolfi MCP Server

✨ 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.

┌────────────────┐    ┌───────────────┐    ┌──────────────────┐
│                │    │               │    │                  │
│  Assistente IA ├────┤  Servidor MCP ├────┤  API Gotas       │
│  (Claude)      │    │  (FastAPI)    │    │  Commerce        │
│                │    │               │    │                  │
└────────────────┘    └───────────────┘    └──────────────────┘

📋 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:

uvicorn src.gotas_mcp_server:app --host 0.0.0.0 --port 8000

Integration with Claude Desktop

To use directly with Claude Desktop:

python install_claude.py

Alternatively, install manually:

mcp install src.gotas_mcp_server.py

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

├── src/
│   └── gotas_mcp_server.py  # Implementação principal do servidor MCP
├── .env                     # Variáveis de ambiente (API key, etc.)
├── .smithery.json           # Configuração para Smithery CLI
├── check_payment.py         # Utilitário para verificar status de pagamentos
├── docsdaapigotas.md        # Documentação detalhada da API
├── install_claude.py        # Script para instalação no Claude Desktop
├── mcp.md                   # Documentação do servidor MCP
├── MCPPROTOCOLpython.MD     # Documentação do protocolo MCP em Python
├── requirements.txt         # Dependências do projeto
├── setup.bat                # Script de configuração para Windows
├── smithery.json            # Schema para integração com Smithery
└── test_client.py           # Cliente de teste para criação de pagamentos

🔒 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)

Usuário: Preciso gerar um link de pagamento de 50 USDT.

Claude: Vou gerar um link de pagamento para você. Para qual URL devo configurar o redirecionamento após o pagamento?

Usuário: https://meusite.com.br/obrigado

Claude: [Utilizando ferramenta create-payment]
Criando pagamento de 50 USDT com redirecionamento para https://meusite.com.br/obrigado...

Pronto! Criei um link de pagamento para 50 USDT.

Link de pagamento: [URL gerado pela API]
Este link expirará em 30 minutos. O cliente deve transferir exatamente 50 USDT para o endereço da carteira mostrado na página de pagamento.

Checking Status (via Claude)

Usuário: Verifique o status do meu pagamento com ID xyz123.

Claude: [Utilizando ferramenta check-payment-status]
Verificando o status do pagamento ID xyz123...

O status atual do pagamento é: PENDENTE
- Valor: 50.00 USDT
- Criado em: [timestamp]
- Expira em: [timestamp]

O pagamento ainda não foi confirmado na blockchain. Você pode acompanhar usando o link de pagamento ou me pedir para verificar novamente mais tarde.

📞 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