Liveauth Mcp Server

LiveAuth MCP サーバー

呼び出し元負担の MCP（1.3.0）： 既存の createMcpGate({ publicKey, toolName, fundingMode: 'caller' }) を使用します。LiveAuthCore が呼び出し元の支払いを検証し、会計を管理します。このパッケージは支払いチャレンジ、再試行のひも付け、重複実行の防止を担います。呼び出し元負担の仕組み、API の例、移行方法。PoW は認証に使われます。有料ツールの支払いには使われません。

AI エージェントと MCP ツールのための認証、呼び出しごとの従量課金、署名付きレシート：Bitcoin ネイティブで、Lightning に対応し、L402 と互換性があります。

この MCP サーバーを使うと、任意の AI エージェントがプルーフ・オブ・ワーク（無料、アカウント不要）またはLightning Network のマイクロペイメント（sats）で API に対して認証できます。その後、呼び出しごとの料金設定、冪等性のある収益イベント、監査者がオフラインで検証できる HMAC 署名付きレシートによって、後続のツール呼び出しの使用量を計測し、収益化できます。

次のような場合にご利用ください：

• CAPTCHA ではなく、設計上のスパム対策として、実際の計算コストまたは実際の sats を要する API や MCP ツールを利用制限する。
• アカウント登録なしで、AI エージェントに呼び出しごとの料金を請求する。
• 有料ツールを呼び出すたびに、改ざんを検知できる監査証跡（署名付きの mcp-call-receipt-v1）を発行する。
• Lightning に対応した L402 バンドルアクセスを、前払い式の MCP セッション向けに提供する。

5 秒で試す — アカウントも API キーも不要：

npx @liveauth-labs/mcp-server

設定がない場合、サーバーは LiveAuth の匿名デモプロジェクトと実際の PoW フローを使用します。特定のプロジェクトのポリシー、料金設定、またはアトリビューションが必要な場合にのみ、LIVEAUTH_API_KEY を追加してください。

---

利用可能なツール（Glama / MCP による自動検出）

ツール	用途
liveauth_mcp_start	セッションを開始します。PoW チャレンジ、Lightning 請求書、または L402 バンドルのヒントを返します。
liveauth_mcp_confirm	解決済みの PoW チャレンジ、支払い済みの Lightning 請求書、または L402 macaroon を送信し、JWT を受け取ります。
liveauth_mcp_charge	呼び出し後の使用量を計測します。toolName を指定すると、登録済みツールの料金を解決し、有料の収益イベントを記録します。
liveauth_mcp_refresh	リフレッシュトークンを新しい JWT と交換します。再認証は不要です。
liveauth_mcp_status	セッション／支払いの状態（Lightning の確認、期限切れ）をポーリングします。
liveauth_mcp_lnurl	セッションの BOLT11 請求書を取得します（lnget 互換）。
liveauth_mcp_payment_confirm	現在のセッションで呼び出し元の支払いを確認します。その後、元の操作を再試行します。
liveauth_mcp_usage	残りの予算、使用済み呼び出し回数、レート制限の期間を照会します。

パラメーターとレスポンスの完全なスキーマは、以下のツールリファレンスをご覧ください。

---

5 分でクイックスタート

オプション 1 — 認証情報不要の PoW（アカウント、キー、ウォレット不要）

npx @liveauth-labs/mcp-server

MCP クライアントで liveauth_mcp_start を呼び出し、次に返された quoteId のみを指定して liveauth_mcp_confirm を呼び出します。このパッケージは既存の PoW ソルバーをローカルで再利用し、LiveAuth API が署名付きチャレンジを検証してから、有効期間の短いセッション JWT を発行します。

オプション 2 — 本番モード

1. liveauth.app で API キーを取得します。
2. Claude Desktop の 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. Claude を再起動します。これで完了です。

オプション 3 — プログラムから使用（CLI / SDK）

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

このパッケージは TypeScript SDK としても利用できます。以下のSDK の使い方をご覧ください。CLI の実行ファイルは liveauth-mcp です。

LiveAuth を選ぶ理由

API プロバイダー／ツール開発者向け：

