@mpp/mcp

Turn your MCP server tools into paid endpoints — in minutes, not days.

@mpp/mcp makes it trivial to add the Machine Payments Protocol (MPP) to any MCP server. Define your tools, set a price, and get paid — in stablecoins or fiat — without touching blockchain code.

Built with ❤️ by clei | MIT License

---

Why

Today, if you want to monetize an API or tool for AI agents, you need:

• An account system
• API keys
• Billing integration
• Webhook handlers for payment events

@mpp/mcp replaces all of that with a price config. Agents pay automatically, wallet-to-wallet, in a single HTTP request.

Install

npm install @mpp/mcp

# Peer dependencies:
npm install @modelcontextprotocol/sdk mppx zod

Quick Start

import { createMcpServer } from '@mpp/mcp'
import { z } from 'zod'

const server = createMcpServer({
  name: 'my-paid-tools',
  version: '1.0.0',
  methods: [{
    type: 'tempo',
    currency: 'usd',
    recipient: '0x742d35Cc6634c0532925a3b844bC9e7595F8fE00',
  }],
  tools: {
    translate: {
      description: 'Translate text between languages',
      inputSchema: z.object({
        text: z.string(),
        targetLang: z.string(),
      }),
      price: {
        intent: 'charge',  // 'charge' = per-call, 'session' = streaming
        amount: '1',       // $0.01
        currency: 'usd',
        method: 'tempo',   // or 'stripe' for card payments
      },
      async execute({ text, targetLang }) {
        // Your business logic here
        return { translated: `[${targetLang}] ${text}` }
      },
    },
  },
})

// Start with STDIO transport (works with Claude Desktop, Cursor, etc.)
server.start()

That's it. No payment middleware. No webhooks. No account setup.

---

How Payment Works

Agent → MCP Server:  tools/call { name: "translate", arguments: {...} }
MCP Server → Agent:  error -32042 Payment Required { challenges: [...] }
Agent → Blockchain:  pays the amount on Tempo
Agent → MCP Server:  tools/call { name: "translate", ..., _meta: { ...credential } }
MCP Server → Agent:  { content: { text: "..." } }  ✅

All automatic from the agent's perspective.

Payment Methods

Method	Description	Status
tempo	Stablecoin on Tempo blockchain (sub-second, <$0.01/tx)	✅ Testnet
stripe	Visa, Mastercard via Stripe Shared Payment Tokens	✅ Production

Two Intent Types

charge — Per-request payment

price: {
  intent: 'charge',
  amount: '10',   // $0.10 per call
  currency: 'usd',
  method: 'tempo',
}

session — Streaming payments

Open a payment channel once, make unlimited calls, settle on-chain:

price: {
  intent: 'session',
  setupAmount: '100',    // $1.00 to open session
  perCallAmount: '1',   // $0.01 per call
  maxTotal: '1000',     // Cap at $10.00
  currency: 'usd',
  method: 'tempo',
}

Full Example with Stripe

import { createMcpServer } from '@mpp/mcp'
import { stripeMethod } from '@mpp/mcp/methods/stripe'
import { z } from 'zod'

const server = createMcpServer({
  name: 'image-generator',
  version: '1.0.0',
  methods: [
    stripeMethod({
      currency: 'usd',
      stripeAccountId: 'acct_xxx',
    }),
  ],
  tools: {
    generate: {
      description: 'Generate an image from a text prompt',
      inputSchema: z.object({ prompt: z.string().max(500) }),
      price: {
        intent: 'charge',
        amount: '50',   // $0.50 per image
        currency: 'usd',
        method: 'stripe',
      },
      async execute({ prompt }) {
        // Call your image generation API
        return { imageUrl: 'https://example.com/img.png' }
      },
    },
  },
})

server.start()

API Reference

createMcpServer(config)

interface MppMcpServerConfig {
  name: string           // Server name
  version: string        // Semantic version
  methods: PaymentMethod[]     // Supported payment methods
  tools: Record<string, ToolDefinition>
  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent'
}

PaymentMethod

// Tempo (stablecoin — testnet ready)
{ type: 'tempo', currency: string, recipient: string }

// Stripe (card)
{ type: 'stripe', currency: string, stripeAccountId: string }

ToolDefinition

{
  description: string
  inputSchema: ZodSchema | JSONSchema
  price: {
    intent: 'charge' | 'session'
    amount: string     // Smallest unit (cents for USD)
    currency: string
    method: string
    perCallAmount?: string  // session only
    maxTotal?: string       // session only
  }
  execute: (args: unknown) => Promise<unknown>
}

MCP Transport

STDIO (recommended for local agents)

import { startStdioServer } from '@mpp/mcp/adapters/stdio'
await startStdioServer(server)

HTTP/SSE (remote agents)

// Coming soon

Architecture

@mpp/mcp
├── core/
│   ├── createServer.ts      # Server factory
│   ├── paidTool.ts           # Tool with payment enforcement
│   ├── challengeBuilder.ts    # -32042 challenge builder
│   ├── sessionManager.ts      # Session lifecycle
│   └── credentialVerifier.ts # On-chain verification
├── methods/
│   ├── tempo.ts               # Tempo blockchain method
│   └── stripe.ts             # Stripe card method
├── adapters/
│   └── stdio.ts              # STDIO transport
└── index.ts                  # Public exports

Resources

• MPP Documentation — Protocol specs and quickstart
• Tempo Docs — Blockchain docs
• MCP Protocol — MCP spec
• IETF Payment Auth — Core spec

Contributing

Contributions welcome! Please read the design doc first.

License

MIT © clei