paymentsafe-mcp

MCP server for PaymentSafe — integrate African escrow payments directly into Cursor, Claude Desktop, Claude Code, Windsurf, Kiro, Cline, Roo Code, Continue, VS Code Copilot, and any MCP-compatible AI IDE.

PaymentSafe is a secure escrow payment platform built for African peer-to-peer marketplaces. Buyers pay into escrow, funds are held safely, and sellers only get paid after delivery is confirmed — protecting both sides of every deal.

This package exposes PaymentSafe's full API as a Model Context Protocol (MCP) server, so AI coding assistants can create and manage escrow transactions in natural language — no payment SDK boilerplate required.

Table of Contents

• Prerequisites
• Quick Start
• IDE Setup
  • Cursor
  • Claude Desktop
  • Claude Code (CLI)
  • Windsurf
  • Kiro
  • Cline
  • Roo Code
  • Continue
  • VS Code (GitHub Copilot)
• Available Tools
• Example Prompts
• Environment Variables
• Supported Countries & Currencies
• Troubleshooting
• Related Packages
• Support

Prerequisites

• Node.js 18+ — download here
• A PaymentSafe API key — get yours free at paymentsafe.business → Developer Portal → My Apps

Quick Start

No installation needed. Run it directly with npx:

PAYMENTSAFE_API_KEY=sk_sandbox_your_key npx paymentsafe-mcp

Or install globally:

npm install -g paymentsafe-mcp
PAYMENTSAFE_API_KEY=sk_sandbox_your_key paymentsafe-mcp

IDE Setup

Cursor

Add to your ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "paymentsafe": {
      "command": "npx",
      "args": ["paymentsafe-mcp"],
      "env": {
        "PAYMENTSAFE_API_KEY": "sk_sandbox_your_key_here"
      }
    }
  }
}

Restart Cursor, then open the MCP panel — you will see 7 PaymentSafe tools available.

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "paymentsafe": {
      "command": "npx",
      "args": ["paymentsafe-mcp"],
      "env": {
        "PAYMENTSAFE_API_KEY": "sk_sandbox_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You can now tell Claude to "create an escrow for my deal" and it will call PaymentSafe directly.

Claude Code (CLI)

Claude Code is Anthropic's terminal-based AI coding agent. Add the server with one command:

claude mcp add paymentsafe \
  --command npx \
  --args paymentsafe-mcp \
  --env PAYMENTSAFE_API_KEY=sk_sandbox_your_key_here

Or to make it available across all projects (user scope):

claude mcp add paymentsafe --scope user \
  --command npx \
  --args paymentsafe-mcp \
  --env PAYMENTSAFE_API_KEY=sk_sandbox_your_key_here

Verify it's connected:

claude mcp list

You can also add it manually to ~/.claude.json under the mcpServers key:

{
  "mcpServers": {
    "paymentsafe": {
      "command": "npx",
      "args": ["paymentsafe-mcp"],
      "env": {
        "PAYMENTSAFE_API_KEY": "sk_sandbox_your_key_here"
      }
    }
  }
}

Then run /mcp inside any Claude Code session to check server status.

Windsurf

Add to your Windsurf MCP settings (~/.codeium/windsurf/mcp_settings.json):

{
  "mcpServers": {
    "paymentsafe": {
      "command": "npx",
      "args": ["paymentsafe-mcp"],
      "env": {
        "PAYMENTSAFE_API_KEY": "sk_sandbox_your_key_here"
      }
    }
  }
}

Kiro

Kiro is Amazon's AI IDE. MCP servers can be configured at workspace level (project-only) or user level (all projects).

Workspace level — create .kiro/settings/mcp.json in your project root:

{
  "mcpServers": {
    "paymentsafe": {
      "command": "npx",
      "args": ["-y", "paymentsafe-mcp"],
      "env": {
        "PAYMENTSAFE_API_KEY": "sk_sandbox_your_key_here"
      }
    }
  }
}

User level (available in all your projects) — create ~/.kiro/settings/mcp.json with the same content.

Enable MCP in Kiro:

1. Open Settings (Ctrl+, or Cmd+,)
2. Search for MCP and make sure MCP support is enabled
3. Open the Kiro panel → MCP Servers tab to verify PaymentSafe is connected

If tools don't appear, check Output → Kiro - MCP Logs for errors.

Cline

Cline is the most popular open-source agentic VS Code extension. Open the Cline panel → MCP Servers icon → Configure tab → click Configure MCP Servers to open the settings file, or edit it directly:

• All platforms: ~/.cline/data/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "paymentsafe": {
      "command": "npx",
      "args": ["-y", "paymentsafe-mcp"],
      "env": {
        "PAYMENTSAFE_API_KEY": "sk_sandbox_your_key_here"
      }
    }
  }
}

