Liveauth MCP

LiveAuth MCP Server

Caller-funded MCP (1.3.0): use the existing createMcpGate({ publicKey, toolName, fundingMode: 'caller' }). LiveAuthCore verifies caller payment and owns accounting; this package owns payment challenges, retry binding and duplicate execution prevention. Caller funding, API examples and migration. PoW authenticates; it does not fund paid tools.

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

1. 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

Stdio verification (including MCPVault)

Configure the command as npx and arguments as ["-y", "@liveauth-labs/mcp-server"]. No environment variables are required for initialize, notifications/initialized, or tools/list. Keep stdin open throughout the session. Startup diagnostics go to stderr; stdout is reserved for MCP messages when running without CLI arguments. Do not pass --help or setup goose to a verifier: those commands intentionally exit.

LIVEAUTH_API_KEY optionally selects a project's public key, and LIVEAUTH_API_BASE defaults to https://api.liveauth.app. Leave LIVEAUTH_DEMO unset for verification; the legacy simulated mode is not needed. Authentication and payment requirements remain enforced when tools are called. A safe offline discovery test can set LIVEAUTH_API_BASE=http://127.0.0.1:1, leave the key unset, and only initialize and list tools; those operations do not contact the API.

Run npm run test:package to build and pack the project, install the tarball into a temporary directory, and test the direct entry point and npm bin with an MCP client. The test includes paths with spaces and reserved characters and verifies that an unauthenticated charge is rejected.

Version 1.3.1 fixes the 1.3.0 entry-point detection bug that could exit with code 0 when invoked through an npm bin symlink or from a path containing spaces or URL-reserved characters. For a reproducible verification, use npx -y @liveauth-labs/mcp-server@1.3.1. A successful local handshake does not establish that MCPVault's own retest passes; the separately reported exit 134 has not been reproduced.

For an unexplained exit (especially code 134), retain complete stderr from process launch, the exit code and signal, resolved package version, Node/npm versions, OS/architecture, exact argv, working directory, and stdin/handshake timing. A deprecation warning alone does not establish the cause of an abort.

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.

For PoW, config.publicKey is the credential sent in X-LW-Public. It may be either the project's primary public key or an active API public key belonging to that project. The API returns the canonical project key in session.powChallenge.projectPublicKey; the solver hashes that returned key, and confirmation still sends the configured credential. These two key strings can legitimately differ, so comparing them for equality is not a project-isolation check.

Use sessions from your trusted LiveAuth API endpoint. The server binds the quote and signed challenge to the resolved project and issues a JWT with projectId and authType. For diagnostics, compare the JWT's projectId with the expected project ID from your console, without logging the token. Decoding claims alone does not verify a JWT signature.

To require a real paid invoice:

const session = await liveauth.start({ forceLightning: true });

console.log(session.invoice?.