LiveAuth MCP Server

> Authentication, pay-per-call metering, and signed receipts for AI agents and MCP tools: Bitcoin-native, Lightning-backed, and L402 compatible.

This MCP server lets any AI agent authenticate against your API using proof-of-work (free, no account) or Lightning Network micropayments (sats), then meter and monetize subsequent tool calls with per-call pricing, idempotent revenue events, and HMAC-signed receipts that auditors can verify offline.

Use it when you want to:

• Gate an API or MCP tool behind real cost-of-compute or real sats (anti-spam by design, not by CAPTCHA).
• Charge AI agents per call without signing them up for an account.
• Issue a tamper-evident audit trail (signed `mcp-call-receipt-v1`) for every paid tool invocation.
• Offer Lightning-backed L402 bundle access for prepaid MCP sessions.

Try it in 5 seconds — no account, no API key:

npx @liveauth-labs/mcp-server

Without configuration, the server uses LiveAuth's anonymous demo project and the real PoW flow. Add `LIVEAUTH_API_KEY` only when you need a specific project's policy, pricing, or attribution.

Available Tools (Glama / MCP auto-discovered)

Full parameter and response schemas are in the Tool Reference below.

5-Minute Quick Start

Option 1 — Credential-free PoW (no account, no key, no wallet)

npx @liveauth-labs/mcp-server

In an MCP client, call `liveauth_mcp_start`, then call `liveauth_mcp_confirm` with only the returned `quoteId`. The package reuses its existing PoW solver locally and the LiveAuth API verifies the signed challenge before issuing a short-lived session JWT.

Option 2 — Production Mode

1. Grab an API key at liveauth.app.

2. Add to Claude Desktop's `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": "la_pk_your_public_key"
      }
    }
  }
}

3. Restart Claude. Done.

Option 3 — Programmatic (CLI / SDK)

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

The package is also a TypeScript SDK — see SDK Usage below. The CLI bin is `liveauth-mcp`.

Why LiveAuth?

For API providers / tool developers:

• Stop bots at the protocol layer. PoW and Lightning sats are non-replayable, non-phishable, and don't require user accounts.
• Charge per call in sats. We sign a receipt you can show auditors, your customers, or your accountant.
• Wrap any MCP tool with one line (`createMcpGate`) and you get per-tool revenue, per-tool min/max pricing, and idempotent retries.

For AI agents / agent builders:

• Permissionless access to paid APIs — solve a PoW or pay sats, get a JWT. No signup, no email, no OAuth dance.
• Use PoW, Lightning invoices, or L402 bundle macaroons for agent access.
• Projects can settle through a custom Lightning node when configured; otherwise payments use the LiveAuthCore-configured node.

The math that matters: if your tool is being scraped by a bot, charging 1 sat per call is enough to make the scraper unprofitable. We call this *cost-of-attack economics*, and it's the whole reason we exist.

Installation

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

Or use directly with npx:

npx @liveauth-labs/mcp-server

Goose

LiveAuth for Goose uses the same standards-based stdio MCP server as every other client—there is no Goose wrapper, daemon, or duplicate authentication runtime.

Install in Goose

Or print the official deep link and current fallbacks:

npx @liveauth-labs/mcp-server setup goose

For a one-off Goose CLI session:

goose session --with-extension "liveauth:npx -y @liveauth-labs/mcp-server"

Manual Goose stdio configuration, when the deep link is unavailable:

extensions:
  liveauth:
    type: stdio
    name: LiveAuth
    enabled: true
    cmd: npx
    args: ["-y", "@liveauth-labs/mcp-server"]
    env_keys: []
    envs: {}
    timeout: 300

Do not edit an existing Goose config destructively. Prefer the deep link or `goose configure`; if you add project configuration later, enter it through Goose's extension secret settings rather than shared plaintext YAML.

Goose quick test

Ask Goose:

> Use LiveAuth to start the default authentication flow. Confirm the returned quote, then show my LiveAuth usage.

The initial flow uses the anonymous demo project's PoW challenge and does not require a wallet. A project public key is optional:

When a paid flow is requested, tool results retain the existing invoice fields and also include portable structured data:

{
  "lightning": {
    "invoice": "lnbc...",
    "lightningUri": "lightning:lnbc...",
    "amountSats": 21,
    "expiresAt": "2030-03-17T17:46:40.000Z",
    "status": "pending"
  }
}

Clients with MCP Apps support can render the included QR, Open Wallet action, expiration, and live paid/pending/expired state. Other clients receive the JSON and QR image content as ordinary MCP results.

Goose troubleshooting

• If the link does not open, run `npx @liveauth-labs/mcp-server setup goose` and use its one-session or manual fallback.
• If `npx` is unavailable, install a current Node.js release (Node 18 or newer).
• If a supplied project key is rejected, remove it to verify the anonymous PoW flow; invalid and revoked keys intentionally do not fall back to demo.
• If a Lightning invoice expires, call `liveauth_mcp_start` again to obtain a fresh quote.
• Keep refresh tokens and any non-public credentials out of logs and plaintext configuration.

LiveAuth lets agents acquire authorization at runtime instead of requiring every tool to be provisioned with permanent credentials in advance.

SDK Usage

The package can also be imported as a TypeScript/JavaScript SDK. Importing the package does not start the stdio MCP server; the CLI lives at the `liveauth-mcp` bin.

Client Auth Helper

import { createMcpClient } from '@liveauth-labs/mcp-server';

const liveauth = createMcpClient({
  publicKey: 'la_pk_xxx',
  baseUrl: 'https://api.liveauth.app',
  onInvoice(invoice) {
    // Render invoice.bolt11 as a QR code for a paid Lightning test.
    console.log(invoice.bolt11);
  },
});

const session = await liveauth.start();
const token = await liveauth.confirm(session);

console.log(token.jwt);

The client stores confirmed JWTs, refreshes them before expiry when a refresh token is returned, and exposes the current token through `liveauth.token`. Call `liveauth.destroy()` when your app is shutting down to clear token state and refresh timers.

To require a real paid invoice:

const session = await liveauth.start({ forceLightning: true });
console.log(session.invoice?.bolt11);

// Poll this after the invoice is paid.
const token = await liveauth.confirmLightning(session);

Server Gate Helper

import { createMcpGate } from '@liveauth-labs/mcp-server';

const gate = createMcpGate({
  publicKey: 'la_pk_xxx',
  baseUrl: 'https://api.liveauth.app',
});

const result = await gate.invoke(
  jwtFromYourTransport,
  { message: 'hello' },
  async (input, context) => ({
    content: [{ type: 'text', text: input.message }],
    charge: context.liveAuth.charge,
  }),
  {}
);

`gate.invoke(...)` validates the JWT, charges the configured sats cost or the backend project default, and passes `context.liveAuth` into your handler. The older `gate.gateTool(...)` name is still supported.

Paid Tool Attribution

If your MCP server has a registered LiveAuth tool ID, pass `toolId` when creating the gate. Charges then go to:

POST /api/mcp/tools/{toolId}/charge

instead of the legacy generic endpoint:

POST /api/mcp/charge

You can also pass a registered tool slug/name as `toolName`. In that mode charges go to the generic endpoint with tool identity in the body:

POST /api/mcp/charge

Tool charges preserve the same session budget checks, but also record an immutable revenue event with gross sats, LiveAuth platform fee, developer net sats, tool method name, paying project/session/token, metadata, and idempotency key. When `costSats` is omitted, LiveAuthCore uses the registered tool's default price; without `toolId` or `toolName`, it falls back to the project's global MCP price.

Registered tools can also have a paid-call webhook URL. On every successful new paid call, LiveAuthCore queues a `liveauth.mcp.tool.paid_call` webhook with the tool identity, gross/platform/net sats, revenue event ID, metadata, and the signed receipt. If the tool webhook URL is blank, LiveAuthCore falls back to the project's webhook URL; idempotent retries do not enqueue duplicates.

import { createMcpGate } from '@liveauth-labs/mcp-server';