• プロトコルレイヤーでボットを阻止できます。PoW と Lightning の sats は再利用もフィッシングもできず、ユーザーアカウントも不要です。
• 呼び出しごとに sats で課金できます。監査担当者、顧客、会計担当者に提示できる領収書に署名します。
• 1 行（createMcpGate）で任意の MCP ツールをラップすると、ツールごとの収益、ツールごとの最小／最大価格、冪等な再試行が可能になります。

AI エージェント／エージェント開発者向け：

• 有料 API に許可不要でアクセスできます。PoW を解くか sats を支払えば、JWT を取得できます。登録、メールアドレス、OAuth の手続きは不要です。
• エージェントアクセスには、PoW、Lightning 請求書、または L402 バンドルのマカロンを使用できます。
• 設定されている場合、プロジェクトはカスタム Lightning ノードを通じて決済できます。そうでない場合、支払いには LiveAuthCore で設定されたノードが使用されます。

重要な計算： ボットにツールをスクレイピングされている場合、呼び出しごとに 1 sat 課金するだけで、スクレイピングを採算の合わないものにできます。これは 攻撃コストの経済性 と呼んでおり、これこそが私たちの存在する理由です。

インストール

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

または npx で直接使用します：

npx @liveauth-labs/mcp-server

Stdio の検証（MCPVault を含む）

コマンドに npx を、引数に ["-y", "@liveauth-labs/mcp-server"] を設定してください。 initialize、notifications/initialized、 tools/list に環境変数は不要です。セッション中は stdin を開いたままにしてください。起動時の診断情報は stderr に出力されます。CLI 引数なしで実行する場合、stdout は MCP メッセージ専用です。 検証ツールには --help や setup goose を渡さないでください。これらのコマンドは意図的に終了します。

LIVEAUTH_API_KEY は任意で、プロジェクトの公開鍵を選択します。LIVEAUTH_API_BASE のデフォルト値は https://api.liveauth.app です。検証時は LIVEAUTH_DEMO を未設定のままにしてください。 レガシーのシミュレーションモードは不要です。ツール呼び出し時には、引き続き認証と支払いの要件が適用されます。 安全なオフライン検出テストでは、LIVEAUTH_API_BASE=http://127.0.0.1:1 を設定し、キーは未設定のままにして、初期化と ツール一覧の取得のみを行えます。これらの操作では API に接続しません。

npm run test:package を実行すると、プロジェクトをビルドしてパッケージ化し、tarball を一時ディレクトリにインストールしたうえで、 MCP クライアントを使って直接のエントリーポイントと npm bin をテストします。 このテストでは、スペースや予約文字を含むパスを使用し、未認証の課金が拒否されることも検証します。

バージョン 1.3.1 では、npm bin のシンボリックリンク経由、またはスペースや URL 予約文字を含むパスから呼び出した際に 終了コード 0 で終了することがあった、1.3.0 のエントリーポイント検出バグが修正されています。再現可能な検証には、 npx -y @liveauth-labs/[email protected] を使用してください。ローカルでのハンドシェイク成功は、MCPVault 独自の再テストに合格したことを 証明するものではありません。別途報告されている終了コード 134 は、まだ再現されていません。

原因不明の終了（特にコード 134）が発生した場合は、プロセス起動時の stderr 全体、終了コードとシグナル、 解決されたパッケージバージョン、Node/npm のバージョン、OS／アーキテクチャ、正確な argv、作業ディレクトリ、 stdin／ハンドシェイクのタイミングを記録してください。非推奨警告だけでは、中断の原因を特定できません。

Goose

Goose 用の LiveAuth は、他のすべてのクライアントと同じ標準準拠の stdio MCP サーバーを使用します。Goose 用のラッパーやデーモン、重複する認証ランタイムはありません。

Goose にインストール

または、公式のディープリンクと現在の代替手段を表示します：

npx @liveauth-labs/mcp-server setup goose

Goose CLI の一時的なセッションでは：

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

ディープリンクを利用できない場合の、Goose stdio の手動設定：

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

