Skip to main content
Glama
bitnovo

MCP Bitnovo Pay

Official
by bitnovo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

MCP Bitnovo Pay

License: MIT Node.js MCP

MCP server for Bitnovo Pay integration with AI agents

A Model Context Protocol (MCP) server that provides AI agents with cryptocurrency payment capabilities through Bitnovo Pay API integration. This server enables AI models to create payments, check payment status, manage QR codes, and access cryptocurrency catalogs.

🚀 Features

  • 8 MCP Tools for comprehensive payment management:

    • create_payment_onchain - Generate cryptocurrency addresses for direct payments

    • create_payment_link - Create web payment URLs with redirect handling

    • get_payment_status - Query payment status with detailed information

    • list_currencies_catalog - Get supported cryptocurrencies with filtering

    • generate_payment_qr - Generate custom QR codes from existing payments

    • get_webhook_events - Query webhook events received in real-time

    • get_webhook_url - Get public webhook URL with configuration instructions

    • get_tunnel_status - Diagnose tunnel connection status

  • Automatic Webhook System with 3 tunnel providers:

    • 🔗 ngrok: Free persistent URL (1 static domain per account)

    • 🌐 zrok: 100% free open-source with persistent URLs

    • 🏢 manual: For servers with public IP (N8N, Opal, VPS)

  • Multi-LLM Support - Compatible with:

    • 🤖 OpenAI ChatGPT (GPT-5, GPT-4o, Responses API, Agents SDK)

    • 🧠 Google Gemini (Gemini 2.5 Flash/Pro Sept 2025, CLI, FastMCP)

    • 🔮 Claude (Claude Desktop, Claude Code)

  • High-Quality QR Codes (v1.1.0+):

    • 📱 512px default resolution (up from 300px) for modern displays

    • 🖨️ Support up to 2000px for professional printing

    • ✨ Sharp edges with optimized interpolation algorithms

    • 🎨 Custom Bitnovo Pay branding with smooth logo scaling

  • Privacy by Default - Sensitive data masked in logs, minimal data exposure

  • Secure - HTTPS enforcement, HMAC signature validation, secure secret handling

  • Reliable - Built-in retry logic, timeout handling, stateless operation

Related MCP server: PayPls MCP Server

📋 Prerequisites

  • Node.js 18+

  • Bitnovo Pay Account with Device ID and optional Device Secret

  • Environment Configuration (see setup guides below)

⚡ Quick Start

1. Get Your Bitnovo Credentials

  1. Sign up at Bitnovo Pay

  2. Obtain your Device ID from the Bitnovo dashboard

  3. (Optional) Generate a Device Secret for webhook signature validation

2. Configure Your MCP Client

Add this configuration to your MCP client config file:

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

For OpenAI ChatGPT (see OpenAI Setup Guide):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

3. Restart Your MCP Client

Restart Claude Desktop, ChatGPT, or your MCP client to load the server.

4. Test the Integration

Ask your AI assistant: "Create a payment for 10 euros"

☁️ Cloud Deployment (NEW in v1.2.0)

MCP Bitnovo Pay now supports remote deployment on cloud platforms with HTTP transport mode. This enables AI platforms like claude.ai to connect to your MCP server remotely.

Deploy to Railway (Recommended)

Deploy on Railway

Quick Setup:

  1. Click "Deploy to Railway" or create a new project

  2. Set environment variables:

    • BITNOVO_DEVICE_ID - Your Bitnovo device ID

    • BITNOVO_BASE_URL - https://pos.bitnovo.com

  3. Deploy (Railway auto-detects Dockerfile)

  4. Get your public URL: https://your-app.up.railway.app

Connect to claude.ai:

  • Add server in Settings → Model Context Protocol

  • Server URL: https://your-app.up.railway.app/mcp

📖 Full Guide: See RAILWAY.md for detailed deployment instructions, troubleshooting, and configuration.

Deploy to Docker

# Build the image
docker build -t mcp-bitnovo-pay .

