npm package: @qvapay/mcp-server
Description: MCP server for QvaPay — AI-native payment platform with P2P trading, market data, and crypto payments
Latest version: 2.0.1

# @qvapay/mcp-server

MCP (Model Context Protocol) server for [QvaPay](https://qvapay.com) — enabling AI assistants to interact with the QvaPay payment platform.

## Features

- **29 tools** covering market data, P2P trading, merchant, and user operations
- **Market Data** (public, no auth): Crypto prices, coin listings, P2P averages, stats, and rankings
- **P2P Trading**: Create/edit/cancel offers, apply, chat, rate counterparties
- **Merchant API**: Create invoices, charge users, list transactions
- **User API**: Check balance, transfer money, search users, manage contacts
- **MCP Resources**: Quick access to profile and balance
- **Guided Prompts**: Step-by-step workflows for invoices, transfers, and account summaries

## Installation

```bash
npx @qvapay/mcp-server
```

Or install globally:

```bash
npm install -g @qvapay/mcp-server
```

## Configuration

Set environment variables based on which features you need:

### Market Tools (3 tools) — No auth required

Market tools are always available. They provide public crypto prices and P2P exchange rate averages.

### Merchant Tools (7 tools)

```bash
export QVAPAY_APP_ID="your-app-uuid"
export QVAPAY_APP_SECRET="your-app-secret"
```

Get these from your [QvaPay Developer Dashboard](https://qvapay.com/apps).

### User + P2P Tools (19 tools)

```bash
export QVAPAY_API_TOKEN="your-bearer-token"
```

Get this from your [QvaPay API Settings](https://qvapay.com/settings/api).

### Optional

```bash
export QVAPAY_API_URL="https://qvapay.com/api"  # Custom API URL
```

The server starts with whichever credentials are available. Missing credentials simply means those tools won't be registered. Market tools are always available.

## Usage

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "qvapay": {
      "command": "npx",
      "args": ["@qvapay/mcp-server"],
      "env": {
        "QVAPAY_APP_ID": "your-app-uuid",
        "QVAPAY_APP_SECRET": "your-app-secret",
        "QVAPAY_API_TOKEN": "your-bearer-token"
      }
    }
  }
}
```

### Claude Code

Add to `.claude/settings.json` or `~/.claude.json`:

```json
{
  "mcpServers": {
    "qvapay": {
      "command": "npx",
      "args": ["@qvapay/mcp-server"],
      "env": {
        "QVAPAY_APP_ID": "your-app-uuid",
        "QVAPAY_APP_SECRET": "your-app-secret",
        "QVAPAY_API_TOKEN": "your-bearer-token"
      }
    }
  }
}
```

### If installed globally via npm

```json
{
  "mcpServers": {
    "qvapay": {
      "command": "qvapay-mcp",
      "env": {
        "QVAPAY_APP_ID": "your-app-uuid",
        "QVAPAY_APP_SECRET": "your-app-secret",
        "QVAPAY_API_TOKEN": "your-bearer-token"
      }
    }
  }
}
```

## Tools Reference

### Market Tools (public, no auth)

| Tool | Description |
|------|-------------|
| `qvapay_coins` | List all cryptocurrencies with prices, fees, and limits |
| `qvapay_price_history` | Get price history for a cryptocurrency (1H to ALL) |
| `qvapay_p2p_averages` | Current P2P exchange rate averages for all coins |

### Merchant Tools (requires APP_ID + APP_SECRET)

| Tool | Description |
|------|-------------|
| `qvapay_app_info` | Get merchant app details |
| `qvapay_app_balance` | Get merchant balance |
| `qvapay_create_invoice` | Create payment invoice |
| `qvapay_modify_invoice` | Modify pending invoice |
| `qvapay_charge_user` | Charge authorized user |
| `qvapay_app_transactions` | List app transactions |
| `qvapay_app_transaction_detail` | Get transaction detail |

### User Tools (requires API_TOKEN)

| Tool | Description |
|------|-------------|
| `qvapay_user_profile` | Get profile + balance |
| `qvapay_user_extended` | Extended profile with P2P stats |
| `qvapay_list_transactions` | List transactions with filters |
| `qvapay_transaction_detail` | Get transaction detail |
| `qvapay_transfer` | Transfer money (requires PIN) |
| `qvapay_search_users` | Search users |
| `qvapay_payment_methods` | List payment methods |
| `qvapay_contacts` | List contacts |

### P2P Trading Tools (requires API_TOKEN)

| Tool | Description |
|------|-------------|
| `qvapay_p2p_list` | Browse P2P offers with filters |
| `qvapay_p2p_detail` | Get full details of a P2P offer |
| `qvapay_p2p_create` | Create a new buy/sell offer |
| `qvapay_p2p_edit` | Edit an open offer you own |
| `qvapay_p2p_apply` | Apply to an open offer |
| `qvapay_p2p_cancel` | Cancel a P2P offer |
| `qvapay_p2p_paid` | Mark offer as paid (buyer action) |
| `qvapay_p2p_received` | Confirm payment received (seller action) |
| `qvapay_p2p_chat_read` | Read chat messages from a trade |
| `qvapay_p2p_chat_send` | Send a chat message in a trade |
| `qvapay_p2p_rate` | Rate your counterparty (1-5 stars) |

### Resources

| Resource | URI | Description |
|----------|-----|-------------|
| Profile | `qvapay://profile` | Full user profile with balance |
| Balance | `qvapay://balance` | Quick balance check |

### Prompts

| Prompt | Description |
|--------|-------------|
| `create-invoice` | Guided invoice creation workflow |
| `transfer` | Guided money transfer workflow |
| `account-summary` | Complete account overview |

## Testing

Use the MCP Inspector to verify the server:

```bash
npx @modelcontextprotocol/inspector node src/index.js
```

## Security

- The transfer tool requires a PIN and will always prompt the user
- P2P create/apply operations that move funds require KYC verification
- Credentials are read from environment variables only
- The server is a thin HTTP client — no data is cached or stored
- All communication uses HTTPS

## License

MIT