PA
Finance

PayMCP: Python & TypeScript Payments for MCP Server

Monetize MCP server endpoints with a lightweight Python & TypeScript payments layer using a two-line decorator; PyPI and npm packages available.

View on GitHub
Quick Install
npx -y @blustAI/paymcp

Overview

PayMCP provides a lightweight payments layer for Model Context Protocol (MCP) servers, implemented for both Python and TypeScript. It lets you monetize MCP endpoints with minimal code changes: add a two-line decorator or wrapper to an existing endpoint and the library handles payment validation and enforcement before your handler runs. This makes it easy to add pay-per-call or metered usage semantics to LLM apps, model gateways, and AI tooling that expose MCP-compatible endpoints.

Designed for developers who want a low-friction integration, PayMCP abstracts the common tasks around verifying payment tokens, enforcing price rules, and returning standard error responses for unpaid calls. PyPI and npm packages are available so you can pick the runtime that matches your MCP server stack and get running in minutes.

Features

  • Two-line decorator/wrapper to protect MCP endpoints
  • Implementations for Python and TypeScript (Node)
  • Simple configuration via environment variables or an init call
  • Hooks for payment providers and custom validators
  • Lightweight: minimal dependencies, fits into existing MCP server handlers
  • Standardized error responses for unpaid or insufficient-payment requests
  • PyPI and npm packages for easy installation

Installation / Configuration

Install the packages from PyPI or npm:

Python:

pip install paymcp

TypeScript / Node:

npm install paymcp
# or
yarn add paymcp

Basic configuration can be done with environment variables or an explicit init call. The library expects a payment provider key and an optional provider type (examples: “stripe” — your provider integration depends on your deployment).

Example environment variables:

export PAYMCP_PROVIDER=stripe
export PAYMCP_PROVIDER_KEY=sk_test_xxx
export PAYMCP_DEFAULT_CURRENCY=USD

Or initialize in code:

Python:

import paymcp

paymcp.configure(provider="stripe", provider_key="sk_test_xxx", default_currency="USD")

TypeScript:

import { configure } from "paymcp";

configure({ provider: "stripe", providerKey: process.env.PAYMCP_PROVIDER_KEY, defaultCurrency: "USD" });

Note: Payment provider integrations (webhooks, token verification) require additional provider-side setup (for example, registering webhook endpoints for Stripe). PayMCP exposes hooks to plug your provider-specific verification logic.

Usage examples

The integration is intentionally minimal — just an import and a decorator (two lines):

Python (MCP handler):

from paymcp import require_payment  # 1st line: import
@require_payment(amount_cents=100)   # 2nd line: decorator
def my_mcp_endpoint(request, context):
    # your existing MCP handler code
    return {"result": "ok"}

TypeScript (MCP handler wrapper):

import { requirePayment } from "paymcp"; // 1st line: import

export const myMcpEndpoint = requirePayment({ amountCents: 100 }, async (req) => {
  // your existing MCP handler code
  return { result: "ok" };
});

What the decorator/wrapper does:

  • Verifies the presence of a payment token or proof in the request (headers, metadata, or body)
  • Validates payment/credit with the configured provider or internal ledger
  • If payment is valid, invokes your handler; otherwise returns a standardized MCP error

Available Resources

  • GitHub repository: https://github.com/blustAI/paymcp
  • PyPI package: https://pypi.org/project/paymcp
  • npm package: https://www.npmjs.com/package/paymcp
  • Example integrations and provider adapters are available in the repo (see the examples/ directory)

Use Cases

  • Pay-per-call AI assistant: charge a small fee per assistant response or per token of output.
  • Metered API gateway: gate heavy or expensive model calls behind microtransactions or credit balance checks.
  • Premium features: enable premium endpoints (higher-quality models, larger context) only for paying users.
  • Data download or model access: require payment before returning downloadable datasets or gated model files.
  • Developer marketplaces: allow third-party developers to publish paid MCP endpoints and let PayMCP validate purchases.

Concrete example — pay-per-call assistant (Python):

  1. Add the require_payment decorator with the desired price.
  2. Configure provider keys via environment variables.
  3. When a client calls your MCP endpoint, include the payment token (e.g., a transaction id) in request metadata.
  4. The decorator validates the token; on success your handler returns content, otherwise the client receives a 402-style MCP error.

Comparison: Python vs TypeScript

Tags:finance