Liveauth Mcp Server

LiveAuth MCP 服务

**调用方付费 MCP（1.3.0）：**使用现有的 createMcpGate({ publicKey, toolName, fundingMode: 'caller' })。LiveAuthCore 验证调用方付款并负责记账；此软件包负责付款挑战、重试绑定和防止重复执行。调用方付费、API 示例和迁移。PoW 用于身份验证；它不会为付费工具提供资金。

为 AI Agent 和 MCP 工具提供身份验证、按次调用计量和签名收据：原生支持 Bitcoin、由 Lightning 支持，并兼容 L402。

此 MCP 服务允许任何 AI Agent 使用工作量证明（免费，无需账户）或 Lightning Network 微支付（聪）对你的 API 进行身份验证，然后通过按次定价、幂等收入事件和可供审计人员离线验证的 HMAC 签名收据，对后续工具调用进行计量和变现。

适用于以下场景：

• 使用实际计算成本或真实聪为 API 或 MCP 工具设置门槛（从设计上防止垃圾请求，而非依赖 CAPTCHA）。
• 按次向 AI Agent 收费，无需让它们注册账户。
• 为每次付费工具调用生成防篡改审计记录（已签名的 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 sat 不可重放、不可钓鱼，也无需用户账号。
• 按调用次数收取 sat。我们会签署收据，供你出示给审计人员、客户或会计师。
• 只需一行代码即可封装任意 MCP 工具（createMcpGate），并获得按工具计费、按工具设置最低／最高价格以及幂等重试功能。

面向 AI Agent／Agent 构建者：

• 无需许可即可访问付费 API——完成 PoW 或支付 sat，即可获取 JWT。无需注册、无需邮箱，也无需经历 OAuth 流程。
• 可通过 PoW、Lightning 发票或 L402 bundle macaroon 为 Agent 提供访问权限。
• 配置后，项目可以通过自定义 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 修复了 1.3.0 的入口点检测错误：通过 npm bin 符号链接调用，或从包含空格 或 URL 保留字符的路径调用时，该错误可能导致程序以代码 0 退出。若要进行可复现的验证，请使用 npx -y @liveauth-labs/[email protected]。本地握手成功并不能证明 MCPVault 自身的重新测试也会通过；单独报告的退出代码 134 尚未复现。

遇到原因不明的退出（尤其是代码 134）时，请保留进程启动时的完整 stderr、退出代码和信号、解析出的包版本、Node/npm 版本、 操作系统／架构、确切的 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；如果之后添加项目配置，请通过 Goose 的扩展密钥设置输入，而不要使用共享的明文 YAML。

Goose 快速测试

向 Goose 提问：

使用 LiveAuth 启动默认身份验证流程。确认返回的报价，然后显示我的 LiveAuth 用量。

初始流程使用匿名演示项目的 PoW 挑战，无需钱包。项目公钥为可选项：

变量	设置时机
LIVEAUTH_API_KEY	设置项目专属策略、定价和归属信息时。
LIVEAUTH_API_BASE	使用自托管的 LiveAuth API，而非 https://api.liveauth.app 时。
LIVEAUTH_DEMO=true	明确选择旧版本地模拟 Lightning 演示时。

请求付费流程时，工具结果会保留现有发票字段，并额外包含可移植的结构化数据：

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

支持 MCP Apps 的客户端可以呈现其中包含的二维码、“打开钱包”操作、过期时间，以及实时的已支付／待处理／已过期状态。其他客户端会将 JSON 和二维码图像内容作为普通 MCP 结果返回。

Goose 故障排除

• 如果链接无法打开，请运行 npx @liveauth-labs/mcp-server setup goose，并使用其单会话或手动备用方案。
• 如果无法使用 npx，请安装当前版本的 Node.js（Node 18 或更高版本）。
• 如果提供的项目密钥被拒绝，请移除它以验证匿名 PoW 流程；无效和已撤销的密钥不会回退到演示模式。
• 如果 Lightning 发票过期，请再次调用 liveauth_mcp_start 获取新的报价。
• 请勿将刷新令牌和任何非公开凭据写入日志或明文配置。

