npm package: @payxor/mcp-client
Description: MCP server for PayXor client operations - quotes, balances, entitlements
Author: PayXor
Latest version: 0.1.2

# @payxor/mcp-client

MCP (Model Context Protocol) server for PayXor client operations. Enables AI models to interact with PayXor for payments, quotes, and entitlement checks.

## Features

- **Quote Generation**: Get signed payment quotes for products
- **Transaction Confirmation**: Confirm payments after execution
- **Balance & Allowance Checks**: Query token balances and approvals
- **Entitlement Verification**: Check session, feature, and pass statuses
- **Chain & Token Info**: Access supported chains and stablecoins

## Installation

```bash
npm install @payxor/mcp-client
# or
yarn add @payxor/mcp-client
# or
pnpm add @payxor/mcp-client
```

## Quick Start

### MCP Configuration

Add the following to your AI tool's MCP config:

```json
{
  "mcpServers": {
    "payxor-client": {
      "command": "npx",
      "args": ["@payxor/mcp-client"]
    }
  }
}
```

> **Note:** You can use `yarn dlx` or `pnpm dlx` instead of `npx`.

### Config File Locations

| AI Tool | Config File Path |
|---------|------------------|
| **Cursor** | `.cursor/mcp.json` (in project root) |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **Cline** | VS Code Command Palette → "Cline: MCP Servers" |

### Continue (VS Code)

Continue uses a different format. Add to `~/.continue/config.json`:

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["@payxor/mcp-client"]
        }
      }
    ]
  }
}
```

### Standalone

```bash
npx @payxor/mcp-client
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PAYXOR_API_URL` | `https://api.payxor.xyz` | PayXor backend API URL |

## Available Tools

### `get_quote`

Generate a signed payment quote for a product.

**Parameters:**
- `appId` (string): App ID (bytes32 hex string)
- `productId` (string): Product ID (bytes32 hex string)
- `chainId` (number): Target blockchain chain ID
- `payer` (string): Payer's wallet address
- `tokenAddress` (string, optional): Specific token for payment

### `confirm_transaction`

Confirm a payment transaction after execution.

**Parameters:**
- `txHash` (string): Transaction hash
- `quoteId` (string): Quote ID from the quote

### `check_balance`

Check a user's token balance.

**Parameters:**
- `tokenAddress` (string): ERC20 token address
- `owner` (string): Wallet address
- `chainId` (number): Chain ID

### `check_allowance`

Check token allowance for PayXor contract.

**Parameters:**
- `tokenAddress` (string): ERC20 token address
- `owner` (string): Wallet address
- `chainId` (number): Chain ID

### `get_product_info`

Get public product information.

**Parameters:**
- `appId` (string): App ID (bytes32 hex string)
- `productId` (string): Product ID (bytes32 hex string)

### `get_app_stablecoins`

Get supported stablecoins for an app on a chain.

**Parameters:**
- `appId` (string): App ID (bytes32 hex string)
- `chainId` (number): Chain ID

### `check_session`

Check if a user has an active session entitlement.

**Parameters:**
- `payer` (string): User's wallet address
- `appId` (string): App ID (bytes32 hex string)
- `productId` (string): Product ID (bytes32 hex string)
- `chainId` (number): Chain ID

### `check_feature`

Check if a user has unlocked a specific feature.

**Parameters:**
- `payer` (string): User's wallet address
- `appId` (string): App ID (bytes32 hex string)
- `entitlementId` (string): Entitlement ID (bytes32 hex string)
- `chainId` (number): Chain ID

### `check_pass`

Check if a user holds a specific pass.

**Parameters:**
- `payer` (string): User's wallet address
- `appId` (string): App ID (bytes32 hex string)
- `passId` (string): Pass ID (bytes32 hex string)
- `chainId` (number): Chain ID

## Available Resources

### `payxor://chains`

List of all supported blockchain networks (mainnets and testnets).

### `payxor://chains/{chainId}/stablecoins`

Stablecoins available on a specific chain. Resources are registered for all supported chains.

### `payxor://entitlements`

Help guide for entitlement checks. Use the `check_session`, `check_feature`, and `check_pass` tools for dynamic entitlement verification.

## Available Prompts

Prompts are reusable templates that help users interact with PayXor in a consistent way.

### `payment_flow`

Guides through the complete payment process: check product info, verify balance/allowance, get quote, and confirm transaction.

**Parameters:**
- `appId` (string): App ID (bytes32 hex string)
- `productId` (string): Product ID (bytes32 hex string)
- `chainId` (number): Target blockchain chain ID
- `payer` (string): Payer's wallet address
- `tokenAddress` (string, optional): Specific token address for payment

### `check_entitlements`

Template for checking various types of user entitlements (session, feature, or pass).

**Parameters:**
- `payer` (string): User's wallet address
- `appId` (string): App ID (bytes32 hex string)
- `chainId` (number): Chain ID
- `entitlementType` (enum): Type of entitlement - `"session"`, `"feature"`, or `"pass"`
- `entitlementId` (string): Product ID (for session), Entitlement ID (for feature), or Pass ID (for pass)

### `verify_payment_readiness`

Checks if a user has sufficient balance and allowance before getting a payment quote.

**Parameters:**
- `payer` (string): User's wallet address
- `appId` (string): App ID (bytes32 hex string)
- `productId` (string): Product ID (bytes32 hex string)
- `chainId` (number): Chain ID
- `tokenAddress` (string, optional): Specific token address to check

## Example Usage (AI Conversation)

```
User: Check if 0x1234... has an active session for product 0xabcd... on Base

AI: [Uses payxor://entitlement/session/0x1234.../0xapp.../0xabcd.../8453]
    The session is active and will expire in 2 hours.

User: Get a quote for that product

AI: [Uses get_quote tool]
    Here's the quote:
    - Amount: 10 USDC
    - Expires: 1 hour
    - Quote ID: 12345
```

## Supported Chains

**Mainnets:** Ethereum (1), Arbitrum (42161), Base (8453), Polygon (137), Optimism (10), Avalanche (43114), BNB Chain (56), zkSync (324)

**Testnets:** Sepolia (11155111), Base Sepolia (84532), Arbitrum Sepolia (421614), and more

## License

MIT