PayMCP: Monetize MCP Tools

You are an AI coding agent helping a developer add PayMCP monetization to an MCP server (TypeScript or Python).

When to use this skill

Use this skill when the user asks to:

• add pricing to MCP tools (pay-per-request),
• gate tools behind subscriptions,
• make an MCP server paid or monetized,
• configure PayMCP providers (traditional or X402),
• choose a coordination mode,
• troubleshoot PayMCP integration issues.

Guardrails (do this first)

1. Never ship payment credentials to end users. If the server runs in STDIO mode and would distribute secrets, stop and recommend a hosted deployment.
2. Prefer minimal diffs: integrate PayMCP without rewriting the server architecture.
3. Keep tool interfaces stable.
4. Use the project’s existing MCP framework and conventions.

High-level integration checklist

Step 1 — Identify environment

• Detect language: TypeScript/Node or Python.
• Detect MCP server library and how tools are registered.
• Confirm how the server is deployed and how env vars are provided.
• If the official MCP SDK is not installed yet, install it before proceeding.

Step 2 — Add PayMCP dependency

• Python: ensure paymcp is installed and imported.
• TypeScript: ensure paymcp is installed and imported.

Step 3 — Configure providers

Ask which provider(s) to use:

• Walleot (default recommendation if the user has no preference)
• Stripe, PayPal, etc. (if required)
• X402 (on-chain)

Rules:

• You can configure one provider or two providers.
• If two providers are configured, use X402 + one traditional provider.
• If X402 is used, the developer must provide a blockchain address to receive USDC.
• For traditional providers, require at least an API key; provider-specific settings may also be needed.

Step 4 — Choose coordination mode

• mode is optional. If omitted, PayMCP defaults to AUTO.
• AUTO detects client capabilities and selects the best compatible flow.

If the developer insists on another mode, list the available options and warn that deviating from AUTO is not recommended unless they understand client capabilities:

• AUTO, RESUBMIT, ELICITATION, TWO_STEP, X402, PROGRESS, DYNAMIC_TOOLS If the client setup is non-standard, read references/coordination-modes.md for compatibility details.

Step 5 — Add pay-per-request pricing or subscription gating to tools

Support both:

• Pay-per-request (price)
• Subscription gating (subscription / plan id)

Rules:

• Apply pricing only to the tool(s) the user wants to monetize.
• Keep free tools free; do not blanket-charge everything.
• Ensure the tool handler receives the required context/extra parameter as per the framework.
• Pay-per-request does not require user identity; subscription gating does.
• Subscriptions require stable user identity (auth). Without authentication, subscription checks are unreliable.
  • Minimum auth checklist: stable user ID + verifiable token (e.g., JWT/session).
  • Auth guidance: https://modelcontextprotocol.io/docs/tutorials/security/authorization

Step 6 — Test

• Add one small “test tool” that costs a tiny amount (e.g., $0.50 or $1.00) and verify the payment process.
• Confirm that a paid call succeeds after payment confirmation.
• Confirm that unpaid calls return the correct payment-required behavior.

Step 7 — Document

• Add short run instructions, required env vars, and the selected provider/mode rationale.

Concrete implementation playbooks

Playbook A — TypeScript MCP server (recommended path)

1. Install dependencies:
   • npm install paymcp (or your package manager)
   • Ensure zod exists if you use it for schemas.
2. Import PayMCP.

import { installPayMCP } from 'paymcp';
import { WalleotProvider } from 'paymcp/providers';

3. Install PayMCP after configuring MCP instance and configure providers with a list.

installPayMCP(mcp, { providers: [new WalleotProvider({ apiKey: "sk_test_..." })] });

4. Optionally set mode (default is AUTO if omitted).
5. Add tool pricing via tool metadata:
   • _meta: { price: { amount, currency } }
6. For subscriptions, add:
   • _meta: { subscription: { plan: "..." } }
   • Requires auth; pay-per-request does not.

Playbook B — Python FastMCP server

1. Install dependencies:
   • pip install paymcp
2. Import PayMCP

from paymcp import PayMCP, price #or from paymcp import PayMCP, subscription
from paymcp.providers import WalleotProvider

3. Install PayMCP after configuring MCP instance and configure providers with a list.

PayMCP(mcp, providers=[WalleotProvider(apiKey="sk_test_...")])

4. Optionally set mode (default is AUTO if omitted).
5. Apply @price(amount=..., currency="USD") to monetized tools.
6. For subscription gating, apply @subscription(plan="...").
   • Requires auth; pay-per-request does not.

Playbook C — X402 (on-chain)

Only do this when the user controls the MCP client or knows it supports x402-protocol.

• Configure X402 provider with a USDC receive address.
• Use mode: X402 only when the client is x402-capable.

References (load on demand)

• references/paymcp-cheatsheet.md — minimal code patterns for TS/Python, pricing/subscriptions, Redis state store.
• references/coordination-modes.md — how to choose mode (AUTO by default).
• references/providers.md — provider-specific configuration notes (Walleot/Stripe/PayPal/X402).
• references/custom-providers.md — custom provider examples (TypeScript/Python).
• references/state-store.md — RedisStateStore and durable state storage.
• references/troubleshooting.md — common errors and fixes.

Output requirements

When making changes, produce:

• a concise summary of what changed,
• the exact files changed,
• how to run/test locally,
• which provider(s) and mode were selected and why,
• any secrets/env vars required (names only; never print real secrets).