LiveAuth 让 Agent 可以在运行时获取授权，而无需预先为每个工具配置永久凭据。

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 中返回规范项目密钥；求解器会对该返回密钥进行哈希处理，而确认请求仍会发送配置的凭据。这两个密钥字符串可能不同，因此，比较它们是否相等不能用于检查项目隔离。

请使用来自可信 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，请在创建 gate 时传入 toolId。费用将计入：

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

而不是旧版通用端点：

POST /api/mcp/charge

你也可以将已注册的工具 slug/名称作为 toolName 传入。在这种模式下，费用将计入通用端点，工具身份信息会包含在请求正文中：

POST /api/mcp/charge

工具费用沿用相同的会话预算检查，同时还会记录不可变的收入事件，其中包含毛 sats、LiveAuth 平台手续费、开发者净 sats、工具方法名称、付费项目/会话/令牌、元数据和幂等键。省略 costSats 时，LiveAuthCore 会使用已注册工具的默认价格；如果没有设置 toolId 或 toolName，则会回退到项目的全局 MCP 价格。

已注册的工具也可以设置付费调用 webhook URL。每次成功的新付费调用都会让 LiveAuthCore 排队发送 liveauth.mcp.tool.paid_call webhook，其中包含工具身份、毛/平台/净 sats、收入事件 ID、元数据和签名回执。如果工具 webhook URL 为空，LiveAuthCore 会回退到项目的 webhook URL；幂等重试不会重复排队。

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	使用通用端点时，每次调用可选的工具 slug/名称覆盖值。
toolMethodName	工具内的方法，例如 web_fetch 或 search。
idempotencyKey	可安全重试的键。对同一工具重复使用此键时，会返回原始收入事件和签名回执，而不会重复收费。
agentId	可选的调用方/Agent 标识符，用于报告。
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

它也适用于任何兼容 MCP 的客户端：Cursor、VS Code、ChatGPT、Windsurf、Continue、Cline。

工具参考

每个 MCP 工具的完整架构。每个工具都兼容 JSON-RPC 2.0，并在 src/index.test.ts 和 src/cli.test.ts 下经过测试。

liveauth_mcp_start

启动新的 LiveAuth MCP 会话。默认返回 PoW 挑战；如果 forceLightning=true，则返回 Lightning 发票。

参数：

• forceLightning（布尔值，可选）：如果为 true，则请求 Lightning 发票而不是 PoW 挑战
• forceL402（布尔值，可选）：如果为 true，则启动一个应使用 L402 bundle 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 bundle）：

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

liveauth_mcp_confirm

提交已解出的工作量证明挑战，让程序包解出其缓存的挑战，轮询 Lightning 付款，或提供 L402 macaroon 以获取 JWT 身份验证令牌。

参数：

• quoteId（字符串）：开始响应中的 quoteId
• challengeHex（字符串，可选，仅限 PoW）：开始响应中的挑战十六进制值
• nonce（数字，可选，仅限 PoW）：解出 PoW 挑战的 nonce
• hashHex（字符串，可选，仅限 PoW）：生成的哈希（projectPublicKey:challengeHex:nonce 的 sha256）
• expiresAtUnix（数字，可选，仅限 PoW）：挑战中的过期时间戳
• difficultyBits（数字，可选，仅限 PoW）：挑战中的难度位数
• signature（字符串，可选，仅限 PoW）：挑战中的签名
• macaroon（字符串，仅限 L402）：L402 套餐申领流程返回的套餐 macaroon

如果挑战来自此 MCP 服务，只需使用 quoteId 调用 confirm，即可复用程序包已有的 PoW 求解器。为保持兼容性，仍支持显式提供解答字段。

返回：

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

注意： 请安全存储 refreshToken。它会在 MCP 工具数据中返回，但不会写入 stderr 或应用日志。使用 liveauth_mcp_refresh 获取新的 JWT，无需重新进行身份验证。

liveauth_mcp_charge

