@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

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:

{
  "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:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["@payxor/mcp-admin"],
          "env": {
            "PAYXOR_API_KEY": "pxk_your-api-key"
          }
        }
      }
    ]
  }
}

Standalone

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
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