Reload VS Code after saving. The PaymentSafe tools will appear in Cline's tool list automatically.

Roo Code

Roo Code is a powerful VS Code agentic extension. Configure at global level (all projects) or project level.

Project level — create .roo/mcp.json in your project root:

{
  "mcpServers": {
    "paymentsafe": {
      "command": "npx",
      "args": ["-y", "paymentsafe-mcp"],
      "env": {
        "PAYMENTSAFE_API_KEY": "sk_sandbox_your_key_here"
      }
    }
  }
}

Global level — open the Roo Code pane → MCP Servers icon → Edit Global MCP. The file is at:

• Windows: %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json
• macOS/Linux: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

Project-level config takes precedence over global when both exist.

Continue

Continue is an open-source AI coding assistant for VS Code and JetBrains. Add PaymentSafe to your Continue config file (~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "paymentsafe",
      "command": "npx",
      "args": ["-y", "paymentsafe-mcp"],
      "env": {
        "PAYMENTSAFE_API_KEY": "sk_sandbox_your_key_here"
      }
    }
  ]
}

Reload the Continue extension after saving. You can then reference PaymentSafe tools in any Continue chat session.

VS Code (GitHub Copilot)

Add to your VS Code settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "paymentsafe": {
      "command": "npx",
      "args": ["paymentsafe-mcp"],
      "env": {
        "PAYMENTSAFE_API_KEY": "sk_sandbox_your_key_here"
      }
    }
  }
}

Available Tools

| Tool | Description | |------|-------------| | create_escrow | Create a new escrow transaction between a buyer and seller | | get_transaction | Get the status and details of an existing transaction | | list_transactions | List all transactions for your API key (last 50) | | release_funds | Release held funds to the seller after delivery | | open_dispute | Freeze funds and open a dispute for staff review | | confirm_delivery | Mark an item as received by the buyer | | get_rates | Get current GHS / USD / EUR exchange rates |

Example Prompts

Once connected in your AI IDE, you can use natural language:

Create an escrow for a GHS 6,500 iPhone 14 sale.
Buyer: +233540000001, Seller: +233244000002. Give 3 days inspection.

What is the status of transaction tx-api-1234567890-abc123?

List all my recent PaymentSafe transactions.

The buyer confirmed delivery on tx-api-xxx — release the funds to the seller.

Open a dispute on transaction tx-api-yyy. The item was not as described.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PAYMENTSAFE_API_KEY | Yes | Your API key (sk_sandbox_* for testing, sk_live_* for production) | | PAYMENTSAFE_BASE_URL | No | Override the API base URL (default: https://api.paymentsafe.business/v1) |

Sandbox vs Live

• Keys starting with sk_sandbox_ use test mode — no real money moves
• Keys starting with sk_live_ use live mode — real transactions
• Always test with a sandbox key first

Supported Countries & Currencies

PaymentSafe supports payments across Africa. Currently accepted currencies:

| Currency | Code | Countries | |----------|------|-----------| | Ghanaian Cedi | GHS | Ghana | | US Dollar | USD | Nigeria, Kenya, Uganda, Tanzania, Rwanda, Zambia, Senegal, Ivory Coast, and more | | Euro | EUR | Cross-border and diaspora payments |

More local currencies coming soon. For USD/EUR transactions, PaymentSafe applies real-time exchange rates automatically.

Troubleshooting

PAYMENTSAFE_API_KEY environment variable is not set Add your API key to the env section of your MCP config file. Restart your IDE after saving.

MCP server not showing up in your IDE Verify Node.js 18+ is installed: node --version Try running npx paymentsafe-mcp manually in your terminal to see any errors.

API error 401: Unauthorized Your API key is wrong or expired. Get a new one at paymentsafe.business → Developer Portal → My Apps.

Network error Check your internet connection. PaymentSafe API endpoint: https://api.paymentsafe.business/v1

Related Packages

| Package | Description | |---------|-------------| | paymentsafe-js | Official JavaScript/TypeScript SDK for Node.js, Next.js, and browser apps |

Support

• Docs: https://paymentsafe.business/docs
• API keys: https://paymentsafe.business (Developer Portal)
• Email: [email protected]
• Issues: https://github.com/Transoft-Technologies/holdpayment/issues

Made with love by Transoft Technologies, Accra, Ghana