# Run with environment variables
docker run -d \
  -p 3000:3000 \
  -e PORT=3000 \
  -e BITNOVO_DEVICE_ID=your_device_id \
  -e BITNOVO_BASE_URL=https://pos.bitnovo.com \
  mcp-bitnovo-pay

Deploy to Other Platforms

The server works on any platform that supports Node.js and Docker:

  • Heroku: Push Dockerfile with environment variables

  • Fly.io: Deploy with fly.toml configuration

  • Google Cloud Run: Deploy Docker container

  • AWS ECS/Fargate: Deploy with task definition

Required Environment Variables:

  • PORT - HTTP port (auto-set by most platforms)

  • BITNOVO_DEVICE_ID - Your Bitnovo device ID

  • BITNOVO_BASE_URL - Bitnovo API URL

Transport Mode Detection:

  • If PORT env var is set → HTTP mode (remote connections)

  • If no PORT → stdio mode (local connections)

📦 Installation Options

Option A: Using npx (Recommended)

No installation required! The npx command automatically downloads and runs the latest version.

npx -y @bitnovopay/mcp-bitnovo-pay

Advantages:

  • ✅ Always get the latest version

  • ✅ No manual updates needed

  • ✅ No local installation required

  • ✅ Works immediately

Option B: Clone Repository (For Development)

For contributors or advanced users who need to modify the code:

# Clone the repository
git clone https://github.com/bitnovo/mcp-bitnovo-pay.git
cd mcp-bitnovo-pay

# Or install from npm
npm install -g @bitnovopay/mcp-bitnovo-pay

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
npm start

Advantages:

  • ✅ Full control of source code

  • ✅ Ability to modify and test changes

  • ✅ Ideal for contributing to the project

🔧 Configuration by LLM Platform

Choose your AI platform and follow the specific setup guide:

Claude Desktop (Anthropic)

Config File Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) Guide: Claude Setup Guide

Basic Configuration:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

With Webhooks (for real-time payment notifications):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com",
        "BITNOVO_DEVICE_SECRET": "your_device_secret_hex",
        "WEBHOOK_ENABLED": "true",
        "TUNNEL_ENABLED": "true",
        "TUNNEL_PROVIDER": "ngrok",
        "NGROK_AUTHTOKEN": "your_ngrok_token",
        "NGROK_DOMAIN": "your-domain.ngrok-free.app"
      }
    }
  }
}

OpenAI ChatGPT

Guide: OpenAI Setup Guide Supported: GPT-5, GPT-4o, Responses API, Agents SDK

Basic Configuration:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Google Gemini

Guide: Gemini Setup Guide Supported: Gemini 2.5 Flash/Pro (Sept 2025), CLI, FastMCP

Basic Configuration:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Environment Variables

Variable

Required

Description

Example

BITNOVO_DEVICE_ID

✅ Yes

Your Bitnovo Pay device identifier

12345678-abcd-1234-abcd-1234567890ab

BITNOVO_BASE_URL

✅ Yes

Bitnovo API endpoint

https://pos.bitnovo.com (production)https://payments.pre-bnvo.com (development)

BITNOVO_DEVICE_SECRET

⚠️ Optional

HMAC secret for webhook validation

your_hex_secret

WEBHOOK_ENABLED

⚠️ Optional

Enable webhook server

true or false

TUNNEL_ENABLED

⚠️ Optional

Auto-start tunnel for webhooks

true or false

TUNNEL_PROVIDER

⚠️ Optional

Tunnel provider

ngrok, zrok, or manual

Security Note: Never commit credentials to version control. Use environment variables or secure secret management.

🛠️ MCP Tools Reference

Payment Creation

create_payment_onchain

Creates a cryptocurrency payment with a specific address for direct transactions.

Use when: User specifies a cryptocurrency (Bitcoin, ETH, USDC, etc.)

{
  "amount_eur": 50.0,
  "input_currency": "BTC",
  "notes": "Coffee payment"
}

create_payment_link

Creates a web-based payment URL where customers can choose their cryptocurrency.

Use when: Generic payment request without specific crypto mentioned (DEFAULT OPTION)