既存の Goose 設定を破壊的に編集しないでください。ディープリンクまたは goose configure を優先してください。後でプロジェクト設定を追加する場合は、共有の平文 YAML ではなく、Goose の拡張機能シークレット設定から入力してください。

Goose のクイックテスト

Goose に次のように依頼します。

LiveAuth を使って、デフォルトの認証フローを開始してください。返された見積もりを確認してから、LiveAuth の使用状況を表示してください。

初期フローでは、匿名のデモプロジェクトの PoW チャレンジを使用するため、ウォレットは不要です。プロジェクトの公開鍵は任意です。

変数	設定する場合
LIVEAUTH_API_KEY	プロジェクト固有のポリシー、料金、アトリビューションを設定する場合。
LIVEAUTH_API_BASE	https://api.liveauth.app の代わりにセルフホストの LiveAuth API を使用する場合。
LIVEAUTH_DEMO=true	旧式のローカルシミュレーションによる Lightning デモを明示的に選択する場合。

有料フローがリクエストされると、ツールの結果には既存の請求書フィールドに加え、持ち運び可能な構造化データも含まれます。

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

MCP Apps に対応したクライアントでは、含まれる QR コード、「ウォレットを開く」アクション、有効期限、支払い済み／保留中／期限切れのライブ状態を表示できます。それ以外のクライアントでは、JSON と QR 画像コンテンツが通常の MCP 結果として返されます。

Goose のトラブルシューティング

• リンクが開かない場合は、npx @liveauth-labs/mcp-server setup goose を実行し、1 セッション用または手動の代替手順を使用してください。
• npx を利用できない場合は、現行の Node.js リリース（Node 18 以降）をインストールしてください。
• 指定したプロジェクトキーが拒否された場合は、キーを削除して匿名 PoW フローを確認してください。無効なキーや失効したキーがデモにフォールバックすることはありません。
• Lightning 請求書の有効期限が切れた場合は、liveauth_mcp_start を再度呼び出して新しい見積もりを取得してください。
• リフレッシュトークンや非公開の認証情報は、ログや平文の設定ファイルに記録しないでください。

LiveAuth を使うと、すべてのツールにあらかじめ永続的な認証情報を設定する必要なく、エージェントが実行時に認可を取得できます。

SDK の使用方法

このパッケージは TypeScript／JavaScript SDK としてインポートすることもできます。パッケージをインポートしても stdio MCP サーバーは起動しません。CLI は liveauth-mcp の bin にあります。

クライアント認証ヘルパー

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);

クライアントは確認済みの JWT を保存し、リフレッシュトークンが返された場合は有効期限前に更新します。また、現在のトークンを liveauth.token から参照できます。アプリのシャットダウン時に liveauth.destroy() を呼び出して、トークンの状態とリフレッシュタイマーをクリアしてください。

PoW では、config.publicKey が X-LW-Public で送信される認証情報です。これは、プロジェクトのプライマリ公開鍵、またはそのプロジェクトに属する有効な API 公開鍵のいずれかです。API は正規のプロジェクトキーを session.powChallenge.projectPublicKey で返します。ソルバーは返されたキーをハッシュし、確認時には設定された認証情報を引き続き送信します。この 2 つのキー文字列は正当に異なる場合があるため、両者の一致を比較してもプロジェクトの分離を確認することはできません。

信頼できる LiveAuth API エンドポイントからのセッションを使用してください。サーバーは見積もりと署名済みチャレンジを解決されたプロジェクトにひも付け、projectId と authType を含む JWT を発行します。診断時には、トークンをログに記録せず、JWT の projectId をコンソールで確認できる想定プロジェクト ID と比較してください。クレームをデコードしただけでは、JWT の署名は検証されません。

実際の有料請求書を必須にするには、次のようにします。

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);

サーバーゲートヘルパー

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(...) は JWT を検証し、設定された sats の料金またはバックエンドプロジェクトのデフォルト料金を請求してから、context.liveAuth をハンドラーに渡します。従来の gate.gateTool(...) という名前も引き続きサポートされています。

有料ツールの帰属

