npm package: @leigents/mcp
Description: Turn your MCP server tools into paid endpoints using the Machine Payments Protocol
Author: clei
Latest version: 0.1.0

# @mpp/mcp

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

[![npm version](https://img.shields.io/npm/v/@mpp/mcp)](https://www.npmjs.com/package/@mpp/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Testnet Status](https://img.shields.io/badge/testnet-tempo%20testnet-orange)](https://docs.tempo.xyz)

`@mpp/mcp` makes it trivial to add the [Machine Payments Protocol (MPP)](https://mpp.dev) 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](https://github.com/leigents) | [MIT License](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

```bash
npm install @mpp/mcp

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

## Quick Start

```typescript
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
```typescript
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:
```typescript
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

```typescript
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)`

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

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

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

### ToolDefinition

```typescript
{
  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)
```typescript
import { startStdioServer } from '@mpp/mcp/adapters/stdio'
await startStdioServer(server)
```

### HTTP/SSE (remote agents)
```typescript
// 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](https://mpp.dev) — Protocol specs and quickstart
- [Tempo Docs](https://docs.tempo.xyz) — Blockchain docs
- [MCP Protocol](https://modelcontextprotocol.com) — MCP spec
- [IETF Payment Auth](https://paymentauth.org) — Core spec

## Contributing

Contributions welcome! Please read the [design doc](DESIGN.md) first.

## License

MIT © clei