Payman AI Financial Interface Server (MCP Implementation)

This Model Context Protocol (MCP) backend facilitates direct interaction with Payman AI's core financial APIs, enabling Large Language Models (LLMs) to execute payment workflows via conversational prompts.

Core Functionality Overview

This service exposes Payman AI's capabilities as structured tools consumable by AI agents (like Claude). Key supported actions include:

• Provisioning and managing authorization tokens (API Keys).
• Registering various recipient types: simulated rail transfers (TEST_RAILS), standard US banking (US_ACH), and digital asset addresses (CRYPTO_ADDRESS).
• Executing outgoing financial disbursements.
• Retrieving records of registered recipients.
• Querying real-time aggregated account standings.

Adherence to the Model Context Protocol (MCP) specification guarantees broad compatibility with compliant client environments.

Key Capabilities

• Credential Security: Authentication secrets are managed securely within the active operational context.
• Diverse Payee Architectures:
  • TEST_RAILS: Environments designated for transactional validation.
  • US_ACH: Facilitates domestic electronic fund transfers within the US.
  • CRYPTO_ADDRESS: Supports sending value to decentralized digital wallets.
• Transaction Management:
  • Initiate transfers specifying value, recipient identifier, and optional remittance notes.
  • Fetch up-to-the-minute ledger balances.
• Recipient Discovery: Locate stored beneficiaries using attributes such as identifiers, contact data, or account specifics.
• Robust Feedback Loops: Implementation of comprehensive error reporting for all remote service interactions.
• Transport Agnostic: Supports both conventional synchronous I/O streams and asynchronous Server-Sent Events (SSE).

System Prerequisites

• A compatible execution environment supporting Node.js (minimum version 14).
• Package management utility: npm or yarn.
• Valid credentials for accessing the Payman AI platform.

Deployment Instructions

Automatic Setup via Smithery

Install payman_mcp for rapid integration with tools like Claude Desktop using the Smithery CLI:

npx -y @smithery/cli install @hrishi0102/payman_mcp --client claude

Manual Source Installation

1. Clone the repository source:

   bash git clone https://github.com/yourusername/payman-mcp-server.git cd payman-mcp-server

2. Install requisite dependencies:

   ```bash npm install

   OR

   yarn install ```

3. Compile the source code (e.g., TypeScript):

   ```bash npm run build

   OR

   yarn build ```

Runtime Configuration

No static configuration files are mandated. API access tokens are supplied dynamically via the set-api-key tool during the agent session.

Initiating the Service

Standard Input/Output Mode (For Local Desktop Clients)

Execute the server using the stdio stream, suitable for clients like Claude Desktop:

Confirm readiness with:

node /ABSOLUTE/PATH/TO/PARENT/FOLDER/payman-mcp/build/payman-server.js

Upon successful initialization, integrate the server endpoint into your chosen MCP client.

• Claude Desktop Integration Guide: Refer here
• Cursor Integration Guide: Refer here

Server-Sent Events (SSE) Transport Mode (For Web Integration)

To utilize an HTTP listener (requires express and cors packages):

node build/payman-server-sse.js

This launches an HTTP service on port 3001, exposing:

• /sse: The unidirectional data stream channel.
• /messages: The bidirectional channel for client command submission.

Client Integration Guide (MCP Consumers)

Once the server establishes connection with an MCP client, tool invocation becomes available:

Credential Assignment

Authentication must be established first:

Please utilize the set-api-key function with my Payman credential: YOUR_API_KEY_HERE

Recipient Provisioning

Simulated Rail Recipient

Provision a simulation recipient named "Test User" tagged as "test"

US Domestic ACH Recipient

Establish a US_ACH recipient with the following specifications:
- Display Name: John Doe
- Account Class: checking
- Account Number: 12345678
- Bank Identifier (Routing): 123456789
- Account Owner Name: John Doe
- Owner Status: individual

Cryptocurrency Recipient

Set up a CRYPTO_ADDRESS recipient:
- Label: Crypto Wallet
- Destination: 0x1234567890abcdef
- Blockchain: ethereum
- Asset Ticker: ETH

Executing Transfers

Disburse an amount of 100.00 to recipient identifier "pay_123abc" referencing memo "Monthly service"

Recipient Index Search

Locate all financial recipients whose designation includes "John"

Account Status Check

Report on the current available capital.

Tool Catalog Reference

set-api-key

Registers the authentication token for subsequent API calls.

• Parameters:
• apiKey (string): The confidential Payman access token

create-test-rails-payee

Generates a recipient record for sandbox testing.

• Parameters:
• name (string): Alias for the recipient
• type (string): Fixed value: "TEST_RAILS"
• tags (string[]): Optional associative labels