MCP サーバーに登録済みの LiveAuth ツール ID がある場合は、ゲートの作成時に toolId を渡します。これにより、課金先は次のエンドポイントになります。

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

従来の汎用エンドポイントではなく、次のエンドポイントが使われます。

POST /api/mcp/charge

登録済みのツールスラッグ／名前を toolName として渡すこともできます。このモードでは、リクエスト本文にツールの ID 情報を含め、汎用エンドポイントに課金します。

POST /api/mcp/charge

ツールの課金では、同じセッション予算チェックが適用されるほか、総 sats、LiveAuth のプラットフォーム手数料、開発者の手取り sats、ツールのメソッド名、支払いを行ったプロジェクト／セッション／トークン、メタデータ、冪等性キーを含む不変の収益イベントも記録されます。costSats を省略すると、LiveAuthCore は登録済みツールのデフォルト価格を使用します。toolId も toolName も指定されていない場合は、プロジェクトのグローバル MCP 価格が適用されます。

登録済みツールには、有料呼び出し用の Webhook URL を設定することもできます。有料呼び出しが新たに成功するたびに、LiveAuthCore はツールの ID 情報、総／プラットフォーム／手取り sats、収益イベント ID、メタデータ、署名付きレシートを含む liveauth.mcp.tool.paid_call Webhook をキューに追加します。ツールの Webhook URL が空欄の場合、LiveAuthCore はプロジェクトの Webhook URL を使用します。冪等性のある再試行では、重複した Webhook はキューに追加されません。

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,
    },
  }
);

toolId または toolName が設定されている場合、GateToolOptions では次のオプションを使用できます。

オプション	用途
costSats	この呼び出しに課金する sats。省略すると、登録済みツールの価格またはプロジェクトのグローバル価格が使用されます。
toolName	汎用エンドポイントを使用する場合の、呼び出しごとの任意のツールスラッグ／名前の上書き値。
toolMethodName	web_fetch や search など、ツール内のメソッド。
idempotencyKey	再試行時の安全性を確保するためのキー。同じツールに対して再利用すると、二重課金の代わりに元の収益イベントと署名付きレシートが返されます。
agentId	レポート用の呼び出し元／エージェント ID（任意）。
metadata	監査用コンテキストを記録する小さな JSON オブジェクト。ツールの非公開出力はここに保存しないでください。

ツールの課金レスポンスには、通常の予算カウンターに加えて収益会計情報が含まれます。

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

レシートは、有料ツールの課金に対して LiveAuthCore が返す、署名付きの呼び出しごとの監査証跡です。課金の証明や後日の照合が必要な場合は、ツールの結果とともに保存してください。

toolId も toolName も設定されていない場合、SDK は後方互換性を保つため、引き続き /api/mcp/charge を使用して利用状況を計測します。

設定

Claude Desktop

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

認証情報なしモード： LIVEAUTH_API_KEY を省略すると、サーバーはプロジェクトヘッダーなしで通常の MCP エンドポイントを呼び出します。LiveAuth は設定済みの匿名デモプロジェクトを割り当て、署名付き PoW チャレンジを返し、通常の検証、JWT、レート制限、利用状況計測の境界を維持します。LIVEAUTH_DEMO=true は、従来のローカルでシミュレートされた Lightning プレビューを明示的に使用するための設定です。

その他の環境変数：

変数	デフォルト	用途
LIVEAUTH_API_KEY	(未設定)	LiveAuth プロジェクトの公開キー（la_pk_…）。
LIVEAUTH_API_BASE	https://api.liveauth.app	セルフホスト可能な LiveAuth の接続先を上書きします。
LIVEAUTH_DEMO	false	従来のローカルでシミュレートされた Lightning デモを明示的に使用します。

その他の MCP クライアント

このサーバーは stdio（JSON-RPC 2.0）を使用します。次のコマンドで起動します。

liveauth-mcp

Cursor、VS Code、ChatGPT、Windsurf、Continue、Cline など、MCP 互換のクライアントでも動作します。

ツールリファレンス

各 MCP ツールの完全なスキーマです。各ツールは JSON-RPC 2.0 に準拠しており、src/index.test.ts と src/cli.test.ts でテストされています。

