# 402MCP.org — HTTP 402 & Agent Payment Registry

402MCP.org — HTTP 402 & Agent Payment Registry is an MCP server for Claude Code that decodes HTTP 402 responses and tells an agent how to pay and retry.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI
- Author: 402MCP
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/402MCP/402mcp
- Updated: 2026-10-18
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/402mcporg-http-402-agent-payment-registry

## What it does

The `decode_402_challenge` tool parses a 402 response — an L402 macaroon with its BOLT 11 invoice, x402 v1 or v2, or MPP — and returns the exact next steps plus the retry header. A separate `recommend_payment_rail` tool filters rails by role, asset, custody model, infrastructure, network, scheme and maturity, letting you re-weight the criteria. The `probe_402_support` tool sends a single GET to a public URL to check for 402 support and never moves money.

Every field in a 402 response is treated as server-controlled: the decoder lists them separately instead of running their text as instructions, and flags expired challenges or macaroons whose payment hash doesn't match the invoice. The probe rejects private, loopback and link-local addresses and non-standard ports, and the hosted endpoint rate-limits probe calls per client.

Recommendations draw on a registry where each entry carries a score from 1 to 10 across six criteria, with sources listed for verification. Running the server locally over stdio needs the `@402mcp/mcp` package, launched through `npx`.

## Requirements
- Needs: Node.js (commands run via npx)
- Remote server: `https://402mcp.org/api/v1/mcp`
- Environment variables: `MCP_402_OFFLINE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http registry https://402mcp.org/api/v1/mcp
```

2. **Platform CLI**
```bash
claude mcp add --env MCP_402_OFFLINE=<MCP_402_OFFLINE> --transport stdio 402mcporg-http-402-agent-payment-registry -- npx -y @402mcp/mcp
```
Replace <…> with your own values

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add 402mcporg-http-402-agent-payment-registry --url https://402mcp.org/api/v1/mcp
```

2. **Platform CLI**
```bash
codex mcp add 402mcporg-http-402-agent-payment-registry --env MCP_402_OFFLINE=<MCP_402_OFFLINE> -- npx -y @402mcp/mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "402mcporg-http-402-agent-payment-registry": {
            "url": "https://402mcp.org/api/v1/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "402mcporg-http-402-agent-payment-registry": {
            "command": "npx",
            "args": [
                "-y",
                "@402mcp/mcp"
            ],
            "env": {
                "MCP_402_OFFLINE": "<MCP_402_OFFLINE>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "402mcporg-http-402-agent-payment-registry": {
            "type": "http",
            "url": "https://402mcp.org/api/v1/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "402mcporg-http-402-agent-payment-registry": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@402mcp/mcp"
            ],
            "env": {
                "MCP_402_OFFLINE": "<MCP_402_OFFLINE>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http 402mcporg-http-402-agent-payment-registry https://402mcp.org/api/v1/mcp
```

2. **Platform CLI**
```bash
gemini mcp add -e MCP_402_OFFLINE=<MCP_402_OFFLINE> 402mcporg-http-402-agent-payment-registry npx -y @402mcp/mcp
```
Replace <…> with your own values

## When to use it
- parse a `402 Payment Required` response using L402, x402 or MPP
- pick a payment rail by role, asset and custody requirements
- check whether a given URL supports HTTP 402 payments without sending money
- look up the wire format for L402, x402 or MPP
- browse an open registry of agent payment solutions

## Example prompts
- Decode this 402 response and tell me how to pay and retry
- Recommend a payment rail with non-custodial storage and x402 support
- Check if this URL supports the 402 payment scheme, without paying anything

## Similar
- [okx-agent-payments-protocol](https://affpapa.org/en/nevibecode/skills/okx-agent-payments-protocol.md) — skill · 16200 installs
- [Lightning Enable MCP Server](https://affpapa.org/en/nevibecode/mcp/lightning-enable-mcp-server.md) — MCP server · ★ 9 repo stars
- [402-mcp](https://affpapa.org/en/nevibecode/mcp/402-mcp.md) — MCP server
- [🚀 P-Link - Collect/Send/Receive payments](https://affpapa.org/en/nevibecode/mcp/p-link-collectsendreceive-payments.md) — MCP server · 828 installs
- [Skavio USDC Payment Verification & Proof MCP](https://affpapa.org/en/nevibecode/mcp/skavio-usdc-payment-verification-proof-mcp.md) — MCP server
- [payment-testing](https://affpapa.org/en/nevibecode/skills/payment-testing.md) — skill · 1300 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