create-us-ach-payee

Registers a standard US bank account recipient.

• Parameters:
• type (string): Fixed value: "US_ACH"
• accountType (enum): Must be "checking" or "savings"
• accountNumber (string): The destination account identifier
• routingNumber (string): The financial institution routing code
• accountHolderName (string): Full name of the account owner
• accountHolderType (enum): Either "individual" or "business"
• name (string): Internal friendly name
• Additional contextual fields available (e.g., contactDetails)

create-crypto-payee

Registers a blockchain destination address.

• Parameters:
• type (string): Fixed value: "CRYPTO_ADDRESS"
• address (string): The recipient wallet address
• chain (string): The associated blockchain network
• currency (string): The specific digital asset (e.g., BTC, ETH)
• name (string): Internal friendly name
• Additional contextual fields available (e.g., contactDetails)

send-payment

Initiates the transfer of funds.

• Parameters:
• payeeId (string): Unique identifier for the destination
• amountDecimal (number): The exact quantum of currency to transfer
• walletId (string, optional): Source wallet identifier
• memo (string, optional): Descriptive transaction notation
• metadata (object, optional): Supplementary structured data

search-payees

Performs indexed lookups across the recipient database.

• Parameters: Various optional filtering predicates
• name, contactEmail, accountNumber, etc.

get-balance

Fetches the present financial standing of the associated account.

• Parameters: Zero required arguments

Fault Reporting Mechanisms

Each exposed function incorporates robust defensive programming to report errors clearly if:

• Authentication token is absent or invalid.
• Remote API calls yield failures.
• Input arguments violate schema constraints.
• Connectivity interruptions occur.

Security Posture

• API access credentials reside exclusively in volatile memory for the session lifetime.
• No sensitive information is written to persistent storage by the server process.

• Authorization headers are correctly applied to all outgoing Payman service interactions.

• Reference Specification: Model Context Protocol Documentation

• Target API Provider: Payman AI Services
• Validation Library: Zod Schema Definition

XHR/AJAX CONTEXT: XMLHttpRequest (XHR) represents an object-oriented interface implemented in JavaScript for making asynchronous Hypertext Transfer Protocol (HTTP) requests between a client environment (like a web browser) and a remote server. XHR fundamentally enables web applications to update portions of a page dynamically without requiring a full page reload, a core principle of Asynchronous JavaScript and XML (Ajax) programming. Before XHR, server interaction mandated traditional form submissions or link navigation, invariably causing the viewport to refresh.

== Historical Development == The foundational concept for this asynchronous request mechanism originated in 2000 with developers associated with Microsoft Outlook. Its initial concrete implementation appeared in Internet Explorer version 5 (released in 1999). Crucially, the prototype did not utilize the standardized XMLHttpRequest identifier; instead, developers employed COM object instantiations such as ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), universal support for the standard XMLHttpRequest name had been established across all major browser platforms, including Mozilla's Gecko rendering engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Process === The World Wide Web Consortium (W3C) published its initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. This evolved into the Level 2 Working Draft on February 25, 2008, introducing capabilities for monitoring data transfer progress, enabling cross-origin requests, and processing raw byte streams. By the close of 2011, the Level 2 features were merged back into the primary specification document. Subsequent maintenance transitioned to the WHATWG consortium starting in late 2012, which now sustains the document as a living standard using Web IDL.

== Typical Implementation Flow == Executing a remote request via XMLHttpRequest typically involves a sequence of defined programmatic steps:

1. Instantiation: Create an instance of the XMLHttpRequest object via its constructor call.
2. Configuration: Invoke the open() method to define the HTTP method (GET, POST, etc.), specify the target resource URI, and determine if the operation should be synchronous or asynchronous.
3. Asynchronous Listener Setup: For non-blocking operations, assign an event handler function to react when the request's state attribute changes.
4. Transmission: Trigger the request initiation using the send() method, optionally passing payload data.
5. Response Handling: Monitor the state changes within the event listener. Upon reaching state 4 (the 'done' status), the server response data is typically accessible via the responseText property.

Beyond these fundamentals, XHR offers fine-grained control over request behavior. Custom HTTP headers can be injected to influence server processing. Data intended for the server can be uploaded within the send() argument. Responses can be immediately parsed from JSON into native JavaScript objects or streamed incrementally without waiting for the total transmission to conclude. Furthermore, requests can be canceled mid-flight or constrained by a defined timeout duration.

== Cross-Origin Constraints == During the nascent phases of the World Wide Web, inherent security limitations prevented scripts loaded from one origin (domain/port/protocol) from making direct network calls to a different origin, a restriction known as the Same-Origin Policy. This limited early web application interactivity.