liveauth_mcp_start

新しい LiveAuth MCP セッションを開始します。デフォルトでは PoW チャレンジを返し、forceLightning=true の場合は Lightning インボイスを返します。

パラメーター：

• forceLightning（boolean、任意）：true の場合、PoW チャレンジの代わりに Lightning インボイスを要求します
• forceL402（boolean、任意）：true の場合、L402 バンドルの macaroon で確認するセッションを開始します

戻り値（PoW）：

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

戻り値（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"
  }
}

戻り値（L402 バンドル）：

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

liveauth_mcp_confirm

解決済みのプルーフ・オブ・ワークチャレンジを送信する、パッケージにキャッシュ済みのチャレンジを解決させる、Lightning の支払いをポーリングする、または L402 マカロンを提示して JWT 認証トークンを受け取ります。

パラメーター：

• quoteId（string）：開始レスポンスの quoteId
• challengeHex（string、任意、PoW のみ）：開始レスポンスのチャレンジの 16 進数文字列
• nonce（number、任意、PoW のみ）：PoW チャレンジを解決する nonce
• hashHex（string、任意、PoW のみ）：結果のハッシュ（projectPublicKey:challengeHex:nonce の sha256）
• expiresAtUnix（number、任意、PoW のみ）：チャレンジの有効期限タイムスタンプ
• difficultyBits（number、任意、PoW のみ）：チャレンジの難易度ビット数
• signature（string、任意、PoW のみ）：チャレンジの署名
• macaroon（string、任意、L402 のみ）：L402 バンドルの請求フローで返されるバンドルマカロン

チャレンジがこの MCP サーバーから取得された場合、quoteId のみを指定して confirm を呼び出すと、パッケージに組み込まれた既存の PoW ソルバーが再利用されます。互換性のため、解決に必要なフィールドを明示的に指定する方法も引き続きサポートされています。

戻り値：

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

注： refreshToken は安全に保管してください。MCP ツールのデータとして返されますが、stderr やアプリケーションログに書き込まれることはありません。再認証せずに新しい JWT を取得するには、liveauth_mcp_refresh を使用します。

liveauth_mcp_charge

認証済みの呼び出しを行った後、API の使用量を計上します。バンドルされた MCP サーバーは、汎用の /api/mcp/charge エンドポイントを呼び出します。toolName を指定すると、LiveAuth は登録済みのツールを特定し、設定済みの価格を適用して、有料ツールの収益イベントを作成します。toolName を省略すると、後方互換性のある汎用の使用量計上が行われます。

パラメーター：

• callCostSats（number、任意）：API 呼び出しのコスト（sats）。省略すると、バックエンドの価格設定が使用されます。
• toolName（string、任意）：ツールごとの価格設定と帰属に使用する、登録済み MCP ツールのスラッグ／名前。

戻り値：

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

予算を超過した場合：

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

liveauth_mcp_status

MCP セッションのステータスを確認します。Lightning の支払い確認をポーリングする場合に使用します。

パラメーター：

• quoteId（string）：開始レスポンスの quoteId

戻り値：

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

paymentStatus が "paid" の場合、セッションは確認済みです。JWT を取得するには、liveauth_mcp_confirm を再度呼び出します。

liveauth_mcp_lnurl

セッションの Lightning 請求書を取得します（lnget 互換）。任意の Lightning ウォレットで支払うための BOLT11 請求書を取得する場合に使用します。

パラメーター：

• quoteId（string）：開始レスポンスの quoteId

戻り値：

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

注： lnget などの Lightning 支払いツールと互換性があります。liveauth_mcp_confirm が "payment pending" を返した場合、請求書をポーリングするために使用します。

liveauth_mcp_usage

料金を発生させずに、現在の使用量と残りの予算を照会します。API 呼び出しを行う前にステータスを確認する場合に使用します。

パラメーター：（必須のものはありません）

戻り値：

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

再認証せずに JWT トークンを更新します。現在の JWT の有効期限が切れたときに、confirm から返された refreshToken を使用して新しい JWT を取得します。

パラメーター：