进行经过身份验证的调用后，计量 API 用量。捆绑的 MCP 服务会调用通用的 /api/mcp/charge 端点。提供 toolName 后，LiveAuth 会解析已注册的工具，应用其配置价格，并创建付费工具收入事件；省略 toolName 则继续使用向后兼容的通用计量方式。

参数：

• callCostSats（数字，可选）：API 调用的 sats 成本。省略时使用后端定价。
• toolName（字符串，可选）：用于按工具定价和归因的已注册 MCP 工具 slug/名称。

返回：

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

如果超出预算：

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

liveauth_mcp_status

检查 MCP 会话状态。用于轮询 Lightning 付款确认状态。

参数：

• quoteId（字符串）：开始响应中的 quoteId

返回：

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

当 paymentStatus 为 "paid" 时，会话即已确认。再次调用 liveauth_mcp_confirm 以获取 JWT。

liveauth_mcp_lnurl

获取会话的 Lightning 发票（兼容 lnget）。用于获取 BOLT11 发票，以便使用任意 Lightning 钱包付款。

参数：

• quoteId（字符串）：开始响应中的 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（字符串）：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. 调用 liveauth_mcp_start 并设置 forceLightning: true，获取 Lightning 账单
2. 使用 liveauth_mcp_lnurl（或轮询 liveauth_mcp_status）获取 BOLT11 账单
3. 使用你的 Lightning 节点／钱包支付账单
4. 使用 quoteId 轮询 liveauth_mcp_status，直到 paymentStatus 为 "paid"
5. 仅使用 quoteId 调用 liveauth_mcp_confirm，以获取 JWT
6. 将 JWT 用于通用的 liveauth_mcp_charge 计量，或 SDK 付费工具归因

身份验证流程

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  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 支持由 Lightning 支持的 L402 套餐，可用于预付费的 MCP 访问。购买套餐，付款后领取 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，但可见性与生命周期是分开的：活动的私有／内部工具仍可被扣费。本次变更不包含单独的发布标志或新的可见性限制。 未知或已移除的工具会返回 HTTP 404，JSON 中包含 status=deny、 reason=tool_not_found 以及提供的工具标识。已注册工具的生命周期拒绝和预算拒绝仍返回 HTTP 200，并包含 status=deny。

原因	含义
tool_unpublished	工具处于 Draft 状态。
tool_inactive	工具处于 Paused 状态或其他非活动状态。
tool_not_found	没有匹配的未移除工具。
budget_exceeded	现有预算策略拒绝了此次扣费。
rate_limited	SDK 支持的结构化速率限制拒绝；当前 MCP 扣费控制器不会发出此原因，也不会强制执行其每分钟设置。
denied	拒绝未提供原因时，SDK 使用的回退原因。未知的未来原因代码仍可通过 SDK 错误获取。

gate.charge() 会返回结构化拒绝，包含 ok=false，其中也包括 JSON HTTP 错误响应中的 status=deny。gate.invoke() 和 gate.gateTool() 会抛出 ChargeDeniedError，包含 reason、code、toolName 和 toolId。为兼容性起见， 它继承自 BudgetExceededError（以及 LiveAuthMcpError）；新的处理程序必须检查 reason，而不能假定每个实例都表示预算耗尽。无关的 HTTP 身份验证、传输和验证失败仍沿用现有错误处理路径。 较旧的后端在升级前仍可能对未知工具返回纯文本错误。

处理程序失败时，网关会抛出 ToolExecutionError，包含 charge、 idempotencyKey 和不可枚举的 cause。其公开消息为通用消息。 请仅公开扣费字段的允许列表：grossSats、revenueEventId、签名后的 receipt 以及幂等键。MCP 响应中应保留 isError=true。不要序列化或记录错误原因、 包含 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;
}

三种不同的标识符

• 回执 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 } 是本地处理程序上下文。为新的逻辑调用使用新键， 且仅对同一预期操作重复使用同一个键。去重扣费不会缓存处理程序结果：在旧版 提供方模式下，重试可能会再次执行处理程序。调用方出资时，重复授权会返回已记录 的付款状态，且不会再次执行。工具状态和价格检查仍会在去重前进行。