{
  "amount_eur": 50.0,
  "url_ok": "https://mystore.com/success",
  "url_ko": "https://mystore.com/cancel",
  "notes": "Order #1234"
}

Payment Management

get_payment_status

Retrieves current payment status with detailed information.

{
  "identifier": "payment_id_here"
}

Status Codes:

  • NR (Not Ready): Pre-payment created, no crypto assigned

  • PE (Pending): Waiting for customer payment

  • AC (Awaiting Completion): Crypto detected in mempool

  • CO (Completed): Payment confirmed on blockchain

  • EX (Expired): Payment time limit exceeded

  • CA (Cancelled): Payment cancelled

  • FA (Failed): Transaction failed to confirm

list_currencies_catalog

Gets available cryptocurrencies with optional amount-based filtering.

{
  "filter_by_amount": 25.0
}

generate_payment_qr

Creates custom QR codes for existing payments with high-quality output.

{
  "identifier": "payment_id_here",
  "qr_type": "both",
  "size": 512,
  "style": "branded"
}

QR Types:

  • address: Crypto address only (customer enters amount manually)

  • payment_uri: Address + amount included (recommended)

  • both: Generate both types (recommended)

  • gateway_url: QR of payment gateway URL

QR Size Options (v1.1.0+):

  • Default: 512px (optimized for modern displays)

  • Range: 100px - 2000px

  • Recommended sizes:

    • 512px: Mobile and web displays

    • 800-1200px: Standard printing

    • 1600-2000px: High-quality printing (posters, stands)

Quality Improvements (v1.1.0):

  • ✨ Sharp edges with nearest kernel interpolation for QR patterns

  • 🎯 High-quality logo scaling with lanczos3 kernel

  • 📦 PNG compression level 6 with adaptive filtering

  • 🖼️ Default size increased from 300px to 512px for better clarity

Webhook Tools

get_webhook_events

Query webhook events received in real-time from Bitnovo Pay API.

Available when: WEBHOOK_ENABLED=true

{
  "identifier": "payment_id_here",
  "limit": 50,
  "validated_only": true
}

get_webhook_url

Get public webhook URL with configuration instructions for Bitnovo panel.

Available when: WEBHOOK_ENABLED=true

{
  "validate": true
}

get_tunnel_status

Diagnose tunnel connection status (ngrok, zrok, or manual).

Available when: WEBHOOK_ENABLED=true

{}

📚 Documentation

🏗️ Development

Available Scripts

npm run build        # Compile TypeScript to JavaScript
npm run dev          # Run development server with hot reload
npm start            # Start production server
npm test             # Run test suite
npm run test:watch   # Run tests in watch mode
npm run lint         # Run ESLint
npm run format       # Format code with Prettier

Architecture

┌─────────────────┐
│   MCP Tools     │ ← 8 tools: 5 payment + 3 webhook
│ (src/tools/)    │
├─────────────────┤
│   Services      │ ← Business logic: PaymentService, CurrencyService
│ (src/services/) │
├─────────────────┤
│   API Client    │ ← Bitnovo API integration with retry logic
│ (src/api/)      │
├─────────────────┤
│ Webhook Server  │ ← HTTP Express + Event Store + Tunnel Manager
│ (src/webhook-*) │
├─────────────────┤
│   Utilities     │ ← Logging, validation, error handling, crypto
│ (src/utils/)    │
└─────────────────┘

Dual-Server Architecture

The MCP server can run two servers simultaneously:

┌─────────────────────────────────────────────────────────┐
│             MCP Bitnovo Pay Server                      │
│                                                         │
│  ┌──────────────┐  ┌──────────────────┐ ┌────────────┐│
│  │ MCP Server   │  │ Webhook Server   │ │  Tunnel    ││
│  │ (stdio)      │  │ (HTTP :3000)     │ │  Manager   ││
│  └──────┬───────┘  └────────┬─────────┘ └──────┬─────┘│
│         │                   │                   │      │
│         │    Event Store    │     Public URL    │      │
│         │   (in-memory)     │   (ngrok/zrok)    │      │
│         └──────────┬────────┴──────────┬────────┘      │
└────────────────────┼───────────────────┼───────────────┘
                     │                   │
            ┌────────┴────────┐  ┌───────┴────────┐
            │                 │  │                │
       Claude Desktop   Bitnovo API    Tunnel Provider
       (MCP Tools)      (Webhooks)    (ngrok/zrok/manual)