• refreshToken（string）：confirm レスポンスの refreshToken

戻り値：

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

注： refreshToken は安全に保管してください。新たな PoW を解いたり、別の Lightning 支払いを行ったりせずにセッションを延長するために必要です。

使用例

PoW 認証

1. liveauth_mcp_start を呼び出して、PoW チャレンジと quoteId を取得します
2. quoteId を指定して liveauth_mcp_confirm を呼び出します。MCP サーバーはキャッシュ済みのチャレンジを既存のパッケージソルバーで解決します
3. 高度なクライアントは、引き続き明示的な解を送信できます（hash = sha256(projectPublicKey:challengeHex:nonce) で、hash < targetHex）
4. API リクエストには、Authorization: Bearer <token> ヘッダーで JWT を使用します
5. 各汎用 API 呼び出しの後、呼び出しコストを指定して liveauth_mcp_charge を呼び出します。省略すると、プロジェクトのグローバル MCP 価格が適用されます
6. 収益化された MCP ツールでは、各呼び出しで収益イベントと署名済みレシートを生成するため、ハンドラーを createMcpGate({ toolId }) または createMcpGate({ toolName }) でラップします

Lightning 認証

1. forceLightning: true を指定して liveauth_mcp_start を呼び出し、Lightning 請求書を取得します
2. liveauth_mcp_lnurl を使用するか、liveauth_mcp_status をポーリングして BOLT11 請求書を取得します
3. Lightning ノードまたはウォレットを使って請求書を支払います
4. 支払いステータスが「paid」になるまで、quoteId を指定して liveauth_mcp_status をポーリングします
5. quoteId のみを指定して liveauth_mcp_confirm を呼び出し、JWT を受け取ります
6. 汎用の liveauth_mcp_charge による従量課金、または SDK による有料ツールのアトリビューションのいずれかで JWT を使用します

認証フロー

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

有料ツールを提供するサーバーでは、同じ JWT を使用しますが、アトリビューション付きのエンドポイントを通じて課金します。

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 バンドルフロー

LiveAuthCore は、前払い MCP アクセス向けに Lightning を利用した L402 バンドルをサポートしています。バンドルを購入し、支払い後に macaroon を取得してから、L402 モードで MCP セッションを開始し、その 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"}'

開発

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/cli.js

リソース

• LiveAuth デモとドキュメント
• MCP プロトコル仕様
• GitHub リポジトリ

ライセンス

MIT

---

カテゴリー： authentication · payments · lightning · l402 · bitcoin · pay-per-call · metering · agent-tools · anti-abuse · mcp-server · typescript

有料実行と診断に関する契約（SDK 1.2.0）

ゲートはセッションを検証し、課金を記録してからハンドラーを呼び出します。 **認可と受理された実行試行は、課金後にハンドラーの例外、タイムアウト、 キャンセルが発生した場合も含め、課金対象です。**自動返金はありません。 ゲート通過前の入力拒否と課金拒否では、使用量は消費されません。ステータスが Charged の収益イベントは、課金されたことを証明するものであり、ツールの 実行が成功したことを証明するものではありません。

有料呼び出しを受け付ける前にツールを登録し、ライフサイクルを Draft から Active に変更してください。Draft は未公開を意味し（tool_unpublished）、 Paused やその他の非アクティブ状態では tool_inactive が返されます。 公開ディスカバリーには Visibility=Public も必要ですが、可視性と ライフサイクルは別のものです。アクティブな非公開／内部ツールも課金できます。 この変更では、別個の公開フラグや新たな可視性制限は導入されません。 不明または削除済みのツールには、status=deny、reason=tool_not_found、 指定されたツール ID を含む JSON を伴った HTTP 404 が返されます。登録済み ツールのライフサイクルによる拒否と予算による拒否では、HTTP 200 と status=deny が維持されます。