const gate = createMcpGate({
  publicKey: process.env.LIVEAUTH_PUBLIC_KEY!,
  baseUrl: process.env.LIVEAUTH_API_URL ?? 'https://api.liveauth.app',
  toolName: 'paid-research-tool',
});

const result = await gate.invoke(
  jwtFromYourTransport,
  { url: 'https://example.com' },
  async (input, context) => {
    const page = await fetch(input.url).then(r => r.text());

    return {
      text: page,
      revenueEventId: context.liveAuth.charge.revenueEventId,
      receipt: context.liveAuth.charge.receipt,
      netSats: context.liveAuth.charge.netSats,
    };
  },
  { requestId: 'req_123' },
  {
    toolMethodName: 'web_fetch',
    idempotencyKey: 'req_123',
    agentId: 'agent_abc',
    metadata: {
      urlHost: new URL('https://example.com').hostname,
    },
  }
);

When `toolId` or `toolName` is set, `GateToolOptions` supports:

Tool charge responses include the normal budget counters plus revenue accounting:

{
  "status": "ok",
  "callsUsed": 3,
  "satsUsed": 15,
  "grossSats": 5,
  "platformFeeSats": 1,
  "netSats": 4,
  "feeBasisPoints": 500,
  "revenueEventId": "event-guid",
  "toolId": "tool-guid",
  "toolName": "Paid Research Tool",
  "toolSlug": "paid-research-tool",
  "receipt": {
    "version": "mcp-call-receipt-v1",
    "payload": "base64url-canonical-json",
    "signature": "base64url-hmac-sha256",
    "signatureAlgorithm": "HMAC-SHA256",
    "keyId": "liveauth-mcp-receipt-v1",
    "body": {
      "receiptId": "mcp_receipt_eventguid",
      "revenueEventId": "event-guid",
      "mcpToolId": "tool-guid",
      "toolName": "Paid Research Tool",
      "toolSlug": "paid-research-tool",
      "toolMethodName": "web_fetch",
      "grossSats": 5,
      "platformFeeSats": 1,
      "netSats": 4,
      "idempotencyKey": "req_123"
    }
  }
}

The receipt is a signed per-call audit artifact returned by LiveAuthCore for paid tool charges. Store it with your tool result when you need proof of charge or later reconciliation.

If no `toolId` or `toolName` is configured, the SDK keeps using `/api/mcp/charge` for backward-compatible usage metering.

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": "la_pk_your_public_key"
      }
    }
  }
}

Credential-free mode: If you omit `LIVEAUTH_API_KEY`, the server calls the normal MCP endpoints without a project header. LiveAuth binds its configured anonymous demo project, returns a signed PoW challenge, and preserves normal verification, JWT, rate-limit, and metering boundaries. `LIVEAUTH_DEMO=true` remains an explicit opt-in to the older locally simulated Lightning preview.

Other env vars:

Other MCP Clients

The server speaks stdio (JSON-RPC 2.0). Start it with:

liveauth-mcp

It also works with any MCP-compatible client: Cursor, VS Code, ChatGPT, Windsurf, Continue, Cline.

Tool Reference

Full schemas for each MCP tool. Each tool is JSON-RPC 2.0 compatible and tested under `src/index.test.ts` and `src/cli.test.ts`.

