rapay-mcp-server

Ra Pay MCP Server

MCP (Model Context Protocol) server for AI agent payment automation. Enables Claude Desktop, Claude API, and ChatGPT to execute payments via Ra Pay CLI.

Status: Perplexity Security Review APPROVED (98% confidence)

Features

• 6 MVP tools for payment operations
• Subprocess isolation (credentials never leave keyring)
• Response sanitization (prevents prompt injection)
• Rate limiting (1 payment/min, 10 queries/min)
• Audit logging

Installation

Prerequisites

• Node.js 18+
• Ra Pay CLI installed and authenticated (ra link-bank)

Setup

cd rapay/mcp-server
npm install
npm run build

Claude Desktop Configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "rapay": {
      "command": "node",
      "args": ["/Users/yourname/rapay/mcp-server/dist/index.js"]
    }
  }
}

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "rapay": {
      "command": "node",
      "args": ["C:\\Users\\yourname\\rapay\\mcp-server\\dist\\index.js"]
    }
  }
}

With custom CLI path:

{
  "mcpServers": {
    "rapay": {
      "command": "node",
      "args": ["/path/to/rapay/mcp-server/dist/index.js"],
      "env": {
        "RAPAY_CLI_PATH": "/custom/path/to/ra"
      }
    }
  }
}

After adding, restart Claude Desktop. You should see "rapay" in the MCP servers list.

Tools

Payment Operations (SENSITIVE)

Tool	Description
ra_send	Execute a payment transaction
ra_subscribe	Create a subscription for a customer
ra_refund	Open Stripe Dashboard for refunds

Query Operations

Tool	Description
ra_balance	Check available balance
ra_history	Get transaction history
ra_whoami	Check account status

Security

Subprocess Isolation

MCP server spawns Ra Pay CLI as subprocess. Credentials remain in OS keyring - MCP server never sees them directly.

Response Sanitization

All CLI output is sanitized to prevent prompt injection:

• ANSI escape sequences removed
• System markers filtered ([SYSTEM], [USER], etc.)
• Control characters stripped

Rate Limiting

Defense-in-depth layer at MCP level:

Tool	Limit
ra_send	1 per 60 seconds
ra_subscribe	1 per 60 seconds
ra_refund	5 per 60 seconds
ra_balance	10 per 60 seconds
ra_history	10 per 60 seconds
ra_whoami	20 per 60 seconds

Note: Backend also enforces velocity controls (account-tier daily limits).

Privacy & Data Storage

Ra Pay is designed as a "dumb pipe" to Stripe:

What Ra Pay stores:

• Your user ID
• Your Stripe account ID (encrypted)
• Action logs: "payment sent", "balance checked" (no amounts)
• Transaction audit trail with Stripe transfer IDs

What Ra Pay does NOT store:

• Your payment amounts
• Recipient details
• Payment descriptions
• Your account balance
• Any personally identifiable information (Stripe handles KYC)

What MCP server adds:

• Client type tracking ("called via Claude Desktop")
• Tool call audit logs (same privacy level as above)
• No new PII storage

Configuration

Environment Variables

Variable	Description	Default
RAPAY_CLI_PATH	Path to Ra Pay CLI executable	ra

Audit Logging

Logs are written to ~/.rapay/mcp-audit.log with 7-day retention:

• Tool name, timestamp, duration
• Result (success/error/rate_limited)
• Sanitized inputs (amounts redacted, emails masked)

Error Handling

Error Codes

Code	Description	Retryable
RATE_LIMIT_EXCEEDED	MCP rate limit hit	No (wait)
CLI_NOT_FOUND	Ra Pay CLI not installed	No
TOS_ACCEPTANCE_REQUIRED	ToS not accepted	No
ACCOUNT_NOT_LINKED	Stripe account not linked	No
VELOCITY_EXCEEDED	Daily limit exceeded	No
TIMEOUT	Request timed out	Yes
NETWORK_ERROR	Network connectivity issue	Yes
EXECUTION_FAILED	Generic CLI error	No

Rate Limit Error

{
  "error": "rate_limit_exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please wait 60 seconds.",
  "retry_after_seconds": 60,
  "retryable": false
}

CLI Not Found Error

{
  "error": "cli_not_found",
  "code": "CLI_NOT_FOUND",
  "message": "Ra Pay CLI not found. Please install it first.",
  "retryable": false
}

ToS Required Error

{
  "error": "tos_required",
  "code": "TOS_ACCEPTANCE_REQUIRED",
  "message": "Terms of Service must be accepted. Run 'ra accept-tos' first.",
  "retryable": false
}

For Claude API Callers: Exponential Backoff

If you receive RATE_LIMIT_EXCEEDED, implement exponential backoff:

const maxRetries = 3;
let delay = 60; // seconds

for (let attempt = 0; attempt < maxRetries; attempt++) {
  try {
    return await mcp.callTool('ra_send', params);
  } catch (error) {
    if (error.code === 'RATE_LIMIT_EXCEEDED') {
      console.log(`Rate limited. Waiting ${delay}s before retry...`);
      await sleep(delay * 1000);
      delay *= 2; // exponential backoff
    } else {
      throw error;
    }
  }
}

// DO NOT:
// - Retry immediately (wastes time, still rate limited)
// - Retry more than 3 times (indicates genuine rate limit)
// - Ignore retry_after_seconds field

Note: MCP rate limiting is client-side defense-in-depth. Backend also enforces velocity controls per account tier.

Data Flow

You (Claude Desktop/API)
    |
    v
MCP Server (this package)
    | - Logs tool calls (no amounts/PII)
    | - Rate limits requests
    | - Sanitizes responses
    v
Ra Pay CLI (subprocess)
    | - Credentials in OS keyring
    | - Adds replay protection
    v
Ra Pay Backend
    | - Validates requests
    | - Enforces velocity limits
    v
Stripe API
    | - Owns all PII
    | - Processes payments
    v
Recipient's Bank

All sensitive data flows directly to Stripe. Ra Pay only records that an action occurred.

Development

npm run dev    # Watch mode
npm run build  # Build
npm run lint   # Lint
npm run test   # Test

License

MIT