Skip to content
Skills Library
Programming · Building & coding

mpp-server-middleware

/mpp-server-middleware

Implement MPP server-side middleware for Hono, Express, Next.js, and Elysia. Use when protecting API routes with HTTP 402 payment gates, configuring payment methods, or setting up the Mppx server instance.

Licence
MIT
Last repository change
14.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 14.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Implement MPP server-side middleware for Hono, Express, Next.js, and Elysia. Use when protecting API routes with HTTP 402 payment gates, configuring payment methods, or setting up the Mppx server instance.

Original author description

Implement MPP server-side middleware for Hono, Express, Next.js, and Elysia. Use when protecting API routes with HTTP 402 payment gates, configuring payment methods, or setting up the Mppx server instance.

How it works

  1. Before writing code
  2. Conceptual Architecture
Original SKILL.md headings · 104 lines, 554 words
SKILL.md preview
---
name: mpp-server-middleware
description: Implement MPP server-side middleware for Hono, Express, Next.js, and Elysia. Use when protecting API routes with HTTP 402 payment gates, configuring payment methods, or setting up the Mppx server instance.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# MPP Server Middleware

## Before writing code

**Fetch live docs**:
1. Fetch `https://www.npmjs.com/package/mppx` for the current server middleware API and configuration options
2. Web-search `mppx server middleware hono express next.js elysia` for framework-specific integration patterns
3. Web-search `site:github.com stripe-samples machine-payments server` for official server sample code
4. Fetch `https://docs.stripe.com/payments/machine/mpp` for Stripe-side server configuration

## Conceptual Architecture

### What the Server Middleware Does

The `mppx` server middleware intercepts requests to protected routes and implements the full HTTP 402 challenge-response flow:

1. **Intercept** — Middleware runs before your route handler
2. **Challenge** — If no `Authorization: Payment` header, returns `402` with `WWW-Authenticate: Payment` challenge
3. **Verify** — If credential present, validates proof of payment (on-chain verification, SPT validation, etc.)
4. **Pass-through** — On successful verification, calls the next handler
5. **Receipt** — Adds `Payment-Receipt` header to the response

### Mppx.create() Configuration

The central factory creates the server instance:

```typescript
const mppx = Mppx.create({
  secretKey: process.env.MPP_SECRET_KEY,  // 32-byte hex for HMAC challenge binding
  methods: [/* payment method configurations */],
});
```

The `secretKey` is critical — it binds challenges to prevent forgery and replay attacks.

### Supported Frameworks

| Framework | Middleware Pattern | Notes |
|-----------|-------------------|-------|
| **Hono** | `app.get('/path', mppx.charge(...), handler)` | Native middleware chaining |
| **Express** | `app.get('/path', mppx.charge(...), handler)` | Standard Express middleware |
| **Next.js** | Route handler wrapping | App Router and Pages Router |
| **Elysia** | Plugin-style integration | Bun-native framework |

### Route Protection

Two middleware functions match the two payment intents:

- **`mppx.charge({ amount })`** — Per-request payment gate (charge intent)
- **`mppx.session({ maxAmount })`** — Session-based streaming payment gate (session intent)

### Amount Specification

- Amounts are strings representing the smallest currency unit
- For USDC: `'100'` = $0.01 (USDC has 6 decimals, so 100 = 0.000100, but convention varies by method)
- For Stripe: follows Stripe's minor-unit convention (cents)
- Always verify exact amount semantics in the SDK docs for your payment method

### Multiple Payment Methods

A single server can accept multiple payment methods simultaneously:

```typescript
const mppx = Mppx.create({
  secretKey: process.env.MPP_SECRET_KEY,
  methods: [
    tempo.charge({ /* Tempo config */ }),
    stripe.charge({ /* Stripe config */ }),
  ],
});
```

The client selects which method to use when fulfilling the challenge.

### Dynamic Pricing

For routes where the price depends on the request:

- Use a pricing function that receives the request and returns the amount
- Implement custom middleware that computes the price and passes it to `mppx.charge()`

### Error Responses

The middleware returns RFC 9457 Problem Details on payment errors:

| Status | Type | When |
|--------|------|------|
| 402 | `payment-required` | No credential provided |
| 402 | `verification-failed` | Invalid proof of payment |
| 402 | `payment-expired` | Challenge or credential expired |
| 402 | `malformed-credential` | Unparseable credential |

### Best Practices

- Always use environment variables for `secretKey`, never hardcode
- Set appropriate challenge expiration times (not too short for UX, not too long for security)
- Log payment verification results (without sensitive data) for debugging
- Implement health check endpoints outside the payment middleware
- Use HTTPS in production (TLS 1.2+ required by spec)
- Add CORS headers if the API is consumed from browsers

Fetch the latest mppx package README for exact middleware API signatures, configuration options, and framework-specific examples before implementing.

Versions

The database has no other skills named mpp-server-middleware.

Database snapshot: 13.11.2026 · package version 25215e942d8a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100mpp-setup
    Scaffold an MPP project — install mppx SDK, configure payment methods, set up server middleware, and create a basic paid API endpoint. Use when starting a new MPP machine payments project from scratch.
  • 100mpp-client-fetch
    Implement MPP client-side payment handling with mppx.fetch(). Use when building AI agents or automated clients that consume 402-protected APIs, handling the transparent challenge-response payment flow.
  • 100mpp
    Build with MPP (Machine Payments Protocol), open machine-to-machine payments over HTTP 402. Use for paid APIs, payment-gated endpoints, agent payment flows, MCP tool payments, or metered billing. Covers mppx (TS), pympp, and mpp Rust SDKs.
  • 100mppx
    TypeScript SDK for the Payment HTTP Authentication Scheme. Handles 402 Payment Required flows with Tempo, Stripe, and other payment methods. Use when integrating payments or mppx into a client or server application.
  • 100x402-payments
    Build applications using the x402 protocol — Coinbase's open standard for HTTP-native stablecoin payments using the HTTP 402 status code. Use this skill when: - Creating APIs that require USDC payments per request (seller/server side) - Building clients or AI agents that pay for…
  • 100hono-guide
    Use when editing or scaffolding Hono 4.0+ API servers in TypeScript. Triggers on `.ts` files with `hono` or `@hono/*` imports, route handlers, middleware, and prompts about validation, error handling, WebSockets, CORS, or building an HTTP API in Hono, even when the user doesn't say 'Hono'.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.