npm package: @payxor/mcp-admin
Description: MCP server for PayXor admin operations - apps, products, quotes management
Author: PayXor
Latest version: 0.1.2

# @payxor/mcp-admin

MCP (Model Context Protocol) server for PayXor admin operations. Enables AI models to manage PayXor apps, products, and view analytics.

## Features

- **App Management**: Create, update, and delete PayXor applications
- **Product Management**: Define and manage purchasable products
- **Quote History**: View and filter payment quotes
- **Analytics**: Access revenue stats, conversion rates, and top payers
- **Developer Helpers**: SDK documentation, usage examples, and integration snippets
- **Prompts**: Reusable templates for consistent workflows (app creation, product setup, analytics, etc.)

## Installation

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

## Quick Start

### MCP Configuration

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

```json
{
  "mcpServers": {
    "payxor-admin": {
      "command": "npx",
      "args": ["@payxor/mcp-admin"],
      "env": {
        "PAYXOR_API_KEY": "pxk_your-api-key"
      }
    }
  }
}
```

> **Note:** You can use `yarn dlx` or `pnpm dlx` instead of `npx`.
>
> **Recommended:** Use `PAYXOR_API_KEY` (API keys) instead of `PAYXOR_AUTH_TOKEN` (session tokens). API keys are more stable and can be scoped to specific apps or permissions.

### 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-admin"],
          "env": {
            "PAYXOR_API_KEY": "pxk_your-api-key"
          }
        }
      }
    ]
  }
}
```

### Standalone

```bash
PAYXOR_API_KEY=pxk_your-api-key npx @payxor/mcp-admin
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PAYXOR_API_URL` | No | PayXor backend API URL (default: `https://api.payxor.xyz`) |
| `PAYXOR_API_KEY` | **Recommended** | PayXor API key (starts with `pxk_`) |
| `PAYXOR_AUTH_TOKEN` | Alternative | PayXor session token (use API key instead) |

> Either `PAYXOR_API_KEY` or `PAYXOR_AUTH_TOKEN` is required. API keys are preferred.

## Authentication

### Using API Keys (Recommended)

API keys provide stable, long-lived authentication with configurable permissions:

1. Sign in to the [PayXor Dashboard](https://payxor.xyz/dashboard)
2. Navigate to **API Keys**
3. Click **Create API Key**
4. Configure your key:
   - **Name**: A descriptive name (e.g., "MCP Admin Server")
   - **Scope**: "Full Account" for all apps, or "App-specific" for a single app
   - **Permissions**: "Read & Write" for full access, or "Read Only" for read-only access
5. Copy the generated key (shown only once!)

API keys provide:
- **Stable authentication** - No expiration (unless you set one)
- **Scoped access** - Limit access to specific apps
- **Permission control** - Read-only or read-write access
- **Usage tracking** - See read/write counts and last used timestamp

### Using Session Tokens (Legacy)

Alternatively, you can use a session token from your browser:

1. Sign in to the PayXor dashboard
2. Open browser developer tools (F12)
3. Find the access token in your session storage or cookies

## Available Tools

### App Management

#### `list_apps`

List all apps owned by the authenticated user.

#### `get_app`

Get details of a specific app.

**Parameters:**
- `id` (string): App UUID

#### `create_app`

Create a new PayXor application.

**Parameters:**
- `name` (string): Application name
- `payee` (string): Receiver wallet address
- `supportedNetworks` (number[]): Array of chain IDs
- `supportedStablecoins` (object): Chain ID → token addresses mapping
- `domain` (string, optional): App domain
- `isTesting` (boolean, optional): Testing mode flag

#### `update_app`

Update an existing application.

**Parameters:**
- `id` (string): App UUID
- `name` (string, optional): New name
- `payee` (string, optional): New receiver address
- `supportedNetworks` (number[], optional): New chains
- `supportedStablecoins` (object, optional): New tokens
- `domain` (string, optional): New domain
- `status` (string, optional): "active" or "paused"

#### `delete_app`

Delete an application (cannot be undone).

**Parameters:**
- `id` (string): App UUID

### Product Management

#### `list_products`

List all products for an app.

**Parameters:**
- `appId` (string): App UUID

#### `create_product`

Create a new product.

**Parameters:**
- `appId` (string): App UUID
- `productName` (string): Product name
- `mode` (number): 0=SESSION, 1=FEATURE, 2=RECEIPT, 3=PASS
- `price` (string): Price in smallest unit
- `duration` (number, optional): Duration in seconds (for SESSION)
- `entitlementId` (string, optional): Custom entitlement ID

#### `update_product`

Update a product.

**Parameters:**
- `id` (string): Product UUID
- `productName` (string, optional): New name
- `price` (string, optional): New price
- `duration` (number, optional): New duration

#### `delete_product`

Delete a product (cannot be undone).

**Parameters:**
- `id` (string): Product UUID

### Analytics

#### `list_quotes`

List quotes with optional filters.

**Parameters:**
- `appId` (string): App UUID
- `productId` (string, optional): Filter by product
- `status` (string, optional): "issued", "used", or "expired"
- `chainId` (number, optional): Filter by chain
- `fromDate` (string, optional): Start date (ISO string)
- `toDate` (string, optional): End date (ISO string)
- `limit` (number, optional): Max results
- `offset` (number, optional): Pagination offset

#### `get_stats`

Get app statistics.

**Parameters:**
- `appId` (string): App UUID
- `productId` (string, optional): Filter by product

**Returns:**
- Total/used/expired quotes
- Total revenue, fees, net revenue
- Conversion rate
- Revenue by chain
- Quotes by date range
- Unique payers and top payers

### Developer Helper Tools

These tools help integration developers with SDK documentation, usage examples, and ready-to-use code snippets.

#### `getSdkOverview`

Returns a concise markdown overview of the PayXor SDK.

**Returns:**
- Authentication patterns (walletClient vs transport)
- Main SDK methods (`getProductInfo`, `getQuote`, `pay`, `confirmTransaction`, entitlement checks)
- Initialization examples (with wagmi, standalone)
- Key concepts (quotes, payment modes, entitlements)

**Example:**
```
AI: [Uses getSdkOverview tool]
    Returns comprehensive SDK documentation with code examples
```

#### `getSdkUsage`

Returns TypeScript usage examples for a specific SDK feature/method.

**Parameters:**
- `feature` (string): SDK feature name
  - Available: `getQuote`, `pay`, `checkBalance`, `approveToken`, `isSessionActive`, `getProductInfo`, `confirmTransaction`

**Returns:**
- Method signature
- Common usage patterns
- Error handling examples
- React hook integration examples

**Example:**
```
AI: [Uses getSdkUsage tool with feature="getQuote"]
    Returns detailed TypeScript examples for using getQuote
```

#### `getReactComponentUsage`

Returns props table and real-world TSX usage examples for a React component.

**Parameters:**
- `name` (string): Component name
  - Available: `DropdownBuyButton`, `ProductCard`, `StablecoinSelector`, `Button`, `StatusMessage`, `StatusBadge`

**Returns:**
- Props table with types and descriptions
- Basic usage examples
- Customization patterns (slotClassNames, labels)

**Example:**
```
AI: [Uses getReactComponentUsage tool with name="DropdownBuyButton"]
    Returns component documentation with props table and TSX examples
```

#### `generateIntegrationSnippet`

Generates a ready-to-paste integration code snippet for a specific framework.

**Parameters:**
- `framework` (string): Target framework
  - Available: `nextjs-app-router`, `nextjs-pages-router`, `vite-react`, `remix`
- `productId` (string, optional): Product ID (hex string) - if provided with appId, fetches product info
- `appId` (string, optional): App UUID - required if productId is provided

**Returns:**
- Complete framework-specific integration code
- Correct imports
- Framework-specific setup (wagmi providers, etc.)
- Product-specific details if productId provided

**Example:**
```
AI: [Uses generateIntegrationSnippet tool with framework="nextjs-app-router", productId="0x...", appId="..."]
    Returns complete Next.js App Router integration code ready to paste
```

#### `listRecommendedFlows`

Returns markdown documentation with recommended integration flows.

**Returns:**
- **Single Product Checkout**: Basic payment flow
- **Cart Flow**: Multiple products with cart
- **Subscription Toggle**: Session-based access management
- **Feature Gating**: Check entitlements before access
- **Marketplace**: Receipt-based digital goods

Each flow includes:
- Use case description
- SDK code example
- React hooks example
- Component usage

**Example:**
```
AI: [Uses listRecommendedFlows tool]
    Returns comprehensive guide with 5 integration patterns and complete code examples
```

## Available Resources

### `payxor://admin/apps`

List all apps owned by the authenticated user.

### `payxor://admin/help`

Guide for admin operations, listing all available tools and their usage.

Note: Use the `list_apps`, `get_app`, `list_products`, and `get_stats` tools for dynamic data access.

## Available Prompts

Prompts are reusable templates that help users talk to models in a consistent way. They guide AI assistants through common workflows with structured instructions.

### `create_app`

Guides through creating a new PayXor application with proper configuration.

**Parameters:**
- `name` (string): Application name
- `payee` (string): Receiver wallet address for payments (0x...)
- `supportedNetworks` (number[]): Array of supported chain IDs
- `supportedStablecoins` (object): Chain ID → token addresses mapping
- `domain` (string, optional): Optional domain for the app
- `isTesting` (boolean, optional): Whether this is a testing app

**Example:**
```
User: [Uses create_app prompt with app details]
AI: Guides through app creation, shows appId after creation
```

### `setup_product`

Guides through creating a new product for an existing app.

**Parameters:**
- `appId` (string): App UUID
- `productName` (string): Product name
- `mode` (number): Payment mode (0=SESSION, 1=FEATURE, 2=RECEIPT, 3=PASS)
- `price` (string): Price in smallest unit
- `duration` (number, optional): Duration in seconds (for SESSION mode)
- `entitlementId` (string, optional): Custom entitlement ID

**Example:**
```
User: [Uses setup_product prompt with product details]
AI: Guides through product creation, shows productId after creation
```

### `view_analytics`

Guides through viewing analytics, revenue, and statistics for an app.

**Parameters:**
- `appId` (string): App UUID
- `productId` (string, optional): Filter stats by product ID

**Example:**
```
User: [Uses view_analytics prompt with appId]
AI: Retrieves and presents comprehensive statistics including revenue, conversion rates, and top payers
```

### `complete_app_setup`

Guides through the complete setup process: creating an app and then setting up multiple products.

**Parameters:**
- `appName` (string): Application name
- `payee` (string): Receiver wallet address
- `supportedNetworks` (number[]): Array of chain IDs
- `supportedStablecoins` (object): Chain ID → token addresses mapping
- `products` (array): Array of product objects with name, mode, price, etc.
- `domain` (string, optional): Optional domain
- `isTesting` (boolean, optional): Testing mode flag

**Example:**
```
User: [Uses complete_app_setup prompt with app config and products array]
AI: Creates app, then creates all products, provides summary with all IDs for integration
```

### `review_quotes`

Guides through reviewing payment quotes with optional filters.

**Parameters:**
- `appId` (string): App UUID
- `productId` (string, optional): Filter by product ID
- `status` (string, optional): Filter by status ("issued", "used", "expired")
- `chainId` (number, optional): Filter by chain ID
- `limit` (number, optional): Max results to return

**Example:**
```
User: [Uses review_quotes prompt with filters]
AI: Retrieves quotes matching filters, shows summary statistics and key information
```

## Example Usage (AI Conversation)

```
User: Create a new app called "My Game" on Base

AI: [Uses create_app tool]
    Created app "My Game":
    - App ID: 0x1234...
    - UUID: abc-def-123
    - Networks: Base (8453)
    - Status: Active

User: Add a premium subscription product for 5 USDC/month

AI: [Uses create_product tool]
    Created product "Premium Subscription":
    - Mode: SESSION
    - Price: 5000000 (5 USDC)
    - Duration: 2592000 seconds (30 days)
    - Product ID: 0xabcd...

User: How's the app performing?

AI: [Uses get_stats tool]
    Stats for "My Game":
    - Total Revenue: 150 USDC
    - Conversion Rate: 23%
    - Active Users: 45
    - Top Payer: 0x789... (25 USDC)

User: Show me how to use the DropdownBuyButton component

AI: [Uses getReactComponentUsage tool with name="DropdownBuyButton"]
    Returns component documentation with props table, basic usage, and customization examples

User: Generate a Next.js integration snippet for my product

AI: [Uses generateIntegrationSnippet tool with framework="nextjs-app-router", productId="0x...", appId="..."]
    Returns complete Next.js App Router integration code with wagmi setup and product-specific details
```

## Payment Modes

| Mode | Value | Description |
|------|-------|-------------|
| SESSION | 0 | Time-limited access (subscription) |
| FEATURE | 1 | Permanent feature unlock |
| RECEIPT | 2 | One-time payment proof |
| PASS | 3 | Access pass/membership |

## License

MIT