🔒 Security

  • HTTPS Only - All API calls use HTTPS

  • HMAC Validation - Webhook signature verification with SHA-256

  • Replay Attack Prevention - Nonce caching with 5-minute TTL

  • Data Privacy - Sensitive information is masked in logs

  • No Rate Data - Exchange rates not exposed to prevent inaccuracies

  • Stateless Design - No local persistence, real-time API queries

  • Auto-reconnection - Exponential backoff up to 10 retries for tunnels

  • Health Monitoring - Connection verification every 60 seconds

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

📞 Support

🌟 Related

Available Tools

5 tools
create_payment_onchainA

🚨 CRITICAL RULE #1 - EXPIRATION: YOU MUST tell user payment expires in EXACTLY "expires_in_minutes" MINUTES. Convert "expires_at" (UTC) to user's LOCAL TIME ZONE and display in their language. Format: "expires in X minutes (on [date] at [time] [user's timezone])".

💰 CRITICAL RULE #2 - AMOUNT: YOU MUST show "expected_input_amount" with FULL PRECISION (all decimals). Example: "0.43515861 SOL" not "0.44 SOL". This is the EXACT amount customer must send.

🪙 RULE #3 - DISPLAY: Show users ONLY "original_symbol" (BTC, USDC, SOL) and "original_blockchain" (Bitcoin Network, Solana Test Network). NEVER mention internal codes.

🔗 CRITICAL RULE #4 - PAYMENT LINK: ALWAYS display "web_url" as "Enlace de pago:" or "Payment Link:" in user's language. This is the web gateway URL where customers can view and complete the payment.

🎯 WHEN TO USE: Only when user explicitly mentions a cryptocurrency (Bitcoin, BTC, Ethereum, ETH, USDC, Solana, SOL, etc.). Customer MUST pay with that exact crypto.

🌐 NETWORK SELECTION: If crypto has MULTIPLE networks (check network_groups), call list_currencies_catalog first, ASK USER which network. Pass cryptocurrency as "SYMBOL on NETWORK".

EXAMPLES: cryptocurrency="BTC", cryptocurrency="USDC on Ethereum Network", cryptocurrency="SOL on Solana Test Network".

ParametersJSON Schema
NameRequiredDescriptionDefault
amountYesPayment amount in the specified fiat currency (must be positive). This amount will be converted to cryptocurrency at current rates.
cryptocurrencyYesCryptocurrency with network (REQUIRED). Format: "SYMBOL on NETWORK" or just "SYMBOL" if only one network. Examples: "USDC on Ethereum Network", "USDC on Solana Test Network", "BTC" (if only one Bitcoin network exists). Use list_currencies_catalog to see available options. The customer MUST pay in this specific cryptocurrency.
fiatNoISO 4217 currency code (EUR, USD, GBP, etc.). IMPORTANT: Use the EXACT currency the user specified. If user says "100 euros" use EUR. If user says "100 dollars" use USD. Default: EUREUR
notesNoOptional payment description or reference
include_qrNoIf true, includes QR codes in the response (RECOMMENDED: always true for immediate use). If false, generate later with generate_payment_qr.

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so description bears full burden. It discloses critical rules (expiration display, amount precision, link display) and behavior (converts fiat to crypto). It lacks explicit mention of side effects or authentication needs, but overall is highly transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with numbered rules and clear sections, but somewhat verbose. The critical info (expiration, amount) is front-loaded. Every sentence serves a purpose, but some redundancy exists (e.g., repeating 'CRITICAL' multiple times).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 params, no output schema, and no annotations, the description covers all necessary context: parameter semantics, usage conditions, expected output (payment link), and interaction with sibling tool list_currencies_catalog. It leaves no key gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds significant value beyond schema: precision guidance for amount, network selection for cryptocurrency, exact fiat currency usage, and QR code recommendation. This ensures correct parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it creates on-chain payments for cryptocurrencies, distinguishes from siblings like create_payment_link by specifying when to use (only when crypto is mentioned), and provides specific examples like 'USDC on Ethereum Network'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'WHEN TO USE' and 'NETWORK SELECTION' sections guide the agent on criteria for invocation, when to call list_currencies_catalog, and how to ask the user for network preference, with actionable examples.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_payment_qrA