`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
• `forceL402` (boolean, optional): If true, start a session that should be confirmed with an L402 bundle macaroon

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..."
  },
  "lightning": {
    "invoice": "lnbc...",
    "lightningUri": "lightning:lnbc...",
    "amountSats": 50,
    "expiresAt": "2009-02-13T23:31:30.000Z",
    "expiresAtUnix": 1234567890,
    "status": "pending"
  }
}

Returns (L402 bundle):

{
  "quoteId": "uuid-of-session",
  "powChallenge": null,
  "invoice": null,
  "authHint": "l402_bundle"
}

`liveauth_mcp_confirm`

Submit a solved proof-of-work challenge, let the package solve its cached challenge, poll a Lightning payment, or present an L402 macaroon to receive a JWT authentication token.

Parameters:

• `quoteId` (string): The quoteId from the start response
• `challengeHex` (string, optional, PoW only): The challenge hex from the start response
• `nonce` (number, optional, PoW only): The nonce that solves the PoW challenge
• `hashHex` (string, optional, PoW only): The resulting hash (sha256 of `projectPublicKey:challengeHex:nonce`)
• `expiresAtUnix` (number, optional, PoW only): Expiration timestamp from the challenge
• `difficultyBits` (number, optional, PoW only): Difficulty bits from the challenge
• `signature` (string, optional, PoW only): Signature from the challenge
• `macaroon` (string, L402 only): Bundle macaroon returned from the L402 bundle claim flow

When the challenge came from this MCP server, calling confirm with `quoteId` alone reuses the package's existing PoW solver. Explicit solution fields remain supported for compatibility.

Returns:

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

Note: Store the `refreshToken` securely. It is returned in MCP tool data but never written to stderr or application logs. Use `liveauth_mcp_refresh` to get a new JWT without re-authenticating.

`liveauth_mcp_charge`

Meter API usage after making an authenticated call. The bundled MCP server calls the generic `/api/mcp/charge` endpoint. Supplying `toolName` lets LiveAuth resolve a registered tool, apply its configured price, and create a paid-tool revenue event; omitting `toolName` keeps backward-compatible generic metering.

Parameters:

• `callCostSats` (number, optional): Cost of the API call in sats. Omit to use backend pricing.
• `toolName` (string, optional): Registered MCP tool slug/name for per-tool pricing and attribution.

Returns:

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

If budget is exceeded:

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

`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. Call `liveauth_mcp_confirm` with the quoteId; the MCP server solves its cached challenge with the existing package solver

3. Advanced clients may still submit an explicit solution (`hash = sha256(projectPublicKey:challengeHex:nonce)` where `hash ` header for API requests

5. After each generic API call, call `liveauth_mcp_charge` with a call cost, or omit it to use the project global MCP price

6. For monetized MCP tools, wrap handlers with `createMcpGate({ toolId })` or `createMcpGate({ toolName })` so each call creates a revenue event and signed receipt

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 with either generic `liveauth_mcp_charge` metering or SDK paid-tool attribution

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    │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Paid tool servers use the same JWT but charge through an attributed endpoint:

Agent calls MCP tool
→ Tool server calls POST /api/mcp/tools/{toolId}/charge
  or POST /api/mcp/charge with toolName
→ LiveAuth validates JWT and budget
→ LiveAuth records gross / platform fee / net revenue and returns a signed receipt
→ Tool handler runs and returns the result

L402 Bundle Flow

LiveAuthCore supports Lightning-backed L402 bundles for prepaid MCP access. Buy a bundle, claim the macaroon after payment, then start an MCP session in L402 mode and confirm it with that macaroon.

# 1. Create a bundle invoice.
curl -X POST https://api.liveauth.app/api/public/l402/bundle/invoice \
  -H "Content-Type: application/json" \
  -d '{"publicKey":"la_pk_xxx","tier":"starter","agentId":"agent_abc"}'

# 2. After the invoice is paid, claim a macaroon.
curl -X POST https://api.liveauth.app/api/public/l402/bundle/claim \
  -H "Content-Type: application/json" \
  -d '{"publicKey":"la_pk_xxx","paymentHash":"payment_hash_from_step_1"}'

# 3. Start and confirm an MCP session with the macaroon.
curl -X POST https://api.liveauth.app/api/mcp/start \
  -H "X-LW-Public: la_pk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"forceL402":true}'

curl -X POST https://api.liveauth.app/api/mcp/confirm \
  -H "X-LW-Public: la_pk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"quoteId":"quote_id_from_step_3","macaroon":"macaroon_from_step_2"}'

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/cli.js

Resources

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

License

MIT

Categories: `authentication` · `payments` · `lightning` · `l402` · `bitcoin` · `pay-per-call` · `metering` · `agent-tools` · `anti-abuse` · `mcp-server` · `typescript`