理由	意味
tool_unpublished	ツールが Draft です。
tool_inactive	ツールが Paused、またはその他の非アクティブ状態です。
tool_not_found	一致する未削除のツールがありません。
budget_exceeded	既存の予算ポリシーにより課金が拒否されました。
rate_limited	SDK がサポートする構造化されたレート制限拒否です。現在の MCP 課金コントローラーはこの理由を出力せず、1 分あたりの設定も適用しません。
denied	拒否に理由がない場合の SDK のフォールバックです。将来追加される未知の理由コードは SDK エラーから引き続き取得できます。

gate.charge() は、JSON の HTTP エラーレスポンスで status=deny が返された 場合も含め、ok=false を伴う構造化された拒否を返します。gate.invoke() と gate.gateTool() は、reason、code、toolName、toolId を持つ ChargeDeniedError をスローします。互換性のため、これは BudgetExceededError（および LiveAuthMcpError）を拡張しています。 新しいハンドラーでは、すべてのインスタンスが予算超過を意味すると想定せず、 reason を確認してください。無関係な HTTP 認証、トランスポート、 バリデーションの失敗は、従来のエラーパスを維持します。古いバックエンドでは、 アップグレードされるまで、未知のツールに対してプレーンテキストのエラーが 返される場合があります。

ハンドラーが失敗すると、ゲートは charge、idempotencyKey、および 列挙不可の cause を持つ ToolExecutionError をスローします。公開される メッセージは汎用的なものです。課金フィールドの許可リストとして、 grossSats、revenueEventId、署名付きの receipt、冪等性キーを公開して ください。MCP レスポンスでは isError=true を維持してください。エラーの cause、JWT を含むハンドラーコンテキスト、任意のメタデータをシリアライズまたは ログに記録しないでください。レシートのペイロード／署名は既存の公開レスポンス 要素であり、返却できます。課金が成功してもレシートがない場合があります。 レシートをでっち上げず、この違いを維持してください。課金メタデータは実行の 成功を意味するものではありません。

import { ChargeDeniedError, ToolExecutionError } from '@liveauth-labs/mcp-server';

try {
  return await gate.invoke(jwt, input, handler, {}, { idempotencyKey });
} catch (error) {
  if (error instanceof ToolExecutionError) {
    return {
      isError: true,
      content: [{ type: 'text', text: 'Tool execution failed after authorization' }],
      _meta: { liveauth: {
        billed: true,
        grossSats: error.charge.grossSats,
        revenueEventId: error.charge.revenueEventId,
        receipt: error.charge.receipt,
        idempotencyKey: error.idempotencyKey,
      } },
    };
  }
  if (error instanceof ChargeDeniedError) {
    // Map known reasons to a public response. Do not serialize error.details wholesale.
    throw error;
  }
  throw error;
}

3つの異なる識別子

• レシートの body.requestId：元の記録済み課金に対する LiveAuth のサーバー HTTP リクエスト／相関識別子です。 リトライでは元のレシートが返されます。
• レシートの body.idempotencyKey：呼び出し元が指定する、リトライ時も変わらないキーです。呼び出し元の資金による課金では、重複排除の対象は呼び出し元のセッション、プロバイダー、登録済みツールの組み合わせです。従来のプロバイダー資金による課金では、支払いプロジェクトとツールが対象です。
• InvokeWorks の _meta.requestId：MCP／クライアントの相関 ID で、X-Request-Id から取得するか、JSON-RPC リクエスト ID から導出されます。InvokeWorks はこれを LiveAuth の冪等性キーとしても使用します。

たとえば、_meta.requestId="client-123"、レシートの body.idempotencyKey="client-123"、レシートの body.requestId="server-456" の組み合わせは有効です。SDK が受け付けるのは idempotencyKey であり、クライアントリクエスト ID 用のオプションを別途送信することはありません。呼び出し元コンテキストの { requestId } は、ローカルのハンドラーコンテキストです。新しい論理呼び出しには新しいキーを使用し、同じキーを再利用するのは同じ操作を意図している場合に限ってください。課金の重複排除ではハンドラーの結果はキャッシュされないため、従来のプロバイダーモードではリトライ時にハンドラーが再実行されることがあります。呼び出し元の資金による重複した認可では、記録済みの支払いステータスが返され、再実行されません。ツールの状態と価格の確認は、引き続き重複排除より先に行われます。