Generate QR codes for payment address and/or payment URI from an existing payment. USE THIS WHEN: User wants QR in different size/style than original, User wants only address QR or only payment URI QR (not both), User created payment without QR (include_qr=false) and now needs it, User wants QR for gateway URL (for redirect payments). EXAMPLES: "Generate bigger QR", "Create QR without branding", "I need QR of 500px", "Generate QR for the payment link"

ParametersJSON Schema
NameRequiredDescriptionDefault
identifierYesPayment identifier from create_payment response
qr_typeNoType of QR to generate: "address": Only crypto address (customer must enter amount manually), "payment_uri": Address + amount included (recommended for specific amounts), "both": Generate both types (recommended), "gateway_url": QR of the payment gateway URL (only for redirect payments)both
sizeNoQR code size in pixels. Recommended: 512 for mobile/desktop, 800-1200 for print, 1600-2000 for high-quality print
styleNoQR code style: "basic": Plain black and white QR, "branded": Includes cryptocurrency logo in center (more professional)branded
brandingNoInclude Bitnovo Pay branding at bottom of QR code
gateway_environmentNoEnvironment for gateway URL generation (auto-detected if not specified)

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It states 'generate' implying a creation action, but does not specify if the tool is read-only, has side effects, or requires specific authentication. Lacks behavioral traits like whether it modifies the payment or returns a file.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise: one sentence for purpose, then a structured 'USE THIS WHEN' list and examples. Front-loaded with purpose. Minor verbosity from examples, but they enhance clarity without being excessive.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should explain return format (e.g., image data, URL). It does not. Also missing error conditions or prerequisites. Complete for usage scenarios but incomplete for expected output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed parameter descriptions. The description adds no extra meaning beyond what the schema provides (e.g., no additional context for 'gateway_environment' when auto-detection happens). Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it generates QR codes for payment address/URI from an existing payment. Distinguishes itself from sibling tools (create_payment_link, create_payment_onchain, etc.) which focus on payment creation or status, not QR generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'USE THIS WHEN' section lists specific scenarios (different size/style, only address or URI, originally without QR, gateway URL) and provides example user requests. Effectively guides when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_payment_statusA

Query the current status and details of a payment by its unique identifier. USE THIS WHEN: User wants to check if a payment was completed, or get details about a previously created payment. RESULT: Payment status (PE=Pending, CO=Completed, EX=Expired, CA=Cancelled), amounts, and confirmation info. Status descriptions: PE (Pending): Waiting for customer to pay, CO (Completed): Payment confirmed on blockchain, EX (Expired): Payment time limit exceeded, CA (Cancelled): Payment was cancelled. EXAMPLES: "Check payment status", "Is payment abc-123 completed?", "Status of my payment". Note: Exchange rate is not included in response as it may not be accurate for non-EUR fiat currencies.

ParametersJSON Schema
NameRequiredDescriptionDefault
identifierYesUnique payment identifier returned from payment creation

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, but description details result status codes, amounts, confirmation info, and notes exclusion of exchange rate for non-EUR fiat.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Contains useful examples and status descriptions but could be more concise. Slightly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequately covers purpose, parameters, and result details including status codes. No output schema, but description provides sufficient context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single parameter is well-documented in schema; description adds no extra meaning. Baseline 3 for 100% coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it queries payment status and details by identifier, distinguishing from sibling creation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use (check payment status, get details). Missing when-not, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_currencies_catalogA

