LiveAuth MCP Server

Model Context Protocol (MCP) server for LiveAuth authentication. Enables AI agents to authenticate using proof-of-work or Lightning Network payments.

⚡ One-Liner Demo

npx @liveauth-labs/mcp-server

That's it! Runs in demo mode (3 sats per verification). No API key needed.

Demo vs Production:

• Demo mode: Returns real Lightning invoice (paid by user's wallet) but simulates confirmation for testing
• Production: Real payment required, real JWT issued

⚡ Quick Start (5 Minutes)

Option 1: Demo Mode (No Config)

# Just run - no API key needed
npx @liveauth-labs/mcp-server

That's it! The server runs in demo mode with 3 sats per verification.

Note: Demo mode returns a real Lightning invoice (so you can see the actual payment flow), but confirmation is simulated for testing. For production, set LIVEAUTH_API_KEY.

Option 2: Production Mode

1. Get API keys at liveauth.app
2. Add to Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "liveauth": {
      "command": "npx",
      "args": ["-y", "@liveauth-labs/mcp-server"],
      "env": {
        "LIVEAUTH_API_KEY": "la_pk_xxx"
      }
    }
  }
}

3. Restart Claude - Done!

Option 3: CLI (Programmatic)

# Production
export LIVEAUTH_API_KEY=la_pk_xxx
npx @liveauth-labs/mcp-server

# Demo
npx @liveauth-labs/mcp-server

What is This?

This MCP server allows AI agents (Claude, GPT, AutoGPT, etc.) to:

• Start an MCP session and get a proof-of-work challenge
• Solve challenges to prove computational work
• Receive JWT tokens for authenticated API access
• Meter API usage with sats per call

Installation

npm install -g @liveauth-labs/mcp-server

Or use directly with npx:

npx @liveauth-labs/mcp-server

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "liveauth": {
      "command": "npx",
      "args": ["-y", "@liveauth-labs/mcp-server"],
      "env": {
        "LIVEAUTH_API_BASE": "https://api.liveauth.app",
        "LIVEAUTH_API_KEY": "your-project-public-key"
      }
    }
  }
}

Demo Mode: If you omit LIVEAUTH_API_KEY or set LIVEAUTH_DEMO=true, the server will use the free demo endpoint (3 sats per verification). This is useful for testing without an API key.

Other MCP Clients

The server communicates over stdio. Start it with:

liveauth-mcp

Available Tools

liveauth_mcp_start

Start a new LiveAuth MCP session. Returns a PoW challenge by default, or a Lightning invoice if forceLightning=true.

Parameters:

• forceLightning (boolean, optional): If true, request Lightning invoice instead of PoW challenge

Returns (PoW):

{
  "quoteId": "uuid-of-session",
  "powChallenge": {
    "projectId": "guid",
    "projectPublicKey": "la_pk_...",
    "challengeHex": "a1b2c3...",
    "targetHex": "0000ffff...",
    "difficultyBits": 18,
    "expiresAtUnix": 1234567890,
    "signature": "sig..."
  },
  "invoice": null
}

Returns (Lightning):

{
  "quoteId": "uuid-of-session",
  "powChallenge": null,
  "invoice": {
    "bolt11": "lnbc...",
    "amountSats": 50,
    "expiresAtUnix": 1234567890,
    "paymentHash": "abc123..."
  }
}

liveauth_mcp_confirm

Submit the solved proof-of-work challenge to receive a JWT authentication token.

Parameters:

• quoteId (string): The quoteId from the start response
• challengeHex (string): The challenge hex from the start response
• nonce (number): The nonce that solves the PoW challenge
• hashHex (string): The resulting hash (sha256 of projectPublicKey:challengeHex:nonce)
• expiresAtUnix (number): Expiration timestamp from the challenge
• difficultyBits (number): Difficulty bits from the challenge
• signature (string): Signature from the challenge

Returns:

{
  "jwt": "eyJhbGc...",
  "expiresIn": 600,
  "remainingBudgetSats": 10000,
  "refreshToken": "abc123def456..."
}

Note: Save the refreshToken! Use liveauth_mcp_refresh to get a new JWT without re-authenticating.

liveauth_mcp_charge

Meter API usage after making an authenticated call. Call this with the cost in sats for each API request.

Parameters:

• callCostSats (number): Cost of the API call in sats

Returns:

{
  "status": "ok",
  "callsUsed": 5,
  "satsUsed": 15
}

If budget is exceeded:

{
  "status": "deny",
  "callsUsed": 100,
  "satsUsed": 1000
}

liveauth_mcp_status

Check the status of an MCP session. Use to poll for Lightning payment confirmation.

Parameters:

• quoteId (string): The quoteId from the start response

Returns:

{
  "quoteId": "uuid-of-session",
  "status": "pending",
  "paymentStatus": "pending",
  "expiresAt": "2026-02-17T12:00:00Z"
}

When paymentStatus is "paid", the session is confirmed. Call liveauth_mcp_confirm again to get the JWT.

liveauth_mcp_lnurl

Get the Lightning invoice for a session (lnget-compatible). Use this to retrieve the BOLT11 invoice for payment with any Lightning wallet.

Parameters:

• quoteId (string): The quoteId from the start response

Returns:

{
  "pr": "lnbc2100n1...",
  "routes": []
}

Note: This is compatible with lnget and other Lightning payment tools. Use this to poll for the invoice when liveauth_mcp_confirm returns "payment pending".

liveauth_mcp_usage

Query current usage and remaining budget without making a charge. Use this to check status before making API calls.

Parameters: (none required)

Returns:

{
  "status": "active",
  "callsUsed": 5,
  "satsUsed": 15,
  "maxSatsPerDay": 10000,
  "remainingBudgetSats": 9985,
  "maxCallsPerMinute": 60,
  "expiresAt": "2026-02-17T12:00:00Z",
  "dayWindowStart": "2026-02-17T00:00:00Z"
}

liveauth_mcp_refresh

Refresh the JWT token without re-authenticating. Use the refreshToken returned from confirm to get a new JWT when the current one expires.

Parameters:

• refreshToken (string): The refreshToken from the confirm response

Returns:

{
  "jwt": "eyJhbGc...",
  "expiresIn": 600,
  "remainingBudgetSats": 9985
}

Note: Save the refreshToken securely. You'll need it to extend the session without solving a new PoW or making another Lightning payment.

Usage Example

PoW Authentication

1. Call liveauth_mcp_start to get a PoW challenge and quoteId
2. Solve the PoW challenge:
   • Compute hash = sha256(projectPublicKey:challengeHex:nonce)
   • Find a nonce where hash < targetHex
3. Call liveauth_mcp_confirm with the solution to receive a JWT
4. Use the JWT in Authorization: Bearer <token> header for API requests
5. After each API call, call liveauth_mcp_charge with the call cost in sats

Lightning Authentication

1. Call liveauth_mcp_start with forceLightning: true to get a Lightning invoice
2. Use liveauth_mcp_lnurl (or poll liveauth_mcp_status) to get the BOLT11 invoice
3. Pay the invoice using your Lightning node/wallet
4. Poll liveauth_mcp_status with the quoteId until paymentStatus is "paid"
5. Call liveauth_mcp_confirm with just the quoteId to receive the JWT
6. Use the JWT and call liveauth_mcp_charge as above

Authentication Flow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  AI Agent       │────▶│  MCP Server     │────▶│  LiveAuth API   │
│                 │     │                 │     │                 │
│ 1. Start       │     │ /api/mcp/start  │     │ Returns PoW    │
│ 2. Solve PoW   │     │                 │     │ challenge       │
│ 3. Confirm     │     │ /api/mcp/confirm│     │ Returns JWT    │
│ 4. API calls   │     │                 │     │                 │
│ 5. Charge      │     │ /api/mcp/charge │     │ Meter usage    │
└─────────────────┘     └─────────────────┘     └─────────────────┘

## x402 Compatibility

LiveAuth supports the x402 standard (Cloudflare/Coinbase). Use either format:

```bash
# L402 (LiveAuth native)
curl -H "Authorization: L402 l402_xxx" https://api.liveauth.app/api/mcp/start

# x402 (Cloudflare/Coinbase compatible)
curl -H "Authorization: x402 preimage_xxx" https://api.liveauth.app/api/mcp/start

The API accepts both and returns WWW-Authenticate: x402 in 402 responses.

Why LiveAuth?

For API Providers:

• Protect endpoints from abuse without CAPTCHA
• Monetize AI agent access with micropayments
• No user friction (agents handle authentication)

For AI Agents:

• Permissionless access (no account signup)
• Cryptographically proven authentication
• Pay with compute (PoW) or sats

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js

Resources

• LiveAuth Demo & Docs
• MCP Protocol Spec
• GitHub Repository

License

MIT