MCP Integration Guide

What is L402 and the Model Context Protocol?

The L402 API Micropayment standard combines HTTP 402 Payment Required status codes with Macaroons and Lightning Network Invoices. It enables machine-to-machine, stateless, and instantly settled API monetization.

The Model Context Protocol (MCP) standardizes how AI agents communicate with context servers. By gating an MCP server behind an L402 paywall, you can charge autonomous AI agents a per-tool-call fee in Bitcoin/sats.

When you combine MCP + L402 + WaaS, you get an intelligent, programmable economy where AI agents pay for context or instantly provision secure native lightning sub-wallets on-demand.

Prerequisites

Before building this integration, ensure your environment includes:

Alby Hub (Lightning node with NWC support)
Python 3.10+ (FastAPI, Uvicorn, httpx)
MacaroonBakery (for cryptographic token minting)

Step 1: Building the L402 Gated MCP Server POC

First, let's create a FastAPI server that acts as our Model Context Protocol endpoint, and secure the JSON-RPC interface with L402 atomic settlement.

from fastapi import FastAPI, Request, HTTPException, Header
import uvicorn
from l402_backend import generate_invoice, mint_macaroon, verify_l402_token

app = FastAPI(title="L402 Gated MCP Server")

@app.post("/mcp/v1/messages")
async def mcp_messages(request: Request, authorization: str = Header(None)):
    # 1. Atomic settlement for MCP tool calls
    amount_sats = 21  # Example pricing: 21 sats per MCP tool execution
    
    if not authorization or not verify_l402_token(authorization):
        invoice_data = await generate_invoice(amount_sats=amount_sats, memo="MCP Tool Call Settlement")
        macaroon_str = mint_macaroon(invoice_data["payment_hash"])
        invoice_str = invoice_data["payment_request"]
        
        raise HTTPException(
            status_code=402, 
            detail="Payment Required for MCP Tool",
            headers={"WWW-Authenticate": f'L402 macaroon="{macaroon_str}", invoice="{invoice_str}"'}
        )
    
    # 2. Process the MCP JSON-RPC tool call once paid
    payload = await request.json()
    
    return {
        "jsonrpc": "2.0",
        "id": payload.get("id"),
        "result": {
            "content": [{"type": "text", "text": "MCP Tool successfully executed with L402 atomic settlement."}]
        }
    }

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8002)
        

Step 2: WaaS Sub-Wallet Provisioning via MCP

Now that our MCP server is gated, AI agents can pay for API access. Next, let's look at what the AI agent is paying for.

Using WaaS (Wallet-as-a-Service), an AI agent can execute an MCP tool call to provision a brand-new Nostr Wallet Connect (NWC) sub-wallet instance for its end users on the fly.

To ensure revenue security, remember:

Macaroon Caveat Binding: Cryptographically bind the budget_sats (budget allocated to the new sub-wallet) directly into the generated Macaroon caveat at mint time.
Revenue Integrity: Increment global usage statistics ONLY after the WaaS provisioning call to Alby Hub succeeds, ensuring exceptions don't inflate usage metrics.

Example WaaS Provisioning Tool Execution Structure:

async def provision_waas_subwallet(budget_sats: int, name: str):
    """
    Called by the MCP execution handler when an AI requests a sub-wallet.
    """
    # Create the sub-wallet on the LDK node backend (e.g., Alby Hub)
    # The API call must ensure the wallet is strictly scoped using isolated credentials.
    nwc_uri = await create_alby_sub_wallet(budget_sats, name)
    
    # Safely update revenue stats
    update_stats(sats_earned=budget_sats) 
    
    return {"nwc_uri": nwc_uri, "budget": budget_sats}
        

Step 3: Automating Client Resolution

To connect an AI agent to the MCP endpoint, it must gracefully solve the 402 challenge.

A standard L402 Client intercepts the HTTP 402 Payment Required exception, parses the WWW-Authenticate header, extracts the lightning invoice, pays it via nostr-wallet-connect (NWC), and retries the original execution with the signed Macaroon.

Conclusion

Combining MCP with L402 and WaaS shifts AI-to-machine interactions from high-friction subscriptions into instant, low-latency, programmatic micropayments.

Start building your autonomous Machine-to-Machine economy today!

Back to WaaS Homepage