Get available cryptocurrencies with optional amount filtering. USE WHEN: (1) User asks which cryptos available, (2) BEFORE onchain payment if crypto has multiple networks (e.g., USDC). DISPLAY RULES: Show users "original_symbol" (BTC, USDC) and "original_blockchain" (Bitcoin Network, Ethereum Network). Use "input_currency_code" ONLY when calling create_payment_onchain - NEVER show it to users. NETWORK SELECTION: If multiple networks exist (shown in network_groups), ASK user which network. RESULT: List with min/max amounts, decimals, network info, features. EXAMPLES: "Which cryptos available?", "What currencies support 50 euros?"

ParametersJSON Schema
NameRequiredDescriptionDefault
filter_by_amountNoOptional EUR amount to filter currencies that support this payment amount. Use this if user asks "which cryptos accept 50 euros?" or similar.

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses result contents (min/max amounts, decimals, network info, features) and caveats about not showing input_currency_code to users. Lacks details on rate limits or performance, but adequate for a read-only listing tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Relatively long but well-structured with sections (USE WHEN, DISPLAY RULES, etc.). Purpose is front-loaded. Each sentence adds value. Slightly verbose but justified by the need for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given only one optional parameter and no output schema, the description covers all needed context: usage scenarios, display rules, result details, and network selection. Complete for a catalog listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with one parameter filter_by_amount described. Description adds context: 'Optional EUR amount to filter currencies that support this payment amount' and usage example. Adds value beyond the schema's own description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get available cryptocurrencies with optional amount filtering.' The verb 'Get' and resource 'available cryptocurrencies' are specific. It distinguishes from sibling tools like create_payment_onchain by specifying that 'input_currency_code' should only be used in that tool, not shown to users.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'USE WHEN' section lists two scenarios: when user asks which cryptos are available, and before onchain payment if crypto has multiple networks. Provides display rules and network selection guidance, making it clear when and how to use the tool vs alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv1.2.1
    • First observedcreate_payment_link
    • First observedcreate_payment_onchain
    • First observedgenerate_payment_qr
    • First observedget_payment_status
    • First observedlist_currencies_catalog
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 5 tools

Disambiguation5/5

Each tool targets a distinct action: creating payment links, creating onchain payments with specific crypto, generating QRs for existing payments, checking status, and listing currencies. No overlap.

Naming Consistency5/5

All tool names follow the verb_noun pattern in snake_case (create_payment_link, create_payment_onchain, generate_payment_qr, get_payment_status, list_currencies_catalog), making them predictable.

Tool Count5/5

Five tools cover essential payment operations: creation (generic and specific), QR generation, status checking, and currency catalog. This is well-scoped for the server's purpose.

Completeness4/5

The set covers creation, QR, status, and catalog. A minor gap is the lack of a dedicated cancel/refund tool, though status includes a cancelled state. Otherwise complete.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • P-Link-MCP

    paracetamol951
    A
    license
    B
    quality
    D
    maintenance
    Payment & Transaction Tools that allow AI agents to send, receive, and request payments
    11
    15 npm
    2
    Apache 2.0

  • PayPls MCP Server

    n8m8
    A
    license
    A
    quality
    D
    maintenance
    Enables AI agents to manage Bitcoin and USDC payments by checking balances, sending funds, and generating receive addresses through the PayPls platform. It facilitates secure financial automation with features like transaction tracking and configurable human approval limits.
    6
    MIT

  • Payoza MCP Server

    Payoza
    F
    license
    Not graded
    quality
    D
    maintenance
    Connects the Payoza crypto payments API to AI assistants, enabling users to manage transactions, subscriptions, and payment links across multiple blockchains. It provides a comprehensive suite of tools for handling checkout sessions, customers, and real-time revenue analytics through natural language commands.
    -

  • Bit2Me MCP Server

    bit2me-devs
    A
    license
    A
    quality
    A
    maintenance
    Enables AI assistants to interact with the Bit2Me cryptocurrency ecosystem, including real-time market data, wallet management, trading, and products like Earn and Loans.
    48
    283 npm
    5
    MIT