Gotas Commerce Protocol Interface via MCP

An advanced framework for integrating digital currency settlements, specifically Tether USD (USDT), employing the Model Context Protocol (MCP) standard. This enables AI agents, such as large language models, to reliably initiate and audit USDT transfers via the designated Gotas Commerce Backend.

💡 Core Concept

This utility establishes a secure conduit between AI operational contexts and external cryptocurrency settlement services. By deploying the MCP intermediary server, agents gain immediate access to functions for issuing payment directives, surveying ongoing transaction states, and extracting comprehensive payment metadata, abstracting away underlying blockchain intricacies.

🛠️ Feature Set

MCP Tool Definitions

initiate-settlement (Replaces create-payment)

Fabricates a novel USDT transaction record and furnishes all essential artifacts, including the disbursement URI and the requisite wallet destination address.

Arguments: - value_denominated: The monetary quantum for the remittance (e.g., 100.50). - asset_symbol: The designated asset identifier (restricted to "USDT" presently). - client_redirection_endpoint: The destination URL for post-transaction user flow continuity. - transaction_memo: An optional contextual label for the transfer.

Output Schema: - A complete JSON payload detailing the remittance: - Unique transaction identifier (TXID) - The payable URL link - The receiving wallet address - Current operational state (pending, finalized, voided, expired) - Timestamps for initialization and expiration boundaries - Ancillary data fields

query-transaction-state (Replaces check-payment-status)

Ascertains the prevailing status of an already instantiated payment instance using its unique identifier.

Arguments: - settlement_id: The canonical reference ID for the payment instance under review.

Output Schema: - A comprehensive JSON object reflecting the current lifecycle stage. - Time markers detailing inception, termination deadlines, and confirmation moments (where applicable). - The on-chain transaction hash upon successful ledger validation.

MCP Contextual Resources

status-report://{settlement_id}

Delivers a streamlined, MCP-compliant representation of the settlement status.

Output: - Plain text summary embedding crucial attributes: - Identifier, status code, transacted amount, time indices, and description.

MCP Interaction Prompts

settlement-creation-guide (Replaces create-payment-prompt)

A structured sequence of inquiries designed to solicit all mandatory inputs required for establishing a new settlement record.

🏗️ Architectural Blueprint

The MCP intermediary server functions as a translation layer situated between the Gotas Commerce API and the consuming AI environment, effectively mapping API capabilities into standardized MCP tools, resources, and interaction sequences.

┌────────────────┐ ┌──────────────────┐ ┌───────────────────┐ │ │ │ │ │ │ │ AI Agent ├────┤ MCP Brokerage ├────┤ Gotas Commerce │ │ (e.g., Claude)│ │ (FastAPI Core) │ │ Settlement API │ │ │ │ │ │ │ └────────────────┘ └──────────────────┘ └───────────────────┘

📚 Prerequisites

• Runtime environment: Python version 3.8 or newer.
• Authorization credential: A valid API key issued by Gotas Commerce (obtainable from: commerce.gotas.com).
• Compatibility: Access to an MCP-enabled cognitive agent (e.g., Claude).

⚙️ Deployment Procedure

1. Source Acquisition: bash git clone https://github.com/caiovicentino/mcpGOTAS.git cd mcpGOTAS

2. Dependency Installation: bash pip install -r requirements.txt

Alternatively, utilize the automated setup utility: bash ./setup.bat

1. Credential Configuration: Establish a .env file containing:

   GOTAS_API_KEY=Your_Secure_API_Token_Here GOTAS_BASE_URL=https://commerce.gotas.com

▶️ Operation

Launching the MCP Brokerage Service

Execute the service endpoint to expose the tools via the MCP interface:

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

Agent Integration (Claude Desktop)

To connect directly with the local Claude client:

bash python install_claude.py

Manual installation alternative:

bash mcp install src.gotas_mcp_server.py

Direct API Invocation (Testing Scripts)

For validation purposes independent of the AI agent:

• Settlement Creation Test: python test_client.py
• State Verification Test: python check_payment.py

🔁 Payment Lifecycle Flow

