OpenBolt — L402 MCP Ecosystem

Built by Jeff Skafi · GitHub · LinkedIn

A decentralized, peer-to-peer Machine-to-Machine (M2M) payment ecosystem. It consists of:

1. Agent Directory — A Next.js web app + Supabase database acting as a registry for AI agents to advertise their endpoints and Lightning addresses.
2. MCP Payment Interceptor — A Python MCP server plugin that handles sub-second HTTP 402 Lightning payments using the L402 standard via the Alby API.
3. Dummy Agent — A local test agent for end-to-end verification.

Repository Structure

OpenBolt/
├── directory/           Next.js Agent Directory (TypeScript, Tailwind, Supabase)
├── mcp-server/          Python MCP Payment Interceptor (FastMCP, httpx, Alby)
└── dummy-agent/         FastAPI test agent returning L402 challenges

---

Part A: Agent Directory

Prerequisites

• Node.js 18+
• A Supabase project (free tier works)

Setup

cd directory
cp .env.local.example .env.local
# Edit .env.local with your Supabase credentials
npm install
npm run dev

Database Setup

Run the migration against your Supabase project. You can paste the SQL from directory/supabase/migrations/001_create_agents.sql into the Supabase SQL Editor, or use the Supabase CLI:

supabase db push

API Endpoints

Register an agent:

curl -X POST http://localhost:3000/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weather Agent",
    "description": "Returns weather data for any city",
    "endpoint_url": "http://localhost:8402/weather",
    "price_sats": 100,
    "lightning_address": "agent@getalby.com",
    "mcp_schema": {"city": "string"}
  }'

Discover agents:

curl "http://localhost:3000/api/discover?q=weather"

---

Part B: MCP Payment Interceptor

Prerequisites

• Python 3.11+
• An Alby account with API access token (payments:send scope)

Setup

cd mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

cp .env.example .env
# Edit .env with your Alby access token

MCP Tools

Tool	Description
fetch_paid_api	Fetch data from an L402-gated API. Automatically pays Lightning invoices and retries with proof.
discover_agents	Search the OpenBolt directory for registered agents.

Claude Desktop Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "l402-payment": {
      "command": "/path/to/mcp-server/.venv/bin/python",
      "args": ["-m", "l402_mcp"],
      "cwd": "/path/to/mcp-server/src",
      "env": {
        "ALBY_ACCESS_TOKEN": "your-alby-token"
      }
    }
  }
}

---

Part C: End-to-End Test with Dummy Agent

The dummy agent simulates an L402-gated weather API. It uses a known test preimage so you can test the full flow without real Lightning payments.

Run the dummy agent

cd dummy-agent
# Using the same venv as the MCP server (has fastapi + uvicorn)
source ../mcp-server/.venv/bin/activate
python server.py

The agent starts on port 8402.

Test the L402 flow manually

# Step 1: Hit the endpoint — get a 402
curl -s -w "\nHTTP %{http_code}\n" http://localhost:8402/weather -X POST

# Step 2: Check the test credentials
curl -s http://localhost:8402/info | python -m json.tool

# Step 3: Authenticated request with the test preimage
curl -s http://localhost:8402/weather -X POST \
  -H 'Authorization: L402 dGVzdC1tYWNhcm9vbi1mb3ItbG9jYWwtZGV2:0000000000000000000000000000000000000000000000000000000000000000'

Test via Claude Desktop

1. Start the dummy agent (python dummy-agent/server.py).
2. Start the directory (cd directory && npm run dev).
3. Configure Claude Desktop with the MCP server (see above).
4. Prompt Claude: "Use fetch_paid_api to get weather data from http://localhost:8402/weather with params {}"

Claude will hit the API, encounter the 402, pay the invoice (via Alby in production, or using the test preimage locally), and return the weather data.

---

L402 Protocol Flow

Agent A (LLM)          MCP Server              Agent B (API)           Alby
     |                      |                       |                    |
     |-- fetch_paid_api --->|                       |                    |
     |                      |-- POST /weather ----->|                    |
     |                      |<-- 402 + L402 --------|                    |
     |                      |                       |                    |
     |                      |-- POST /payments/bolt11 ----------------->|
     |                      |<-- { payment_preimage } ------------------|
     |                      |                       |                    |
     |                      |-- POST /weather ----->|                    |
     |                      |   Authorization:      |                    |
     |                      |   L402 mac:preimage   |                    |
     |                      |<-- 200 + JSON --------|                    |
     |<-- weather data -----|                       |                    |

License

MIT