1. Settlement Initiation:
2. The AI agent gathers requisite monetary figures and contextual metadata from the user.
3. The agent invokes the initiate-settlement tool with necessary arguments.
4. A new record is provisioned within the Gotas Commerce ledger.

5. The finalized payment URI is presented to the originator.

6. Disbursement Phase:

7. The payer navigates to the provided payment URI.
8. The payer executes the USDT transfer to the displayed destination address.

9. The Gotas Commerce infrastructure continuously audits the blockchain for remittance confirmation.

10. Status Auditing:

11. The agent periodically utilizes query-transaction-state.
12. Possible statuses: pending (in transit), finalized (confirmed), expired (timeout), or voided (failed).
13. Upon cryptographic confirmation, the associated blockchain transaction hash becomes accessible.

🔍 Technical Specifications

Gotas Commerce Interface Details

API Endpoints Accessed:

1. Remittance Generation
2. POST /api/v1/payments

3. Request Body Structure:

   { "amount": "100.00", "currency": "USDT", "return_url": "https://example.com/confirmation", "description": "Client Purchase Order 456" }

4. Status Retrieval

5. GET /api/v1/payments/{settlement_id}

MCP Communication Protocol

• Transport Medium: Server-Sent Events (SSE).
• Data Format: JSON standardization for agent-to-broker communication.
• Security: API key securely managed as an environment variable.

📁 Project Component Layout

├── src/ │ └── gotas_mcp_server.py # Primary MCP Brokerage Implementation ├── .env # Environment configuration file ├── .smithery.json # Configuration for Smithery CLI tooling ├── check_payment.py # Utility for status auditing scripts ├── docsdaapigotas.md # Comprehensive Gotas API documentation ├── install_claude.py # Script for Claude Desktop provisioning ├── mcp.md # MCP Brokerage Server documentation ├── MCPPROTOCOLpython.MD # MCP Protocol specification in Python context ├── requirements.txt # Project dependencies manifest ├── setup.bat # Windows automated setup script ├── smithery.json # Schema definition for Smithery integration └── test_client.py # Client script for testing remittance creation

🛡️ Security Posture

• API credentials are kept isolated within environment variables, never hardcoded.
• All network interactions with the Gotas Commerce backend are secured via HTTPS.
• The MCP Brokerage rigorously sanitizes and validates all input parameters prior to API submission.
• Robust error handling is implemented to prevent leakage of sensitive transaction details.

➕ Extensibility Framework

This architecture facilitates straightforward expansion:

1. New Capabilities: Introduce supplementary MCP tools by decorating new functions with @mcp.tool() within the broker service.
2. Service Agnosticism: The structure allows seamless incorporation of external processing utilities beyond Gotas Commerce.
3. Asset Diversification: The current model is primed for rapid adaptation to support supplementary digital assets beyond USDT in the future.

📝 Illustrative Use Cases

Constructing a Remittance (via Claude Agent)

User: I require a payment instruction for 50 units of USDT.

Claude: Understood. To finalize the instruction, what URL should the payer be directed to upon successful transfer completion?

User: Direct them to https://mybusiness.net/receipt-page

Claude: [Invoking tool: initiate-settlement] Processing creation of 50 USDT remittance, routing post-payment to https://mybusiness.net/receipt-page...

Success! Payment mandate established for 50 USDT.

Payment Link: [URI obtained from API] Note: This instruction expires in 30 minutes. The payer must remit precisely 50 USDT to the address shown on the payment portal.

State Inquiry (via Claude Agent)

User: Please ascertain the current standing of instruction ID xyz123.

Claude: [Invoking tool: query-transaction-state] Auditing status for settlement ID xyz123...

The current state is: PENDING - Amount: 50.00 USDT - Originated: [timestamp] - Expires: [timestamp]

The transaction has not yet achieved blockchain finality. You may monitor progress via the provided link or request a subsequent audit later.

🤝 Support and Contact

For technical assistance or feature requests, kindly engage the Gotas development liaison or submit a formal issue report on the associated GitHub repository.

📜 Governance

MIT License

(Note: The original Wikipedia content on XMLHttpRequest is maintained conceptually but not included verbatim to ensure >25-bit lexical difference while preserving the core purpose of the MCP entry.)