Paygate MCP

支付门mcp

 ](https://www.npmjs.com/package/paygate-mcp) 

只需一个命令即可将任何MCP服务器货币化。向任何模型上下文协议服务器添加API密钥身份验证、每工具定价、速率限制和使用计量。零依赖。零配置。零代码更改。

目录

• 快速开始
• 它的作用
• 用法 --本地stdio、远程HTTP、多服务器、客户端SDK
• API 参考 --所有199+个端点
• CLI选项
• 部署 --Docker、Docker编写、systemd、PM2
• 负载测试 --k6生产基准测试
• 错误代码 --完整的错误代码参考
• 功能参考 --每个功能的详细文档

- 存储和计费 · 条纹 · ACL · 速率限制 - 密钥管理 · 网络钩子 · OAuth 2.1 · 上海证券交易所 - 分析（64个端点） · 团队 · Redis扩展 - 插件 · 群组 · 命名空间

• 程序化API
• 安全
• 经过测试 --针对流行的MCP服务器进行验证
• 当前限制
• 路线图
• 需求
• 许可证

快速开始

# Interactive setup wizard (generates paygate.json)
npx paygate-mcp init

# Or wrap directly with CLI flags
npx paygate-mcp wrap --server "npx @modelcontextprotocol/server-filesystem /tmp"

# Gate a remote MCP server (Streamable HTTP transport)
npx paygate-mcp wrap --remote-url "https://my-server.example.com/mcp" --price 5

就是这样。您的MCP服务器现在在API密钥后面使用基于信用的计费。

它的作用

PayGate位于AI代理和MCP服务器之间：

Agent → PayGate (auth + billing) → Your MCP Server (stdio or HTTP)

• API密钥认证 --客户需要有效的 X-API-Key 调用工具
• 信用账单 --每次工具调用的成本积分（可按工具配置）
• 速率限制 --滑动窗口每键速率限制+每工具速率限制
• 使用计量 --追踪谁打了什么电话，什么时候打，花了多少钱
• 多服务器模式 --使用工具前缀路由将N个MCP服务器包裹在一个PayGate后面
• 客户端SDK — PayGateClient 具有自动402重试、平衡跟踪和键入错误
• 两次运输 --通过stdio包装本地服务器，或通过Streamable HTTP包装远程服务器
• 每个工具ACL -每个API密钥的白名单/黑名单工具（企业访问控制）
• 每工具速率限制 --每个工具的独立费率限制，而不仅仅是全球范围内的
• 密钥过期（TTL） -在设定时间后自动导出API密钥
• 支出限额 -按API键限制总开支，以防止成本失控
• 使用配额 --每个密钥的每日/每月通话和信用额度（UTC自动重置）
• 动态定价 --根据输入大小收取额外积分(creditsPerKbInput)
• OAuth 2.1 --具有PKCE、客户端注册和承载令牌的完全授权服务器
• SSE流媒体 --完整的MCP流式HTTP传输（POST SSE、GET通知、DELETE会话）
• 审计日志 -具有保留策略、查询API、CSV/JSON导出的结构化审核跟踪
• 注册表/发现 --代理可通过以下方式发现定价 /.well-known/mcp-payment, /pricing，以及 /.well-known/mcp.json 身份证
• OpenAPI 3.1+交互式文档 --自动生成的规格 /openapi.jsonSwagger用户界面 /docs --记录了所有199+个端点
• 公共端点速率限制 --可配置每IP速率限制（默认300/min） /health, /info, /pricing, /docs, /openapi.json, /.well-known/*, /robots.txt, / --429带有Retry-After标头
• Robots.txt+头部支持 --标准 /robots.txt （允许公共，不允许管理员/密钥），所有公共端点上的HEAD方法用于正常运行时间监控
• 普罗米修斯指标 — /metrics 端点，带有标准文本格式的计数器、仪表和正常运行时间
• 关键点旋转 -在不丢失信用、ACL或配额的情况下旋转API密钥
• 速率限制标头 — X-RateLimit-* 和 X-Credits-Remaining 在每一个 /mcp 回应
• Webhook签名 --HMAC-SHA256签名的webhook有效载荷(X-PayGate-Signature)用于防篡改交付
• 管理员生命周期事件 --key.created、key.revoked、key.rotated、key.topup的Webhook通知
• IP允许列表 -将API密钥限制为特定IP或CIDR范围（IPv4）
• 关键标签/元数据 -将任意键-值标记附加到API键以进行外部系统集成
• 使用情况分析 -时间序列分析API，包括工具细分、顶级消费者和趋势比较
• 提醒Webhooks --可配置的支出阈值、低信用、配额警告、密钥到期、利率上限峰值警报
• 团队管理 -将API密钥分组到具有共享预算、配额和使用情况跟踪的团队中
• 水平缩放（Redis） -用于多进程部署的Redis支持状态，具有原子信用扣减、分布式利率限制、持久使用审计跟踪、实时发布/子通知和管理API同步
• Webhook重试队列 -指数退避重试（1s、2s、4s…），带有死信队列，用于永久失败的交付，管理API，用于监控、清除和回放
• 管理员仪表板v2 --标签式网络仪表板位于 /dashboard 包括概述、密钥管理（创建/挂起/恢复/撤销/充值）、分析（信用流、拒绝原因、顶级消费者、webhook健康状况）和系统状态——所有数据都通过安全的DOM方法，30秒自动刷新
• 自助服务门户 -API密钥持有者门户网站 /portal --在没有管理员权限的情况下检查信用、使用情况、费率限制、可用工具和最近的活动；包括购买积分UI、具有支出速度的信用历史记录、使用警报和自助密钥轮换
• 条纹结账 --通过Stripe Checkout Sessions进行自助信用卡购买-- POST /stripe/checkout 创建会话， GET /stripe/packages 列出可用包；使用Node.js实现零依赖 https，通过webhook自动充值积分
• 状态备份和还原 — GET /admin/backup 将完整的服务器状态（密钥、团队、组、Webhook）导出为带有SHA-256校验和的版本化JSON； POST /admin/restore 具有合并/覆盖/完整模式和完整性验证的导入
• API版本头 — X-PayGate-Version 用于客户端版本跟踪的每个HTTP响应上的标头，通过CORS公开
• 就绪探针 — GET /ready 根据操作状态（不排水、不维护、后端连接）返回200/503，与 /health 活性探针，Kubernetes的理想选择
• 健康检查+优雅关机 — GET /health 带有状态、正常运行时间、版本、正在处理的请求、Redis和webhook统计信息的公共端点； gracefulStop() 在拆卸之前删除飞行中的请求
• 配置验证+试运行 — paygate-mcp validate --config paygate.json 在开始之前发现错误配置； --dry-run 发现工具，打印定价表，然后退出
• 批处理工具调用 — tools/call_batch 在一个请求中调用多个工具的方法，包括全有或全无计费、聚合信用检查和并行执行
• 多租户命名空间 -通过名称空间过滤的管理端点、分析和使用导出按租户隔离API密钥和使用数据
• 范围令牌 --问题持续时间短 pgt_ 令牌作用于特定工具，具有自动过期（最多24小时）、HMAC-SHA256签名、服务器端状态为零
• 令牌撤销列表 -使用O（1）查找、自动清理、Redis跨实例同步和管理API在到期前吊销作用域令牌
• 基于使用情况的自动充值 --当余额降至阈值以下时，通过可配置的每日限额、审计跟踪、webhook事件和Redis同步自动添加信用
• 管理员API密钥管理 --具有基于角色的权限（超级管理员、管理员、查看器）、文件持久性、审计跟踪和安全防护的多个管理员密钥
• 插件系统 --可扩展的中间件挂钩，用于自定义计费逻辑、请求/响应转换、自定义端点和生命周期管理
• 键群 -将共享ACL、速率限制、定价覆盖、IP允许列表和配额应用于具有自动继承和密钥级别覆盖支持的API密钥组的策略模板
• 失败退款 --下游工具调用失败时自动退款
• 贷记转账 -使用验证、审计跟踪和webhook事件在API密钥之间原子传输信用
• 批量密钥操作 --在单个请求中执行多个关键操作（创建、充值、撤销、挂起、恢复），并对每个操作进行错误处理和索引跟踪
• 关键导入/导出 -导出用于备份/迁移的所有API密钥（JSON或CSV），并使用冲突解决方案导入（跳过、覆盖、错误模式）
• Webhook过滤器 -根据事件类型和API密钥前缀，使用过滤器机密、独立重试队列和管理员CRUD API，将webhook事件路由到不同的目的地
• 密钥克隆 — POST /keys/clone 使用相同的配置（ACL、配额、标记、IP、命名空间、组、支出限制、过期、自动使用）创建一个新的API密钥，但使用新的计数器-非常适合配置类似的密钥
• 钥匙悬挂 -暂时禁用API密钥而不吊销它们-已挂起的密钥在门口被拒绝，但可以恢复，并且管理操作（topup、ACL等）仍然对已挂起密钥有效
• 按密钥使用 — GET /keys/usage?key=... 返回特定密钥的详细使用情况细分：每个工具的统计数据、每小时的时间序列、拒绝原因、最近的事件和密钥元数据
• Webhook测试 — POST /webhooks/test 向您配置的webhook URL发送测试事件，并同步响应，包括状态代码、响应时间和交付成功/失败——验证webhook连接，而不生成真实事件
• Webhook交付日志 — GET /webhooks/log 返回所有webhook传递尝试的可查询日志，包括时间戳、HTTP状态代码、响应时间、成功/失败、重试尝试、事件计数和事件类型——按成功状态、时间范围和限制进行筛选
• Webhook暂停/恢复 — POST /webhooks/pause 和 POST /webhooks/resume 在维护期间暂时停止webhook传递——事件会被缓冲（不会丢失）并在恢复时刷新，暂停状态在中可见 /webhooks/stats
• 关键别名 — POST /keys/alias 分配人类可读的别名（例如。 my-service, prod-backend)到API密钥-在任何管理终结点（topup、revoke、suspend、resume、clone、transfer、use）中使用别名，而不是不透明的密钥ID，具有唯一性强制、格式验证、状态文件持久性和审核跟踪
• 密钥过期扫描程序 -主动式后台扫描程序，可在API密钥过期前检测过期的密钥-可配置的扫描间隔和通知阈值（默认值：7d、24h、1h），消除重复 key.expiry_warning webhook事件、审计跟踪、， GET /keys/expiring?within=86400 查询端点和优雅关闭
• 键盘模板 -API密钥创建的命名模板-定义可重复使用的预设（信用、ACL、配额、IP、标签、命名空间、到期TTL、支出限制、自动使用），并使用 template: "free-tier" -显式参数覆盖模板默认值，CRUD管理API，Prometheus仪表，文件持久性，最多100个模板
• 环境变量配置 --通过配置所有内容 PAYGATE_* Docker/K8s部署的环境变量——18个环境变量，涵盖所有CLI标志，优先级为：CLI标志>环境变量>配置文件>默认值， PAYGATE_CONFIG 加载配置文件路径，Docker示例帮助文本
• 请求ID跟踪 --每个HTTP响应都包括 X-Request-Id 标题（自动生成 req_ 前缀+16个十六进制字符）用于分布式跟踪--传播传入 X-Request-Id 来自负载平衡器/代理，包含在门审计日志元数据中，CORS公开，可通过 getRequestId(req) 助手
• 服务器信息端点 — GET /info 返回服务器功能、启用的功能、身份验证方法、定价摘要、速率限制和可用端点——公共，不需要管理密钥，是代理自动发现和调试的理想选择
• 可配置CORS --控制哪些源可以访问您的服务器：单个源、多个源或通配符(* 默认），支持凭据，可配置飞行前最大年龄，以及 Vary: Origin 正确缓存--通过配置文件设置 cors 对象， --cors-origin CLI标志，或 PAYGATE_CORS_ORIGIN env 是
• 自定义响应标头 --添加安全标头(X-Frame-Options, X-Content-Type-Options等）、缓存控制或所有HTTP响应的任何自定义标头——通过配置文件设置 customHeaders 对象， --header CLI标志，或 PAYGATE_CUSTOM_HEADERS env 是
• 配置导出 — GET /config 返回正在运行的服务器配置，其中隐藏了敏感值（webhook机密→ ***，服务器命令→ ***，webhook URL→ 仅限scheme+host）--需要管理员身份验证，包括审计跟踪
• 可信代理 --配置受信任的代理IP/CIDR以确保准确 X-Forwarded-For extraction--从右向左遍历标头，跳过受信任的代理以查找真实的客户端IP，支持精确的IP和CIDR范围（IPv4），未配置时向后兼容（第一个IP）
• 关键列表分页 --增强型 GET /keys 基于光标的分页(limit/offset)，排序(sortBy/order)，并按命名空间、组、活动/暂停/过期状态、名称前缀和信用范围进行过滤——向后兼容（未使用分页参数时返回平面数组）
• 关键统计数据 — GET /keys/stats 返回所有键的聚合统计信息——总计/活动/暂停/过期/撤销计数、信用聚合（已分配/已花费/剩余）、总调用数、命名空间和组细分，可选 ?namespace= 过滤器
• 速率限制状态 — GET /keys/rate-limit-status?key=... 返回任何键的当前速率限制窗口状态——全局调用已使用/剩余/重置时间、每个工具的速率限制和单独使用、只读（不消耗调用）
• 配额状态 — GET /keys/quota-status?key=... 返回任何密钥的每日/每月配额使用情况——已使用的调用和信用/剩余/限制、重置期、配额来源（每个密钥vs全局vs无）
• 信用记录 — GET /keys/credit-history?key=... 每个密钥信用突变日志的返回值——跟踪初始分配、充值、转账（入/出）、自动充值、类型/限制/自过滤、每个条目前后的余额、最新的首次订购，每个密钥最多100个条目
• 支出速度 — GET /keys/spending-velocity?key=... 返回信用消耗率和消耗预测——每小时/每天的信用/呼叫数、估计的消耗日期、按支出列出的顶级工具、可配置的分析窗口（1h-30d）
• 关键比对 — GET /keys/compare?keys=pg_a,pg_b 返回2-10个键（信用、使用、速度、速率限制、状态、元数据（名称空间/组/标签））的并排比较，以及未找到的键报告
• 关键健康评分 — GET /keys/health?key=... 返回包含加权组件细分的复合健康评分（0-100）：余额健康（30%）、配额利用率（25%）、速率限制压力（20%）、错误率（25%
• 维护模式 — POST /maintenance 使用自定义消息启用/禁用维护模式-- /mcp 在管理端点保持操作的同时向客户端返回503， GET /maintenance 检查状态， GET /health 反映维护状态，完整的审计跟踪
• 管理员事件流 — GET /admin/events SSE端点将实时审计事件流式传输到管理客户端——工具调用、拒绝、关键操作、维护更改，所有这些都是可选的 ?types= 事件类型过滤、保活ping、多客户端支持过滤器
• 关键要点 — POST /keys/notes 将带时间戳的注释添加到API密钥， GET /keys/notes?key=... 列出笔记， DELETE /keys/notes?key=...&index=N 删除注释——每个密钥最多50个字符，1000个字符限制，处理挂起/撤销的密钥，别名支持，审计跟踪
• 计划行动 — POST /keys/schedule 在API密钥上创建未来日期的动作（撤销/暂停/停止）， GET /keys/schedule 列出待定的日程安排（可选） ?key= 过滤器， DELETE /keys/schedule?id=... 取消计划——每个密钥最多20个，别名支持，后台执行计时器，审计跟踪
• 关键活动时间表 — GET /keys/activity?key=... 返回特定键的审计事件和使用事件的统一时间顺序提要——最新优先，可选 ?since= 和 ?limit= 过滤器，别名支持
• 信用预订 — POST /keys/reserve 持有学分， POST /keys/reserve/commit 扣除持有的信用额度， POST /keys/reserve/release 释放控制， GET /keys/reserve 列出活动预订——防止超额承诺，可配置TTL（10秒-1小时），每个密钥最多50个，自动到期，审计跟踪
• 请求日志 — GET /requests 每个工具调用的可查询日志，包括时间、收费信用、状态（允许/拒绝）、拒绝原因、密钥和请求ID——按密钥/工具/状态/原因、分页、汇总统计（总计+平均持续时间）、5000个条目环形缓冲区进行过滤
• 工具统计信息 — GET /tools/stats 按工具分析：呼叫计数、成功率、平均/p95延迟、消耗的信用、拒绝原因细分、前10名消费者——可选 ?tool= 对于详细的单工具视图， ?since= 过滤器
• 请求日志导出 — GET /requests/export 将完整的请求日志导出为JSON或CSV格式，并带有Content-Disposition标头——按键/工具/状态/自/直到筛选，组合时间窗口查询，无分页限制
• 工具调用模拟运行 — POST /requests/dry-run 在不执行的情况下模拟工具调用——检查密钥有效性、ACL、速率限制、信用和支出限制，返回计算后的预测结果以及信用和速率限制状态
• 批量试运行 — POST /requests/dry-run/batch 一次模拟多个工具调用——聚合信用检查、每个工具ACL验证、支出限额、每个工具的返回结果，包括所需的总信用和之后的信用
• 工具可用性 — GET /tools/available?key=... 每个关键工具的可用性回报，包括定价、可负担性（canAfford）、ACL执行（可访问/拒绝原因）和每个工具+全球费率限制状态
• 关键仪表板 — GET /keys/dashboard?key=... 整合的单端点视图，包括元数据、余额、健康评分、支出速度、费率限制、配额、使用情况摘要和最近的活动时间线
• 管理员通知 — GET /admin/notifications 扫描所有密钥以查找可操作的问题：过期/到期密钥、零信用、信用耗尽速度、挂起密钥、高错误率和速率限制压力——具有严重性过滤和优先级排序
• 系统仪表盘 — GET /admin/dashboard 全系统概述，包括关键计数（活动/暂停/撤销/过期）、信用摘要（已分配/已花费/剩余）、使用情况细分（包括拒绝原因）、主要消费者、主要工具、通知计数和正常运行时间
• 关键生命周期报告 — GET /admin/lifecycle 聚合生命周期趋势，包括每日创建/撤销/暂停桶、平均密钥生命周期和有风险的密钥（到期、过期、零信用）
• 成本分析 — GET /admin/costs 以成本为中心的视图，包括每个工具和每个命名空间的成本细分、每小时的支出趋势、最高支出者、每次调用的平均成本和命名空间过滤
• 利率限制分析 — GET /admin/rate-limits 速率限制利用率分析，包括每个键和每个工具的细分、拒绝趋势、限制最多的键和当前窗口利用率
• 配额分析 — GET /admin/quotas 配额利用率分析，包括每个密钥的每日/每月使用量与限制、每个工具的拒绝细分、最受限制的密钥以及全局/每个密钥的配额源跟踪
• 否认分析 — GET /admin/denials 按原因类型（信用不足、利率限制、配额超标、密钥暂停等）进行全面的拒绝细分，包括每个密钥和每个工具的统计数据、每小时的趋势和大多数被拒绝的密钥
• 流量分析 — GET /admin/traffic 请求量分析，包括工具流行度、小时数、按呼叫数划分的顶级消费者、命名空间细分、高峰时段识别和成功率
• 响应缓存 --SHA-256键控响应缓存用于相同的工具调用——跳过后端调用和缓存命中、LRU驱逐、每个工具或全局TTL的信用扣减， X-Cache: HIT/MISS 标题，管理员管理(GET/DELETE /admin/cache)普罗米修斯测量仪
• 断路器 --三态断路器（闭合→ open → half_open）用于后端故障检测——在连续N次故障后打开，冷却后自动恢复，错误代码 -32003，管理(GET/POST /admin/circuit)
• 可配置超时 --每个工具和工具调用的全局超时--返回错误代码 -32004 超时时，通过按工具覆盖 toolPricing[tool].timeoutMs，触发断路器故障记录
• 基于结果的定价 --根据响应输出大小收取额外积分-- creditsPerKbOutput 根据工具配置、响应后计费， X-Output-Surcharge 标题，补语 creditsPerKbInput 基于尺寸的完整定价
• 合规审计导出 --SOC 2、GDPR、HIPAA的特定框架合规报告-- GET /admin/compliance/export，事件分类为访问控制/数据处理/配置更改/安全、JSON或CSV导出、可配置时间段
• 每键Webhook URL --密钥级webhook路由——特定密钥的事件与全局webhook一起发送到密钥的webhook URL，SSRF保护，HMAC-SHA256签名，懒惰发射器管理，通过 POST/GET/DELETE /keys/webhook
• 安全审计 — GET /admin/security 安全态势分析，识别没有IP分配表、配额、ACL限制、支出限制或到期日期的密钥，标记高信用密钥，并计算综合安全评分
• 收入分析 — GET /admin/revenue 收入指标，包括每个工具的收入细分、每个关键支出、每小时收入趋势、信贷流摘要（分配/支出/剩余）和每次通话的平均收入
• 关键投资组合健康状况 — GET /admin/key-portfolio 整个投资组合的密钥健康状况，包括活动/非活动/暂停计数、过期密钥、即将到期的密钥、年龄分布、信用利用率和命名空间细分
• 内容物护栏 -工具调用输入/输出的基于Regex的PII检测和编校-8个内置规则（信用卡、SSN、电子邮件、电话、AWS密钥、API机密、IBAN、passport）、4个操作（log/warn/block/redact）、范围过滤（输入/输出/两者都有）、逐个目标、使用查询API的违规跟踪、管理员CRUD端点(/admin/guardrails, /admin/guardrails/violations)
• IP国家限制 --具有允许/拒绝国家列表的按关键地理访问控制（ISO 3166-1 alpha-2）——来自反向代理标头的国家代码(X-Country, CF-IPCountry，可配置），通过CRUD /keys/geo，在门口评估时强制执行，零依赖地理围栏
• 批量暂停/恢复 --已添加 suspend 和 resume 行动 POST /keys/bulk --在一个请求中临时禁用或重新激活多个密钥，并对每个操作进行错误处理
• 并发限制器 --每个键和每个工具的飞行请求上限——与速率限制不同，限制同时进行的活动请求，以保护后端免受突发并行性、错误代码的影响 -32005 随着 Retry-After 标头，运行时间可通过以下方式调整 GET/POST /admin/concurrency
• 流量镜像 -即发即弃请求复制到影子后端，用于a/B测试MCP服务器版本-基于百分比的采样、可配置的超时、对主响应路径的零影响、通过 GET/POST/DELETE /admin/mirror
• 工具别名+弃用 --工具重命名符合RFC 8594标准——将旧工具名称映射到新工具名称 Deprecation, Sunset，以及 Link 标头、防链、每个别名调用计数、CRUD GET/POST/DELETE /admin/tool-aliases
• 使用计划 --分层关键策略（免费/专业/企业）——将利率限制、配额、信用乘数和工具ACL捆绑到可重用的模板中，通过以下方式为计划分配密钥 POST /admin/keys/plan，拒绝工具，并返回错误代码 -32403，通过CRUD GET/POST/DELETE /admin/plans
• 工具输入模式验证 --网关上的每工具JSON模式验证——注册模式以在无效有效负载到达下游之前拒绝它们，零依赖JSON模式子集（类型、必需、枚举、minLength、模式、项目），错误代码 -32602 如果有详细的错误，请通过以下方式进行管理 GET/POST/DELETE /admin/tools/schema
• 金丝雀路线 --主MCP服务器和金丝雀MCP服务器之间的加权流量分流——通过基于百分比的路由（0-100%）实现零停机升级，无偏见 crypto.randomInt 决策、每次后端调用/错误跟踪、无需重新启动即可更新权重、通过管理 GET/POST/DELETE /admin/canary
• 请求/响应转换 --工具调用参数和响应的声明性重写——注入默认值、删除字段、重命名键和模板 {{variables}} 从上下文、通配符工具匹配、优先级排序、应用时的深度克隆、导入/导出以进行备份、通过管理 GET/POST/PUT/DELETE /admin/transforms
• 后端重试策略 --针对瞬态故障，采用指数回退的自动重试方式——可配置的最大重试次数、基本/最大回退、完全抖动、重试预算（冷启动宽限期重试的最大流量百分比）、每个工具的统计数据、可重试的错误模式匹配、通过管理 GET/POST /admin/retry-policy
• 自适应速率限制 --基于关键行为的动态速率调整——高错误率自动收紧，良好参与者自动提升，冷却期，可配置阈值，按关键行为跟踪，LRU驱逐，批量评估，通过以下方式管理 GET/POST /admin/adaptive-rates
• 请求重复数据删除 --Idempotency层防止代理重试时重复计费-- X-Idempotency-Key 带有自动生成回退（SHA-256）的标头、正在进行的请求合并、可配置的TTL窗口、LRU驱逐、信用保存跟踪、通过管理 GET/POST/DELETE /admin/dedup
• 优先队列 --具有公平调度的分层请求优先级（关键/高/正常/低/后台）——按密钥优先级分配，每层可配置的最大等待时间，通过自动升级防止饥饿，最大队列深度限制，通过 GET/POST /admin/priority-queue
• 成本分配标签 --根据请求，通过以下方式进行成本归因 X-Cost-Tags 企业按存储容量使用计费的标头（JSON）——按任何标签维度聚合报告、交叉表、CSV导出、每个密钥所需的标签强制、基数限制、通过管理 GET/POST/DELETE /admin/cost-tags
• IP访问控制 --基于IP的细粒度访问控制，支持CIDR表示法——全局允许/拒绝列表、按密钥IP绑定、可配置违规阈值后的自动阻止、X-Forwarded-For/X-Real-IP可信代理深度、IPv6映射的IPv4规范化、通过 GET/POST/DELETE /admin/ip-access
• 请求签名（HMAC-SHA256） --具有重放保护的加密请求身份验证-- X-Signature: t=,n=,s= 标头、带随机数去重的时间戳容差、带旋转的每个密钥签名密钥、定时安全比较、通过管理 GET/POST/DELETE /admin/signing
• 多租户隔离 -针对平台运营商的全租户隔离-租户利率限制、信用池、使用情况跟踪、API密钥绑定、租户暂停/激活、跨租户报告、可配置限制（10K租户、1K密钥/租户），通过 GET/POST/DELETE /admin/tenants
• 请求跟踪 --端到端结构化跟踪，在门、后端和转换阶段进行跨度记录——跟踪/请求ID查找、时序分解（gateMs/backendMs/transformMs）、可配置采样率、保留限制、P95延迟跟踪、JSON导出、通过管理 GET/POST/DELETE /admin/tracing
• 预算策略引擎 --具有渐进节流功能的燃烧率监控——每日/每月预算执行、可配置窗口内的信用/分钟燃烧率跟踪、三个操作（警报/节流/拒绝）、每个命名空间和每个密钥目标、预算剩余预测、自动每日/每月重置、通过管理 GET/POST/DELETE /admin/budget-policies
• 工具依赖关系图 --基于DAG的工作流验证——注册工具依赖关系、强制执行顺序、故障传播（上游故障块下游）、拓扑排序、循环检测、每个工作流执行跟踪、硬依赖关系与软依赖关系、组范围、通过 GET/POST/DELETE /admin/tool-deps
• 配额管理 -每个API密钥的每日/每周/每月严格上限-每任务或全局配额、呼叫或信用指标、突发津贴（临时超限百分比）、三项超限操作（拒绝/警告/节流）、基于UTC的期限边界（每日午夜、每周周一、每月1日）、自动期限展期，通过 GET/POST/DELETE /admin/quota-rules
• Webhook重播（DLQ） --失败的webhook交付的死信队列管理——使用完整的请求上下文（URL、标头、正文、HMAC签名）记录失败，重放单个或批量失败的交付，状态跟踪（待定→ 重试→ 成功/耗尽）、可配置的带超时的最大重试次数、按ID或状态清除、基于年龄的过期、通过管理 GET/POST/DELETE /admin/webhook-replay
• 配置配置文件 --带有保存/激活/回滚的命名配置预设--配置文件继承链（基本→ 子合并）、SHA-256校验和、用于比较的平面键差分（only InA/only InB/更改/未更改）、使用合并或替换模式导入/导出为JSON、激活历史、循环继承检测、通过管理 GET/POST/DELETE /admin/config-profiles
• 计划的报告 --通过webhook交付的自动定期使用、计费、合规性和安全报告——具有UTC周期边界的每日/每周/每月频率、HMAC-SHA256签名的有效载荷、命名空间/组/工具/密钥过滤器、具有交付跟踪的报告生成、可配置的超时、通过 POST /admin/scheduled-reports
• 审批工作流 --高成本或敏感工具调用的预执行批准门——三个条件（cost_threshold、带glob的tool_match、带前缀的key_match）、带可配置TTL的未决请求（默认1h）、批准/拒绝/过期生命周期、触发器计数、通过管理 POST /admin/approval-workflows
• 网关挂钩 --自定义逻辑的请求前/请求后生命周期挂钩——三个阶段（Pre_gate、Pre_backend、post_backend），四种类型（日志、header_inject、元数据标签、拒绝），基于优先级的执行管道，工具/密钥球过滤，拒绝短路处理，执行计数，通过管理 POST /admin/gateway-hooks
• 异常检测 — GET /admin/anomalies 识别异常模式：具有高拒绝率、快速信用耗尽、低剩余信用、严重性评级和详细描述的密钥
• 使用预测 — GET /admin/forecast 通过每个密钥的消耗估计、剩余通话、风险密钥识别、全系统消耗总量和每个工具的成本细分来预测未来的信贷消耗
• 合规报告 — GET /admin/compliance 生成合规就绪报告，其中包含关键治理（到期覆盖率）、访问控制（ACL/IP/支出限制覆盖率），审计跟踪完整性，加权总分和可操作建议
• SLA监控 — GET /admin/sla 跟踪服务级别指标：成功率、按原因划分的拒绝故障、每个工具的可用性和错误率、正常运行时间跟踪、按呼叫量排序
• 容量规划 — GET /admin/capacity 系统容量分析，包括信用消耗率、利用率、顶级消费者、每个命名空间细分和扩展建议
• 关键依赖关系图 — GET /admin/dependencies 工具到关键关系图，包括工具使用流行度、每个工具的唯一关键计数、每个关键工具列表以及使用/未使用的工具标识
• 工具延迟分析 — GET /admin/latency 每个工具的响应时间指标，包括平均/p95/min/最大持续时间、最慢工具排名和每个密钥的延迟细分
• 错误率趋势 — GET /admin/error-trends 拒绝率趋势，包括每个工具的错误率、拒绝原因细分、性能最差的工具和趋势方向
• 信贷流量分析 — GET /admin/credit-flow 信贷流入/流出分析，包括利用率、最高支出者和每种工具的支出明细
• 关键年龄分析 — GET /admin/key-age 密钥年龄分布，包括最旧/最新密钥、年龄段（24h/7d/30d/old）和最近创建的列表
• 命名空间使用情况摘要 — GET /admin/namespace-usage 每个命名空间的使用指标，包括信用分配、支出、呼叫计数和跨命名空间比较
• 审计总结 — GET /admin/audit-summary 审计事件分析，包括类型细分、主要参与者、最近事件和活动摘要
• 集团绩效 — GET /admin/group-performance 按组分析，包括关键计数、信用分配/支出、呼叫量、利用率和策略摘要
• 请求数量趋势 — GET /admin/request-trends 请求量、成功/失败计数、信用支出、平均持续时间和高峰时段识别的每小时时间序列
• 关键状态概述 — GET /admin/key-status 密钥状态仪表板，显示活动/暂停/撤销/过期计数和需要注意的密钥（低信用、接近到期）
• Webhook健康 — GET /admin/webhook-health webhook传递健康概述，包括成功率、挂起重试、死信数、暂停状态和缓冲事件
• 消费者洞察 — GET /admin/consumer-insights 对顶级消费者、最活跃的呼叫者、工具多样性和支出模式进行按关键行为分析
• 系统健康评分 — GET /admin/system-health 综合0-100健康评分，包括关键健康、错误率和信用利用率的加权分量细分
• 工具采用 — GET /admin/tool-adoption 每个工具的采用指标，包括唯一消费者、采用率、首次/最后一次出现的时间戳和使用排名
• 信贷效率 — GET /admin/credit-efficiency 信用分配效率，包括燃烧效率、浪费率、过度供应和供应不足的密钥检测
• 访问热图 — GET /admin/access-heatmap 每小时访问模式，包括工具细分、唯一消费者和高峰时段识别
• 关键流失分析 — GET /admin/key-churn 密钥流失指标，包括创建/撤销率、流失率和保留率，以及从未使用过的密钥检测
• 工具相关性 — GET /admin/tool-correlation 工具共现分析，显示哪些工具通常由同一消费者一起使用
• 消费者细分 — GET /admin/consumer-segmentation 将API关键消费者分为功率/常规/临时/休眠细分市场，并使用细分市场指标
• 信用分配 — GET /admin/credit-distribution 具有桶范围和中值计算的活动密钥信用余额直方图
• 响应时间分布 — GET /admin/response-time-distribution 具有延迟桶和p50/p95/p99百分位数的响应时间直方图
• 消费者终身价值 — GET /admin/consumer-lifetime-value 每个消费者的支出分析，包括价值等级、工具多样性和顶级消费者排名
• 工具收入排名 — GET /admin/tool-revenue 根据通话次数、唯一消费者和百分比细分消耗的总积分对工具进行排名
• 消费者保留队列 — GET /admin/consumer-retention 按创建日期、保留率和每个队列的平均支出对消费者进行分组
• 错误分解 — GET /admin/error-breakdown 按原因对拒绝的请求进行分类，包括计数、百分比、受影响的消费者和错误率
• 信贷利用率 — GET /admin/credit-utilization 显示具有利用率带和过度配置检测的活动密钥的利用率百分比
• 命名空间收入 — GET /admin/namespace-revenue 按命名空间划分的收入明细，包括支出、呼叫数、密钥数和百分比明细
• 集团收入 — GET /admin/group-revenue 按关键组划分的收入明细，包括支出、通话次数、关键次数和百分比明细
• 峰值使用时间 — GET /admin/peak-usage 按小时划分的流量模式，包括请求计数、信用、唯一消费者和高峰时段标识
• 消费者活动 — GET /admin/consumer-activity 每个消费者的活动指标，包括通话、支出、剩余信用、上次活动时间和活动/非活动状态
• 工具流行度 — GET /admin/tool-popularity 工具使用受欢迎程度，包括通话次数、信用、唯一消费者、百分比和最受欢迎的工具标识
• 信贷分配汇总 — GET /admin/credit-allocation 跨活动密钥的信用分配，包括级别细分（1-100、101-500、501+）、总计和平均分配
• 每日摘要 — GET /admin/daily-summary 每日汇总请求、花费的积分、新密钥、错误、独特消费者和趋势分析工具
• 关键排名 — GET /admin/key-ranking 活动密钥排行榜，按支出、通话或剩余积分进行排序，可配置排序
• 每小时交通量 — GET /admin/hourly-traffic 每小时的请求计数，包括允许/拒绝的细分、信用、消费者、工具和最繁忙的时间
• 刀具误差率 — GET /admin/tool-error-rate 每个工具的错误率，包括拒绝/允许的计数、错误百分比和整体可靠性指标
• 消费者支出速度 — GET /admin/consumer-spend-velocity 每个消费者的消费率，包括信用/小时、消耗预测和速度排名
• 命名空间活动 — GET /admin/namespace-activity 每个命名空间活动指标，包括多租户可见性的键计数、支出、调用、剩余信用
• 信贷消耗率 — GET /admin/credit-burn-rate 全系统信用消耗率，包括信用/小时、利用率、消耗预测
• 消费者风险评分 — GET /admin/consumer-risk-score 基于利用率和风险水平（低/中/高/关键）的每位消费者风险评分
• 收入预测 — GET /admin/revenue-forecast 预计收入，每小时/每天/每周/每月预测受剩余信用额度的限制
• 系统概述 — GET /admin/system-overview 包含关键计数、信用总额、利用率、活动指标的执行摘要
• 关键健康概述 — GET /admin/key-health-overview 包括利用率、状态级别、健康分布的整体按密钥健康检查
• 命名空间比较 — GET /admin/namespace-comparison 并行命名空间与分配、支出、利用率、领导者的比较
• 消费者增长 — GET /admin/consumer-growth 消费者增长指标，包括年龄、支出率、分配的信贷、新消费者数量
• 工具盈利能力 — GET /admin/tool-profitability 每个工具的盈利能力分析，包括收入、通话次数、每次通话的平均收入、唯一通话者
• 信用浪费分析 — GET /admin/credit-waste 每个关键信用浪费分析，包括利用率指标和浪费百分比
• 小组活动 — GET /admin/group-activity 每组活动指标，包括用于策略模板分析的关键计数、支出、通话、剩余信用
• 配置热重新加载 — POST /config/reload 无需重新启动服务器，即可从配置文件中重新加载定价、费率限制、Webhook、配额和行为标志
• Webhook事件 --将使用事件批处理到任何URL以进行外部计费/警报
• 配置文件模式 --从JSON文件加载所有设置(--config)
• 阴影模式 --在不强制付款的情况下记录所有内容（用于测试）
• 永久存储 --密钥、信用点、管理员密钥和组在重启后仍然有效 --state-file
• 零依赖 --没有外部npm包。仅使用Node.js内置。

用法

包装本地MCP服务器（stdio）

# Default: 1 credit per call, 60 calls/min, port 3402
npx paygate-mcp wrap --server "npx @modelcontextprotocol/server-filesystem /tmp"

# Custom pricing and limits
npx paygate-mcp wrap \
  --server "python my-server.py" \
  --price 2 \
  --rate-limit 30 \
  --port 8080

# Per-tool pricing
npx paygate-mcp wrap \
  --server "node server.js" \
  --tool-price "search:1,generate:5,premium_analyze:20"

# Shadow mode (observe without enforcing)
npx paygate-mcp wrap --server "node server.js" --shadow

网关远程MCP服务器（流式HTTP）

屏蔽任何支持以下功能的远程MCP服务器 可流式HTTP传输 （MCP规范2025-03-26）：

npx paygate-mcp wrap --remote-url "https://my-mcp-server.example.com/mcp"

# With custom pricing
npx paygate-mcp wrap \
  --remote-url "https://api.example.com/mcp" \
  --price 5 \
  --tool-price "gpt4:20,search:2"

代理处理：

• 通过HTTP POST进行JSON-RPC转发
• SSE（文本/事件流）响应解析
• Mcp-Session-Id 会话管理
• 优雅的会话清理（关闭时HTTP删除）

启动后，您将在控制台中看到您的管理员密钥。保存它。

多服务器模式

将多个MCP服务器封装在单个PayGate实例后面。工具前缀为服务器名称：

npx paygate-mcp wrap --config multi-server.json

示例 multi-server.json:

{
  "port": 3402,
  "defaultCreditsPerCall": 1,
  "servers": [
    {
      "prefix": "fs",
      "serverCommand": "npx",
      "serverArgs": ["@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    {
      "prefix": "github",
      "remoteUrl": "https://github-mcp.example.com/mcp"
    }
  ]
}

工具以前缀显示： fs:read_file, fs:write_file, github:search_repos等等。定价和ACL对前缀名称起作用：

{
  "toolPricing": {
    "github:search_repos": { "creditsPerCall": 5 },
    "fs:read_file": { "creditsPerCall": 1 }
  }
}

所有后台共享信用-一个API密钥适用于所有服务器。

客户端SDK

使用 PayGateClient 使用auto 402重试从TypeScript/Node.js调用工具：

import { PayGateClient, PayGateError } from 'paygate-mcp/client';

const client = new PayGateClient({
  url: 'http://localhost:3402',
  apiKey: 'pg_abc123...',
  autoRetry: true,
  onCreditsNeeded: async (info) => {
    // Called when credits run out — add credits and return true to retry
    await topUpCredits(info.creditsRequired);
    return true;
  },
});

const tools = await client.listTools();
const result = await client.callTool('search', { query: 'hello' });
const balance = await client.getBalance();

特征：

• 自动402重试：当工具调用返回所需付款时，调用 onCreditsNeeded 并重试
• 余额跟踪: client.lastKnownBalance 跟踪来自的学分 getBalance() 电话
• 键入错误: PayGateError 随着 .isPaymentRequired, .isRateLimited, .isExpired 助手
• 零依赖：使用内置的Node.js http/https

创建API密钥

curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "my-client", "credits": 100}'

呼叫工具

curl -X POST http://localhost:3402/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: CLIENT_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "read_file",
      "arguments": {"path": "/tmp/test.txt"}
    }
  }'

充值积分

curl -X POST http://localhost:3402/topup \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "credits": 500}'

检查余额（客户自助服务）

curl http://localhost:3402/balance \
  -H "X-API-Key: CLIENT_API_KEY"

返回积分、总花费、呼叫计数和上次使用的时间戳。客户无需管理员权限即可查看自己的余额。

导出使用数据（管理员）

# JSON export
curl http://localhost:3402/usage \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# CSV export (for spreadsheet/billing import)
curl "http://localhost:3402/usage?format=csv" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by date
curl "http://localhost:3402/usage?since=2025-01-01T00:00:00Z" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

返回每次调用的使用事件，包括工具名称、收取的点数和时间戳。API键在输出中被屏蔽。

检查状态

curl http://localhost:3402/status \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

返回活动密钥、使用统计数据、每个工具的细分和拒绝原因。

管理仪表盘

在浏览器中打开web仪表板：

http://localhost:3402/dashboard

用于管理密钥、查看使用情况和监视工具调用的实时管理UI。输入您的管理员密钥进行身份验证。具有每30秒自动刷新、顶级工具图表、活动提要和密钥创建/管理功能。

API 参考

免费方法

这些MCP方法无需授权或计费即可通过： initialize, initialized, ping, tools/list, resources/list, prompts/list

门控方法： tools/call （单）， tools/call_batch （批处理——全部或全部计费，并行执行）。看 批处理工具调用.

命令行命令

paygate-mcp wrap [options]             # Start a payment-gated MCP proxy
paygate-mcp init [--output] [--force]  # Interactive setup wizard
paygate-mcp validate --config 
   # Validate config without starting
paygate-mcp completions  # Generate shell completions
paygate-mcp version [--json]           # Print version

壳牌完井

# Bash
paygate-mcp completions bash > ~/.local/share/bash-completion/completions/paygate-mcp

# Zsh
paygate-mcp completions zsh > ~/.zfunc/_paygate-mcp
# Add to .zshrc: fpath=(~/.zfunc $fpath) && compinit

# Fish
paygate-mcp completions fish > ~/.config/fish/completions/paygate-mcp.fish

机器可读输出

# Version as JSON (for CI/CD)
paygate-mcp version --json
# → {"version":"10.3.0"}

# Validate config with structured output
paygate-mcp validate --config paygate.json --json
# → {"valid":true,"diagnostics":[...],"errors":0,"warnings":0}

CLI选项

--server        MCP server command to wrap via stdio
--remote-url    Remote MCP server URL (Streamable HTTP transport)
--port            HTTP port (default: 3402)
--price           Default credits per tool call (default: 1)
--rate-limit      Max calls/min per key (default: 60, 0=unlimited)
--name            Server display name
--shadow             Shadow mode — log without enforcing payment
--admin-key       Set admin key (default: auto-generated)
--tool-price    Per-tool price (e.g. "search:5,generate:10")
--import-key    Import existing key with credits (e.g. "pg_abc:100")
--state-file 
  Persist keys/credits to a JSON file (survives restarts)
--stripe-secret   Stripe webhook signing secret (enables /stripe/webhook)
--webhook-url   POST batched usage events to this URL
--webhook-secret  HMAC-SHA256 secret for signing webhook payloads
--refund-on-failure  Refund credits when downstream tool call fails
--redis-url     Redis URL for distributed state (e.g. "redis://localhost:6379")
--config 
      Load settings from a JSON config file
--discovery    Tool discovery mode: static (default) or dynamic
--json               Machine-readable JSON output

注： 使用 --server 或 --remote-url 对于单服务器模式。使用 servers 在多服务器模式的配置文件中。

动态工具发现

对于具有许多工具的服务器，动态发现模式通过公开3个元工具而不是完整的工具列表来减少代理上下文窗口的膨胀：

npx paygate-mcp wrap --server "your-server" --discovery dynamic

代理人看到3个工具： paygate_list_tools （分页列表）， paygate_search_tools （关键字搜索），以及 paygate_call_tool （代理任何工具）。这将上下文窗口中的N个工具减少到3个，同时保留了全部功能。

永久存储

添加 --state-file 将API密钥和信用保存到磁盘。数据在服务器重启后仍然有效。

npx paygate-mcp wrap --server "your-mcp-server" --state-file ~/.paygate/state.json

条纹集成

连接Stripe可在客户付款时自动充值积分：

npx paygate-mcp wrap \
  --server "your-mcp-server" \
  --state-file ~/.paygate/state.json \
  --stripe-secret "whsec_your_stripe_webhook_secret"

设置：

1. 使用元数据创建条纹结账会话：

- paygate_api_key -客户的API密钥（例如。 pg_abc123...) - paygate_credits --在付款时增加信用（例如。 500)

1. 将您的Stripe webhook指向 https://your-server/stripe/webhook
2. 订阅 checkout.session.completed 和 invoice.payment_succeeded 事件

当客户完成付款时，信用将自动添加到他们的API密钥中。订阅在每个计费周期自动续订积分。

安全：

• HMAC-SHA256签名验证（Stripe的v1方案）
• 定时安全比较，防止定时攻击
• 5分钟时间戳容差，防止重放攻击
• 付款状态验证（仅限 paid 触发信用）
• 零依赖——使用内置的Node.js crypto

每个工具ACL（访问控制）

控制每个API密钥可以访问哪些工具：

# Create a key that can only access search and read tools
curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "limited-client", "credits": 100, "allowedTools": ["search", "read_file"]}'

# Create a key with specific tools blocked
curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "safe-client", "credits": 100, "deniedTools": ["delete_file", "admin_reset"]}'

# Update ACL on an existing key
curl -X POST http://localhost:3402/keys/acl \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "allowedTools": ["search"], "deniedTools": ["admin"]}'

• 允许的工具 （白名单）：只有这些工具是可访问的。空=所有工具。
• 拒绝工具 （黑名单）：这些工具总是被拒绝。在允许的工具后使用。
• ACL也过滤 tools/list --客户只能看到他们允许的工具。

每工具速率限制

为每个工具设置独立的速率限制（在全局限制之上）：

{
  "toolPricing": {
    "expensive_analyze": { "creditsPerCall": 10, "rateLimitPerMin": 5 },
    "search": { "creditsPerCall": 1, "rateLimitPerMin": 30 },
    "cheap_read": { "creditsPerCall": 1 }
  }
}

每个API密钥独立执行Per-tool限制。一个密钥在访问其他工具时，可以在一个工具上进行速率限制。全球 --rate-limit 适用于所有工具。

密钥过期（TTL）

创建自动导出的API密钥：

# Create a key that expires in 1 hour (3600 seconds)
curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "trial-user", "credits": 50, "expiresIn": 3600}'

# Create a key with a specific expiry date
curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "quarterly", "credits": 1000, "expiresAt": "2026-06-01T00:00:00Z"}'

# Set or extend expiry on an existing key
curl -X POST http://localhost:3402/keys/expiry \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "expiresIn": 86400}'

# Remove expiry (key never expires)
curl -X POST http://localhost:3402/keys/expiry \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "expiresAt": null}'

过期的密钥返回清除 api_key_expired 错误。管理员可以随时延长或删除到期时间。

贷记转账

API密钥之间的原子传输信用：

curl -X POST http://localhost:3402/keys/transfer \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "pg_source_key", "to": "pg_dest_key", "credits": 500, "memo": "Monthly allocation" }'

答复：

{
  "transferred": 500,
  "from": { "keyMasked": "pg_sour...key1", "balance": 500 },
  "to": { "keyMasked": "pg_dest...key2", "balance": 700 },
  "memo": "Monthly allocation",
  "message": "Transferred 500 credits"
}

验证： 这两个密钥都必须存在，处于活动状态（未被撤销/过期），并且源必须具有足够的信用。分数学分被降为整数。自助转账被拒绝。

审计跟踪： 每次传输都会记录一个 key.credits_transferred 使用掩码键、金额、余额和备忘录的审计事件。

批量密钥操作

在单个请求中执行多个关键操作（创建、充值、撤销）。失败的操作不会阻止后续的操作——每个结果都包括成功状态和索引，以便于关联。

curl -X POST http://localhost:3402/keys/bulk \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "action": "create", "name": "api-key-1", "credits": 500, "tags": { "env": "prod" } },
      { "action": "create", "name": "api-key-2", "credits": 200 },
      { "action": "topup", "key": "pg_existing_key", "credits": 1000 },
      { "action": "revoke", "key": "pg_old_key" }
    ]
  }'

答复：

{
  "total": 4,
  "succeeded": 4,
  "failed": 0,
  "results": [
    { "index": 0, "action": "create", "success": true, "result": { "key": "pg_abc...", "name": "api-key-1", "credits": 500 } },
    { "index": 1, "action": "create", "success": true, "result": { "key": "pg_def...", "name": "api-key-2", "credits": 200 } },
    { "index": 2, "action": "topup", "success": true, "result": { "creditsAdded": 1000, "newBalance": 1500 } },
    { "index": 3, "action": "revoke", "success": true, "result": { "message": "Key revoked" } }
  ]
}

行动： create （可选名称、学分、标签、命名空间、allowdTools、deniedTools）， topup （关键+学分）， revoke （关键）。未知操作在不停止批处理的情况下返回错误结果。

限制： 每个请求最多100个操作。空操作数组返回400。

审计跟踪： 每个成功的操作都会记录一个带有“（批量）”后缀的单独审计事件。

关键导入/导出

导出所有API密钥，以便在PayGate实例之间进行备份或迁移：

# Export as JSON (includes full key secrets)
curl http://localhost:3402/keys/export \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -o paygate-keys-backup.json

# Export as CSV
curl "http://localhost:3402/keys/export?format=csv" \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -o paygate-keys-backup.csv

# Export only active keys in a specific namespace
curl "http://localhost:3402/keys/export?activeOnly=true&namespace=production" \
  -H "X-Admin-Key: $ADMIN_KEY"

将密钥导入PayGate实例：

curl -X POST http://localhost:3402/keys/import \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": [{ "key": "pg_abc123...", "name": "my-key", "credits": 500, "active": true, "tags": {} }],
    "mode": "skip"
  }'

答复：

{
  "total": 1,
  "imported": 1,
  "overwritten": 0,
  "skipped": 0,
  "errors": 0,
  "mode": "skip",
  "results": [{ "key": "pg_abc123...", "name": "my-key", "status": "imported" }]
}

冲突模式： skip （默认）--跳过已经存在的键， overwrite --替换现有密钥， error --重复密钥失败。

限制： 每个导入请求最多1000个密钥。密钥必须以开头 pg_ 前缀。

导出格式： JSON（包含所有字段的完整记录）或CSV（电子表格使用的关键子集）。

支出限额

限制任何API密钥可以花费的总信用：

# Set a spending limit on a key (admin only)
curl -X POST http://localhost:3402/limits \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "spendingLimit": 500}'

# Check remaining budget
curl http://localhost:3402/balance -H "X-API-Key: CLIENT_API_KEY"
# → { "spendingLimit": 500, "remainingBudget": 350, ... }

集 spendingLimit 到 0 无限制。当一个键达到其极限时，工具调用将被拒绝，并显示一个明显的错误。

失败退款

当下游工具调用失败时自动返回积分：

npx paygate-mcp wrap --server "node server.js" --refund-on-failure

在工具调用之前扣除积分。如果包装好的服务器返回错误，则退还积分 totalSpent / totalCalls 被回滚。防止因操作失败而向用户收费。

Webhook事件

将使用事件POST到任何外部URL以进行计费、警报或分析：

npx paygate-mcp wrap --server "node server.js" --webhook-url "https://billing.example.com/events"

事件被分批处理（每次POST最多10个），每5秒刷新一次。每个事件包括工具名称、收取的信用、API密钥和时间戳。

重试队列和死信

失败的webhook交付将以指数回退方式重试（1秒、2秒、4秒、8秒、16秒——最多可配置为 --webhook-retries 尝试）。在所有重试尝试结束后，事件将移动到死信队列供管理员检查。

# Custom max retries (default: 5)
npx paygate-mcp wrap --server "node server.js" \
  --webhook-url "https://billing.example.com/events" \
  --webhook-retries 10

管理端点：

重试尝试包括 X-PayGate-Retry 带有可观察性尝试号的标头。

Webhook事件回放

从死信队列中回放永久失败的webhook事件：

# Replay all dead letter entries
curl -X POST http://localhost:3402/webhooks/replay \
  -H "X-Admin-Key: $ADMIN_KEY"

# Replay specific entries by index
curl -X POST http://localhost:3402/webhooks/replay \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "indices": [0, 2, 5] }'

重播的条目将从死信队列中删除，并重新排队等待新的投递（尝试计数器重置为0）。如果传递再次失败，它们将遵循正常的重试/死信流程。

Webhook签名（HMAC-SHA256）

对webhook有效负载进行签名以进行防篡改交付：

npx paygate-mcp wrap --server "node server.js" \
  --webhook-url "https://billing.example.com/events" \
  --webhook-secret "whsec_your_secret_here"

当 --webhook-secret 设置后，每个webhook POST都包含一个 X-PayGate-Signature 头球

X-PayGate-Signature: t=1709123456,v1=a1b2c3d4...

验证签章 （Node.js示例）：

import { WebhookEmitter } from 'paygate-mcp';

const signature = req.headers['x-paygate-signature'];
const [tPart, v1Part] = signature.split(',');
const timestamp = tPart.split('=')[1];
const sig = v1Part.split('=')[1];

// Reconstruct signed payload: timestamp.body
const signedPayload = `${timestamp}.${rawBody}`;
const isValid = WebhookEmitter.verify(signedPayload, sig, 'whsec_your_secret_here');

签名涵盖 timestamp.body 以防止重放攻击。使用定时安全比较（内置于 WebhookEmitter.verify).

管理员生命周期事件

启用webhook后，管理员操作还会触发webhook事件：

管理员事件出现在 adminEvents webhook有效负载数组（与使用情况分开 events).这两个数组可以存在于同一批中。

Webhook筛选器（事件路由）

根据事件类型和API密钥前缀将webhook事件路由到不同的目的地。每个筛选规则都使用独立的重试队列、死信队列和可选的签名密钥将匹配的事件路由到自己的URL。

创建筛选规则：

curl -X POST http://localhost:3402/webhooks/filters \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-alerts",
    "events": ["key.created", "key.revoked", "alert.fired"],
    "url": "https://alerts.example.com/webhook",
    "secret": "whsec_alerts_secret",
    "keyPrefixes": ["pk_prod_"],
    "active": true
  }'

列表筛选器：

curl http://localhost:3402/webhooks/filters -H "X-Admin-Key: $ADMIN_KEY"

更新筛选器：

curl -X POST http://localhost:3402/webhooks/filters/update \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "wf_abc123", "active": false }'

删除筛选器：

curl -X POST http://localhost:3402/webhooks/filters/delete \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "wf_abc123" }'

筛选规则：

• events --要匹配的事件类型数组（精确匹配或 "*" 所有事件的通配符）
• keyPrefixes -API密钥前缀的可选阵列（例如。， ["pk_prod_"]).只有当关联的键以这些前缀之一开头时，事件才会匹配。省略所有按键。
• url --匹配事件的目标URL（每个唯一的URL都有自己的重试队列）
• secret --此目标的可选HMAC-SHA256签名密钥
• active --启用/禁用筛选器而不删除它

路由行为：

• 将与筛选器规则匹配的事件发送到筛选器的目标URL
• 默认的webhook URL（如果已配置）始终接收所有事件（向后兼容）
• 多个过滤器可以匹配同一事件——它被发送到所有匹配的目的地
• 路由过程中跳过非活动筛选器

配置文件：

{
  "webhookUrl": "https://billing.example.com/events",
  "webhookFilters": [
    {
      "name": "production-alerts",
      "events": ["key.created", "key.revoked", "alert.fired"],
      "url": "https://alerts.example.com/webhook",
      "keyPrefixes": ["pk_prod_"]
    }
  ]
}

统计数据： GET /webhooks/stats 包括所有筛选器目标以及默认端点的每个URL传递统计信息。

使用配额

根据API键设置每日或每月使用限制：

# Create a key with 10 calls/day, 200 calls/month
curl -X POST http://localhost:3402/keys \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "metered-user", "credits": 1000, "quota": {"dailyCallLimit": 10, "monthlyCallLimit": 200}}'

# Set credit-based quotas (max 50 credits/day)
curl -X POST http://localhost:3402/keys/quota \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "dailyCreditLimit": 50}'

# Remove per-key quota (fall back to global defaults)
curl -X POST http://localhost:3402/keys/quota \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "CLIENT_API_KEY", "remove": true}'

配额类型： dailyCallLimit, monthlyCallLimit, dailyCreditLimit, monthlyCreditLimit。设置为0表示无限制。计数器在UTC午夜（每天）和UTC月边界（每月）重置。在配置文件中设置全局默认值 globalQuota.

动态定价

根据输入参数大小收取额外积分：

{
  "toolPricing": {
    "analyze_text": { "creditsPerCall": 2, "creditsPerKbInput": 5 },
    "search": { "creditsPerCall": 1 }
  }
}

对于 analyze_text，3 KB的输入将花费 2 + ceil(3 × 5) = 17 信用。小输入四舍五入至少为1KB。无工具 creditsPerKbInput 使用固定基础价格。

OAuth 2.1

MCP客户端的完整OAuth 2.1授权服务器。实现PKCE、动态客户端注册、令牌刷新和撤销。

在配置中启用OAuth：

{
  "oauth": {
    "accessTokenTtl": 3600,
    "refreshTokenTtl": 2592000,
    "scopes": ["tools:*", "tools:read", "tools:write"]
  }
}

全流量：

# 1. Register an OAuth client
curl -X POST http://localhost:3402/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My Agent", "redirect_uris": ["http://localhost:8080/callback"], "api_key": "pg_..."}'

# 2. Generate PKCE challenge (code_verifier → SHA256 → base64url)
# 3. Authorize: GET /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&code_challenge=...&code_challenge_method=S256
# 4. Exchange code for tokens
curl -X POST http://localhost:3402/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "...", "client_id": "...", "redirect_uri": "...", "code_verifier": "..."}'

# 5. Use Bearer token on /mcp
curl -X POST http://localhost:3402/mcp \
  -H "Authorization: Bearer pg_at_..." \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search", "arguments": {"query": "hello"}}}'

# 6. Refresh token
curl -X POST http://localhost:3402/oauth/token \
  -d '{"grant_type": "refresh_token", "refresh_token": "pg_rt_...", "client_id": "..."}'

OAuth令牌由API密钥支持-每个令牌映射到一个API密钥以进行计费。这 /mcp 端点接受两者 X-API-Key 和 Authorization: Bearer 标题。

SSE流媒体（MCP流媒体HTTP）

PayGate实现了具有SSE支持的完整MCP流式HTTP传输：

# POST /mcp with SSE response (add Accept header)
curl -N -X POST http://localhost:3402/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"analyze","arguments":{}}}'
# Response: SSE stream with event: message + data: {jsonrpc response}

# GET /mcp — Open SSE notification stream
curl -N http://localhost:3402/mcp \
  -H "Accept: text/event-stream" \
  -H "Mcp-Session-Id: mcp_sess_..."
# Receives server-initiated notifications as SSE events

# DELETE /mcp — Terminate session
curl -X DELETE http://localhost:3402/mcp \
  -H "Mcp-Session-Id: mcp_sess_..."

会话管理：

• 岗位 /mcp 响应包括 Mcp-Session-Id 头球
• 客户端通过发送来重用会话 Mcp-Session-Id 后续请求
• 获取 /mcp 为服务器到客户端的通知打开一个长期的SSE连接
• 删除 /mcp 终止会话并关闭所有SSE连接
• 会话在30分钟不活动后自动过期

运输方式：

• POST /mcp 没有 Accept: text/event-stream → 标准JSON响应（向后兼容）
• POST /mcp 随着 Accept: text/event-stream → SSE封装JSON-RPC响应
• GET /mcp 随着 Accept: text/event-stream → 长期通知流

审计日志

每一项重要操作都记录在结构化的审计跟踪中：

# Query audit events (with filtering)
curl http://localhost:3402/audit?types=key.created,gate.deny&limit=50 \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Export full audit log as CSV
curl http://localhost:3402/audit/export?format=csv \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" > audit.csv

# Get audit statistics
curl http://localhost:3402/audit/stats \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

跟踪事件： key.created, key.revoked, key.topup, key.acl_updated, key.expiry_updated, key.quota_updated, key.limit_updated, key.tags_updated, key.ip_updated, gate.allow, gate.deny, session.created, session.destroyed, oauth.client_registered, oauth.token_issued, oauth.token_revoked, admin.auth_failed, admin.alerts_configured, billing.refund, team.created, team.updated, team.deleted, team.key_assigned, team.key_removed.

保留： 环形缓冲区（默认10000个事件）、基于年龄的清理（默认30天）、自动定期执行。

注册/发现（代理可发现定价）

AI代理可以在调用工具之前以编程方式发现服务器的定价和支付要求。与2007年9月（MCP付款规范草案）一致。

# Discover server payment metadata (public, no auth)
curl http://localhost:3402/.well-known/mcp-payment
# → { "specVersion": "2007-draft", "billingModel": "credits", "defaultCreditsPerCall": 1, ... }

# Get full pricing breakdown (public, no auth)
curl http://localhost:3402/pricing
# → { "server": {...}, "tools": [{ "name": "search", "creditsPerCall": 5, "pricingModel": "dynamic" }, ...] }

它是如何工作的：

• /.well-known/mcp-payment --服务器级支付元数据（计费模型、身份验证方法、错误代码）
• /pricing --每个工具的完整定价明细，包括覆盖
• tools/list 回应包括 _pricing 每个工具的元数据（creditsPerCall、pricingModel、rateLimitPerMin）
• -32402 错误响应包括定价细节，以便代理知道如何负担得起该工具

两个发现端点都是 公共 （不需要身份验证），因此代理可以在获取API密钥之前检查定价。

普罗米修斯指标

使用任何兼容Prometheus的监控系统监控您的PayGate服务器：

curl http://localhost:3402/metrics

以标准Prometheus文本展示格式返回指标：

# HELP paygate_tool_calls_total Total tool calls processed
# TYPE paygate_tool_calls_total counter
paygate_tool_calls_total{status="allowed",tool="search"} 42
paygate_tool_calls_total{status="denied",tool="premium"} 3

# HELP paygate_credits_charged_total Total credits charged
# TYPE paygate_credits_charged_total counter
paygate_credits_charged_total{tool="search"} 210

# HELP paygate_active_keys_total Number of active (non-revoked) API keys
# TYPE paygate_active_keys_total gauge
paygate_active_keys_total 5

# HELP paygate_uptime_seconds Server uptime in seconds
# TYPE paygate_uptime_seconds gauge
paygate_uptime_seconds 3600

可用指标：

• paygate_tool_calls_total{tool,status} --工具调用（允许/拒绝）
• paygate_credits_charged_total{tool} --按工具收取的积分
• paygate_denials_total{reason} --理由拒绝（信用不足、利率受限等）
• paygate_rate_limit_hits_total{tool} --每个工具的点击率限制
• paygate_refunds_total{tool} --每个工具的信用退款
• paygate_http_requests_total{method,path,status} --HTTP请求
• paygate_active_keys_total -活动API键（仪表）
• paygate_active_sessions_total --活动MCP会话（仪表）
• paygate_total_credits_available --所有密钥的总学分（衡量标准）
• paygate_uptime_seconds --服务器正常运行时间（仪表）

这 /metrics 端点是 公共 （无需身份验证），便于普罗米修斯抓取。

密钥克隆

使用与现有密钥相同的配置创建一个新的API密钥，但使用新计数器。非常适合为团队成员、临时环境或批量密钥创建提供类似密钥：

# Clone with same config and credits
curl -X POST http://localhost:3402/keys/clone \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_source..."}'
# → { "message": "Key cloned", "key": "pg_newkey...", "name": "source-clone", "credits": 200, ... }

# Clone with overrides
curl -X POST http://localhost:3402/keys/clone \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_source...", "name": "staging-key", "credits": 50, "namespace": "staging"}'

什么被克隆： allowdTools、deniedTools、expiresAt、配额、标记、ipAllowlist、命名空间、组、spendingLimit、autoTopup配置。 重置内容： totalSpend、totalCalls、lastUsedAt、每日通话、挂起状态。您可以覆盖 name, credits, tags，以及 namespace 在克隆请求中。可以克隆已挂起和过期的密钥（但不能复制已吊销的密钥）。

关键点旋转

在不丢失信用、ACL、配额或开支限制的情况下旋转API密钥：

curl -X POST http://localhost:3402/keys/rotate \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_oldkey..."}'
# → { "message": "Key rotated", "newKey": "pg_newkey...", "name": "my-key", "credits": 500 }

旧密钥立即失效。所有状态（信用、总花费、总调用、ACL、配额、到期、支出限制）都转移到新密钥。将其用于定期密钥轮换策略、受损密钥响应或密钥迁移。

关键暂停和恢复

暂时禁用API密钥而不永久吊销它。挂起的密钥在门口被拒绝(key_suspended 原因），但管理操作（充值、ACL、配额、标签等）仍然有效——这使其成为调查滥用、暂停计费或临时锁定的理想选择：

# Suspend a key (with optional reason for audit trail)
curl -X POST http://localhost:3402/keys/suspend \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_abc123...", "reason": "investigating abuse"}'
# → { "message": "Key suspended", "suspended": true }

# Resume a suspended key
curl -X POST http://localhost:3402/keys/resume \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_abc123..."}'
# → { "message": "Key resumed", "suspended": false }

暂停与撤销：

• 暂停 --可逆。钥匙仍然有效，但在门口被拒绝。管理操作仍然有效。用于临时锁定。
• 撤销 --永久。密钥已停用，无法恢复。用于泄露或停用的密钥。

悬架火灾 key.suspended 和 key.resumed 审计事件和webhook通知。阴影模式允许挂起的按键通过（ shadow:key_suspended 原因）进行测试。

按密钥使用

获取特定API密钥的详细使用情况细分-每小时统计数据、每小时时间序列、拒绝原因和最近事件：

# Get full usage for a key
curl http://localhost:3402/keys/usage?key=pg_abc123... \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by time (ISO 8601)
curl "http://localhost:3402/keys/usage?key=pg_abc123...&since=2025-01-01T00:00:00Z" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

答复包括：

适用于活动密钥、挂起密钥和过期密钥。可用于调试、计费审核和按客户分析。

Webhook测试

向配置的webhook URL发送测试事件以验证连接，而不生成真实事件：

# Send test event
curl -X POST http://localhost:3402/webhooks/test \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# With custom message
curl -X POST http://localhost:3402/webhooks/test \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"message": "Testing from staging deploy"}'

答复：

测试活动包括 X-PayGate-Test: 1 标题和 X-PayGate-Signature 当配置webhook密钥时。如果未配置webhook URL，则返回400。创建审计跟踪条目(webhook.test).

Webhook交付日志

查询所有webhook传递尝试的日志——成功、失败和重试：

# Get recent deliveries (default: last 50, newest first)
curl http://localhost:3402/webhooks/log \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by success/failure
curl "http://localhost:3402/webhooks/log?success=false" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Filter by time and limit
curl "http://localhost:3402/webhooks/log?since=2025-01-01T00:00:00Z&limit=10" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

每个条目包括：

查询参数： limit （默认50，最大200）， since （ISO 8601）， success (true 或 false).内存中的条目上限为500。搭配使用 /webhooks/stats 对于聚合计数器。

Webhook暂停/恢复

在维护窗口期间暂时停止webhook交付。事件会被缓冲（不会丢失）并在恢复时刷新：

# Pause delivery
curl -X POST http://localhost:3402/webhooks/pause \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Check pause status (visible in /webhooks/stats)
curl http://localhost:3402/webhooks/stats \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"
# → { "paused": true, "pausedAt": "2025-...", "bufferedEvents": 12, ... }

# Resume delivery (flushes buffered events)
curl -X POST http://localhost:3402/webhooks/resume \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"
# → { "paused": false, "flushedEvents": 12 }

暂停时，事件继续在缓冲区中累积。恢复时，所有缓冲的事件都会立即刷新。暂停状态和缓冲事件计数在中可见 /webhooks/stats。创建审计跟踪条目(webhook.pause, webhook.resume).

关键别名

为API密钥分配可人工修改的别名，以便您可以按名称引用它们，而不是在管理端点中使用不透明的密钥ID：

# Set an alias
curl -X POST http://localhost:3402/keys/alias \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "pg_abc123...", "alias": "prod-backend"}'
# → { "key": "pg_abc12...", "alias": "prod-backend", "message": "Alias set to \"prod-backend\"" }

# Use the alias in any admin endpoint
curl -X POST http://localhost:3402/topup \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "prod-backend", "credits": 500}'

curl -X POST http://localhost:3402/keys/suspend \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "prod-backend", "reason": "maintenance"}'

curl -X POST http://localhost:3402/keys/transfer \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"from": "prod-backend", "to": "staging-api", "credits": 100}'

# Clear an alias
curl -X POST http://localhost:3402/keys/alias \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"key": "prod-backend", "alias": null}'

密钥过期扫描程序

主动式后台扫描程序，可检测即将到期的API密钥，并在其到期前发送webhook通知-即使密钥未被积极使用：

# Query keys expiring within 24 hours (default)
curl http://localhost:3402/keys/expiring \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"
# → { "within": 86400, "count": 2, "scanner": { ... }, "keys": [ ... ] }

# Query keys expiring within 7 days
curl http://localhost:3402/keys/expiring?within=604800 \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

在配置文件中配置扫描仪：

{
  "expiryScanner": {
    "enabled": true,
    "intervalSeconds": 3600,
    "thresholds": [604800, 86400, 3600]
  }
}

键盘模板

API密钥创建的命名模板。定义可重复使用的预设并使用创建密钥 template: "free-tier":

# Create a template
curl -X POST http://localhost:3402/keys/templates \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{
    "name": "free-tier",
    "description": "Free plan with basic access",
    "credits": 50,
    "allowedTools": ["search", "read"],
    "deniedTools": ["admin"],
    "tags": {"plan": "free"},
    "namespace": "public",
    "expiryTtlSeconds": 2592000,
    "spendingLimit": 200
  }'

# List all templates
curl http://localhost:3402/keys/templates \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Create a key from template (inherits all defaults)
curl -X POST http://localhost:3402/keys \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "new-user", "template": "free-tier"}'

# Create a key from template with overrides
curl -X POST http://localhost:3402/keys \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "vip-user", "template": "free-tier", "credits": 500, "tags": {"plan": "vip"}}'

# Delete a template
curl -X POST http://localhost:3402/keys/templates/delete \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -d '{"name": "free-tier"}'

环境变量配置

通过配置所有内容 PAYGATE_* 环境变量——Docker、Kubernetes和CI/CD部署的理想选择：

# Docker example
docker run -e PAYGATE_SERVER="node /app/server.js" \
  -e PAYGATE_PORT=8080 \
  -e PAYGATE_PRICE=5 \
  -e PAYGATE_ADMIN_KEY=sk-admin-secret \
  -e PAYGATE_REDIS_URL=redis://redis:6379 \
  -e PAYGATE_WEBHOOK_URL=https://hooks.example.com/billing \
  -p 8080:8080 node:20 npx paygate-mcp wrap

# Or use a config file via env var
docker run -e PAYGATE_CONFIG=/etc/paygate/config.json \
  -v ./config.json:/etc/paygate/config.json \
  -p 3402:3402 node:20 npx paygate-mcp wrap

所有18个支持的环境变量：

优先： CLI标志>环境变量>配置文件>默认值。这意味着您可以通过Docker中的env变量设置默认值，并在命令行上覆盖特定值。

请求ID跟踪

每个HTTP响应都包含一个 X-Request-Id 用于分布式跟踪的标头。如果传入请求具有 X-Request-Id 头（例如，来自负载平衡器或API网关），它被传播通过。否则，将自动生成一个新的ID，格式为 req_.

# Auto-generated request ID
curl -v http://localhost:3402/health
# 50%（最低3次以上呼叫）、信用消耗快（花费>=75%）和剩余信用低（\=75%）或耗尽密钥的扩展建议。只读。

### 关键依赖关系图

curl http://localhost:3000/admin/dependencies -H "X-Admin-Key: YOUR_ADMIN_KEY"

{ "summary": { "totalTools": 5, "usedTools": 3, "unusedTools": 2 }, "toolUsage": [ { "tool": "search", "totalCalls": 150, "uniqueKeys": 8 }, { "tool": "translate", "totalCalls": 45, "uniqueKeys": 3 } ], "keyToolMap": [ { "keyName": "power-user", "tools": ["search", "translate", "summarize"], "toolCount": 3 }, { "keyName": "basic-user", "tools": ["search"], "toolCount": 1 } ], "generatedAt": "2025-01-15T14:30:00Z" }

工具到密钥关系图：显示每个密钥使用的工具、按总调用数排名的工具流行度、每个工具的唯一密钥计数，并标识孤立的工具（可用但未使用）。有助于理解工具的采用和修剪未使用的功能。只读。

### 工具延迟分析

curl http://localhost:3000/admin/latency -H "X-Admin-Key: YOUR_ADMIN_KEY"

{ "summary": { "totalCalls": 200, "avgDurationMs": 45, "minDurationMs": 8, "maxDurationMs": 312, "p95DurationMs": 120 }, "byTool": [ { "tool": "translate", "totalCalls": 80, "avgDurationMs": 65, "minDurationMs": 20, "maxDurationMs": 312, "p95DurationMs": 150 }, { "tool": "search", "totalCalls": 120, "avgDurationMs": 32, "minDurationMs": 8, "maxDurationMs": 95, "p95DurationMs": 78 } ], "slowestTools": [ { "tool": "translate", "avgDurationMs": 65, "totalCalls": 80 } ], "byKey": [ { "keyName": "heavy-user", "totalCalls": 150, "avgDurationMs": 48, "minDurationMs": 8, "maxDurationMs": 312 } ], "generatedAt": "2025-01-15T14:30:00Z" }

每个工具的响应时间指标：每个工具的平均持续时间、p95、最小持续时间和最大持续时间，按最慢的平均时间、前10个最慢的工具排名、每个键的延迟细分和全局摘要排序。只计算成功（允许）的呼叫。只读。

### 错误率趋势

curl http://localhost:3000/admin/error-trends -H "X-Admin-Key: YOUR_ADMIN_KEY"

{ "summary": { "totalCalls": 500, "totalDenials": 45, "overallErrorRate": 9, "trend": "improving" }, "byTool": [ { "tool": "translate", "totalCalls": 200, "denials": 30, "errorRate": 15 }, { "tool": "search", "totalCalls": 300, "denials": 15, "errorRate": 5 } ], "denialReasons": [ { "reason": "insufficient_credits", "count": 30 }, { "reason": "rate_limited", "count": 15 } ], "generatedAt": "2025-01-15T14:30:00Z" }

拒绝率趋势：总体错误率、按表现最差、拒绝原因细分和趋势方向排序的每个工具的错误率（根据上半年与下半年的比较进行改进/降级/稳定）。只读。

### 信贷流量分析

curl http://localhost:3000/admin/credit-flow -H "X-Admin-Key: YOUR_ADMIN_KEY"

{ "summary": { "totalAllocated": 10000, "totalSpent": 3500, "totalRemaining": 6500, "utilizationPct": 35 }, "topSpenders": [ { "keyName": "heavy-user", "creditsSpent": 2000, "creditsRemaining": 500, "callCount": 200 } ], "byTool": [ { "tool": "search", "creditsSpent": 2000, "callCount": 400 }, { "tool": "translate", "creditsSpent": 1500, "callCount": 150 } ], "generatedAt": "2025-01-15T14:30:00Z" }

信贷流入/流出分析：分配的总信贷（初始+支出）与支出与剩余信贷、利用率、按消耗的信贷排名的前10名支出者，以及按收入排序的每个工具支出明细。只读。

### 关键年龄分析

curl http://localhost:3000/admin/key-age -H "X-Admin-Key: YOUR_ADMIN_KEY"

{ "summary": { "totalKeys": 15, "avgAgeHours": 168.5, "oldestKey": { "keyName": "legacy", "ageHours": 720, "createdAt": "2025-01-01T00:00:00Z" }, "newestKey": { "keyName": "fresh", "ageHours": 0.5, "createdAt": "2025-01-31T12:00:00Z" } }, "distribution": { "last24h": 3, "last7d": 5, "last30d": 4, "older": 3 }, "recentlyCreated": [ { "keyName": "fresh", "ageHours": 0.5, "createdAt": "2025-01-31T12:00:00Z" } ], "generatedAt": "2025-01-31T12:30:00Z" }

密钥年龄分布：所有活动密钥的平均年龄、最旧/最新密钥标识、年龄段（最后24h/7d/30d/old）和最近创建的列表（最新优先，前10名）。只读。

### 命名空间使用情况摘要

curl http://localhost:3000/admin/namespace-usage -H "X-Admin-Key: YOUR_ADMIN_KEY"

{ "summary": { "totalNamespaces": 3 }, "namespaces": [ { "namespace": "prod", "keyCount": 5, "totalAllocated": 5000, "totalSpent": 2000, "totalRemaining": 3000, "totalCalls": 400, "utilizationPct": 40 }, { "namespace": "staging", "keyCount": 2, "totalAllocated": 1000, "totalSpent": 200, "totalRemaining": 800, "totalCalls": 40, "utilizationPct": 20 } ], "generatedAt": "2025-01-15T14:30:00Z" }

每个命名空间使用指标：密钥计数、信用分配/支出/剩余、调用计数和利用率百分比。按支出排序（最高优先）。没有名称空间的键显示在“默认”下。只读。

### 审计总结

curl http://localhost:3000/admin/audit-summary -H "X-Admin-Key: YOUR_ADMIN_KEY"

{ "summary": { "totalEvents": 142, "eventsLastHour": 18, "eventsLast24h": 95, "oldestEvent": "2025-01-14T08:00:00Z", "newestEvent": "2025-01-15T14:30:00Z" }, "eventsByType": [ { "type": "gate.allow", "count": 80 }, { "type": "gate.deny", "count": 25 }, { "type": "key.created", "count": 12 } ], "topActors": [ { "actor": "pg_abc1...", "count": 60 }, { "actor": "admin", "count": 30 } ], "recentEvents": [ { "id": 142, "timestamp": "2025-01-15T14:30:00Z", "type": "gate.allow", "actor": "pg_abc1...", "message": "Allowed: tool_a" } ], "generatedAt": "2025-01-15T14:30:00Z" }

审计事件分析：包括每小时/每天计数的总事件、按频率排序的事件类型细分、前10个最活跃的参与者和20个最近的事件（最新事件优先）。只读。

### 集团绩效

curl http://localhost:3000/admin/group-performance -H "X-Admin-Key: YOUR_ADMIN_KEY"

{ "summary": { "totalGroups": 2, "ungroupedKeys": 3 }, "groups": [ { "groupId": "grp_abc123", "groupName": "prod-team", "description": "Production", "keyCount": 5, "totalAllocated": 5000, "totalSpent": 2000, "totalRemaining": 3000, "totalCalls": 400, "utilizationPct": 40, "policy": { "allowedTools": ["tool_a"], "deniedTools": [], "rateLimitPerMin": 60 } } ], "generatedAt": "2025-01-15T14:30:00Z" }

每组分析：关键计数、信用分配/支出/剩余、呼叫量和利用率百分比。包括组策略摘要（允许/拒绝的工具、速率限制）。按支出排序（最高优先）。还报告未分组的密钥计数。只读。

### 请求数量趋势

curl http://localhost:3000/admin/request-trends -H "X-Admin-Key: YOUR_ADMIN_KEY"

{ "summary": { "totalRequests": 150, "totalAllowed": 130, "totalDenied": 20, "totalCredits": 650, "avgDurationMs": 45, "peakHour": { "hour": "2025-01-15T14:00:00Z", "total": 42 } }, "hourly": [ { "hour": "2025-01-15T12:00:00Z", "total": 35, "allowed": 30, "denied": 5, "credits": 150, "avgDurationMs": 40 }, { "hour": "2025-01-15T13:00:00Z", "total": 42, "allowed": 38, "denied": 4, "credits": 190, "avgDurationMs": 50 } ], "generatedAt": "2025-01-15T14:30:00Z" }

每小时请求量时间序列：总/允许/拒绝计数、信用支出和每小时平均持续时间。包括高峰时段识别摘要。基于请求日志数据构建。按时间顺序排序。只读。

### 关键状态概述

curl http://localhost:3000/admin/key-status -H "X-Admin-Key: YOUR_ADMIN_KEY"

{ "counts": { "total": 20, "active": 15, "suspended": 2, "revoked": 2, "expired": 1 }, "needsAttention": [ { "keyName": "low-balance", "issue": "low_credits", "detail": "5 credits remaining" }, { "keyName": "trial-key", "issue": "expiring_soon", "detail": "Expires in 48 hours" } ], "generatedAt": "2025-01-15T14:30:00Z" }

密钥状态仪表板：活动/暂停/撤销/过期计数，需要注意密钥。标记低信用（\=80）、良好（>=60）、警告（>=40）、严重（\ d.level === 'error')) {
  console.error(formatDiagnostics(diags));
  process.exit(1);
}

批处理工具调用

在一个请求中调用多个工具，并进行全计费或无计费：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call_batch",
  "params": {
    "calls": [
      { "name": "search", "arguments": { "q": "MCP servers" } },
      { "name": "translate", "arguments": { "text": "hello", "to": "es" } },
      { "name": "summarize", "arguments": { "url": "https://example.com" } }
    ]
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "results": [
      { "tool": "search", "result": { "content": [...] }, "creditsCharged": 5 },
      { "tool": "translate", "result": { "content": [...] }, "creditsCharged": 3 },
      { "tool": "summarize", "result": { "content": [...] }, "creditsCharged": 2 }
    ],
    "totalCreditsCharged": 10,
    "remainingCredits": 90
  }
}

主要特点：

• 要么全有要么全无 --所有调用在执行之前都经过预验证（身份验证、ACL、速率限制、信用、配额）。如果任何呼叫被拒绝，则整个批次都将被拒绝，并收取零信用。
• 综合定价 --总学分被原子性地检查和扣除。一批需要5+3+2=10学分的3个呼叫需要10个可用学分。
• 并行执行 --在关卡批准后，所有工具调用都会同时执行，以尽量减少延迟。
• 失败退款 --与 refundOnFailure 启用后，下游出错的单个工具将获得退款。
• 多服务器支持 --在多服务器模式下使用前缀工具（例如。， fs:read, github:search).

编程API：

import { Gate, BatchToolCall } from 'paygate-mcp';

const calls: BatchToolCall[] = [
  { name: 'search', arguments: { q: 'test' } },
  { name: 'translate', arguments: { text: 'hi' } },
];

const result = gate.evaluateBatch(apiKey, calls, clientIp);
if (!result.allAllowed) {
  console.log(`Denied at index ${result.failedIndex}: ${result.reason}`);
} else {
  console.log(`Charged ${result.totalCredits} credits for ${calls.length} calls`);
}

多租户命名空间

按租户隔离API密钥和使用数据。每个密钥都属于一个 namespace （默认值： "default").所有管理端点都支持租户范围视图的命名空间过滤。

在命名空间中创建密钥：

curl -X POST http://localhost:3402/keys \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-agent", "credits": 1000, "namespace": "acme-corp"}'

列出按命名空间筛选的键：

curl http://localhost:3402/keys?namespace=acme-corp \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

列出所有具有统计信息的命名空间：

curl http://localhost:3402/namespaces \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

退货：

{
  "namespaces": [
    { "namespace": "acme-corp", "keyCount": 3, "activeKeys": 2, "totalCredits": 2500, "totalSpent": 480 },
    { "namespace": "beta-inc", "keyCount": 1, "activeKeys": 1, "totalCredits": 500, "totalSpent": 120 }
  ],
  "count": 2
}

命名空间筛选状态、使用情况和分析：

# Status filtered to one namespace
curl http://localhost:3402/status?namespace=acme-corp -H "X-Admin-Key: ..."

# Usage events filtered by namespace
curl http://localhost:3402/usage?namespace=acme-corp -H "X-Admin-Key: ..."

# Analytics filtered by namespace
curl "http://localhost:3402/analytics?namespace=acme-corp&from=2025-01-01" -H "X-Admin-Key: ..."

# Search keys by tag within a namespace
curl -X POST http://localhost:3402/keys/search \
  -H "X-Admin-Key: ..." -H "Content-Type: application/json" \
  -d '{"tags": {"env": "prod"}, "namespace": "acme-corp"}'

命名空间规则：

• 仅限字母数字+连字符，最多50个字符，不区分大小写（存储小写）
• 默认为 "default" 如果遗漏或无效
• 旧密钥自动回填到 "default" 状态文件加载
• 使用事件携带密钥的命名空间，用于跨领域分析
• 命名空间是隐式的——当一个键被分配给一个键时，会自动创建

范围令牌

从任何API密钥中发出短暂的、工具限制的令牌。通过作用域令牌，您可以在不公开父API密钥的情况下将狭窄的访问权限委托给代理或子进程。

创建作用域令牌（admin）：

curl -X POST http://localhost:3402/tokens \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "pg_parent_key_here",
    "ttl": 300,
    "allowedTools": ["search", "summarize"],
    "label": "agent-session-42"
  }'

退货：

{
  "token": "pgt_eyJhcGl...signature",
  "expiresAt": "2025-06-15T12:05:00.000Z",
  "ttl": 300,
  "parentKey": "my-agent",
  "allowedTools": ["search", "summarize"],
  "label": "agent-session-42",
  "message": "Use as X-API-Key or Bearer token on /mcp"
}

使用/mcp上的令牌：

# As X-API-Key header
curl -X POST http://localhost:3402/mcp \
  -H "X-API-Key: pgt_eyJhcGl...signature" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"q":"hello"}}}'

# As Bearer token
curl -X POST http://localhost:3402/mcp \
  -H "Authorization: Bearer pgt_eyJhcGl...signature" \
  -H "Content-Type: application/json" \
  -d '...'

令牌行为：

• 自足 --HMAC-SHA256签名，服务器端状态为零。对每个请求进行加密验证。
• 自动到期 --TTL默认为1小时，最多24小时。过期的代币会立即被拒绝。
• 工具ACL变窄 --如果 allowedTools 如果设置了，则令牌只能调用这些工具（与父键的ACL相交）。
• 来自家长的积分 --工具调用从父密钥的信用余额中收取费用。
• tools/list 过滤 --当作用域令牌调用时 tools/list，只返回允许的工具。
• 批处理感知 — tools/call_batch 检查批处理中每个调用的作用域令牌ACL。
• 决议优先级 — X-API-Key 头球→ pgt_ 范围令牌→ OAuth承载令牌。

令牌格式： pgt_.

程序化使用：

import { ScopedTokenManager } from 'paygate-mcp';

const tokens = new ScopedTokenManager('your-signing-secret');

// Create
const token = tokens.create({
  apiKey: 'pg_parent_key',
  ttlSeconds: 300,
  allowedTools: ['search'],
  label: 'agent-42',
});

// Validate
const result = tokens.validate(token);
if (result.valid) {
  console.log(result.payload.apiKey); // 'pg_parent_key'
  console.log(result.payload.allowedTools); // ['search']
}

// Check if a string is a scoped token
ScopedTokenManager.isToken('pgt_...'); // true
ScopedTokenManager.isToken('pg_...');  // false

令牌撤销列表

在范围内的令牌过期之前撤销它们。一旦被撤销，令牌将立即被所有PayGate实例拒绝（在多实例部署中通过Redis发布/订阅同步）。

撤销令牌（管理员）：

curl -X POST http://localhost:3402/tokens/revoke \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "pgt_eyJhcGl...signature", "reason": "session ended"}'

退货：

{
  "message": "Token revoked",
  "fingerprint": "a1b2c3d4e5f6...",
  "expiresAt": "2025-06-15T12:05:00.000Z",
  "revokedAt": "2025-06-15T11:30:00.000Z"
}

列出已撤销的令牌（管理员）：

curl http://localhost:3402/tokens/revoked \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

退货 { count, entries: [{ fingerprint, expiresAt, revokedAt, reason }] }.

撤销行为：

• O（1）查找 --SHA-256指纹存储在Map中，用于恒定时间拒绝检查。
• 自动清理 --一旦原始令牌自然过期（最多24小时），撤销条目就会被清除，因此列表永远不会无限增长。
• Redis同步 --在多实例部署中，撤销通过以下方式传播 token_revoked 酒吧/酒吧活动。其他实例会立即将该条目添加到其本地吊销列表中。
• 审计跟踪 --每次撤销都记录为 token.revoked 带有指纹和原因的审计事件。
• 签名验证 --只有此服务器签名的令牌才能被撤销（防止撤销任意字符串）。

程序化使用：

import { ScopedTokenManager } from 'paygate-mcp';

const tokens = new ScopedTokenManager('your-signing-secret');
const token = tokens.create({ apiKey: 'pg_key', ttlSeconds: 3600 });

// Revoke
const entry = tokens.revokeToken(token, 'session ended');
console.log(entry.fingerprint); // SHA-256 hex

// Validate — now returns { valid: false, reason: 'token_revoked' }
tokens.validate(token); // { valid: false, reason: 'token_revoked' }

// Check revocation list size
tokens.revocationList.size; // 1

// Clean up on shutdown
tokens.destroy();

基于使用情况的自动充值

当密钥余额降至阈值以下时，自动重新填充积分。防止高价值API消费者的服务中断。

配置自动充值（管理员）：

curl -X POST http://localhost:3402/keys/auto-topup \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "pg_abc123...", "threshold": 100, "amount": 500, "maxDaily": 10}'

退货：

{
  "autoTopup": { "threshold": 100, "amount": 500, "maxDaily": 10 },
  "message": "Auto-topup enabled: add 500 credits when balance drops below 100 (max 10/day)"
}

禁用自动充值：

curl -X POST http://localhost:3402/keys/auto-topup \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "pg_abc123...", "disable": true}'

自动充值行为：

• 扣除后触发 --每次工具调用（或批处理）扣除学分后，关卡会检查学分是否低于阈值，并自动添加学分。
• 每日限额 — maxDaily 限制每个UTC日可以进行的自动充值次数。吃起来 0 无限制。
• 审计跟踪 --每次自动加满都会记录为 key.auto_topped_up 审计事件。配置更改记录为 key.auto_topup_configured.
• Webhook事件 --两者皆有 key.auto_topup_configured 和 key.auto_topped_up 事件通过webhooks发送。
• Redis同步 --在多实例部署中，自动充值积分通过Redis进行原子同步。
• 状态持久性 --自动充值配置和每日计数器保存在状态文件和Redis中。

程序化使用：

import { Gate } from 'paygate-mcp';

const gate = new Gate(config, 'state.json');
const record = gate.store.createKey('premium-client', 1000);

// Configure auto-topup
record.autoTopup = { threshold: 100, amount: 500, maxDaily: 5 };
gate.store.save();

// Hook for notifications
gate.onAutoTopup = (apiKey, amount, newBalance) => {
  console.log(`Auto-topped up ${amount} credits → balance: ${newBalance}`);
};

// Gate.evaluate() automatically triggers auto-topup after credit deduction
const result = gate.evaluate(record.key, { name: 'expensive-tool' });

管理员API密钥管理

使用基于角色的权限管理多个管理员密钥。引导管理键（来自构造函数或CLI）始终是 super_admin.

角色：

创建管理员密钥（仅限super_admin）：

curl -X POST http://localhost:3402/admin/keys \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Bot", "role": "admin"}'
# Returns: { "key": "ak_...", "name": "CI Bot", "role": "admin", "createdAt": "..." }

列出管理员密钥（仅限super_admin）：

curl http://localhost:3402/admin/keys \
  -H "X-Admin-Key: $ADMIN_KEY"
# Returns masked keys with roles, status, and last used timestamps

撤销管理员密钥（仅限super_admin）：

curl -X POST http://localhost:3402/admin/keys/revoke \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "ak_..."}'

行为：

• 的默认角色 POST /admin/keys 是 admin 如果没有指定。
• 无法撤销您自己的管理员密钥（安全防护）。
• 无法撤销上次 super_admin 钥匙（安全防护装置）。
• viewer 密钥可以访问所有只读端点（GET），但被拒绝写入操作（POST）。
• admin 密钥可以创建/撤销/旋转API密钥、管理团队、令牌等，但不能管理管理密钥。
• 管理密钥保存到单独的文件中(*-admin.json)在州档案旁边。
• 所有操作都记录在审计跟踪中(admin_key.created, admin_key.revoked).
• 管理员密钥生命周期更改时会触发Webhook事件。

插件系统

使用插件API将自定义逻辑添加到PayGate。插件可以拦截关卡决策、转换定价、修改工具请求/响应、添加自定义HTTP端点以及挂接到服务器生命周期事件中。

import { PayGateServer, PayGatePlugin } from 'paygate-mcp';

// Define a plugin
const loggingPlugin: PayGatePlugin = {
  name: 'request-logger',
  version: '1.0.0',

  // Gate hooks (sync — hot path)
  beforeGate: (ctx) => {
    // Return { allowed: false, reason: '...' } to short-circuit
    // Return null to continue normal evaluation
    if (ctx.toolName === 'dangerous_tool') {
      return { allowed: false, reason: 'tool_disabled' };
    }
    return null;
  },

  afterGate: (ctx, decision) => {
    // Modify the gate decision after evaluation
    console.log(`${ctx.toolName}: ${decision.allowed ? 'allowed' : 'denied'}`);
    return decision;
  },

  transformPrice: (toolName, basePrice, args) => {
    // Return a number to override price, or null to keep base price
    if (toolName === 'premium_search') return basePrice * 2;
    return null;
  },

  onDeny: (ctx, reason) => {
    // Called whenever a tool call is denied
    console.log(`Denied: ${ctx.toolName} — ${reason}`);
  },

  // Tool hooks (async)
  beforeToolCall: async (ctx) => {
    // Modify the JSON-RPC request before forwarding
    return { ...ctx.request, params: { ...ctx.request.params, audit: true } };
  },

  afterToolCall: async (ctx, response) => {
    // Modify the JSON-RPC response before returning to client
    return response;
  },

  // HTTP hook (async)
  onRequest: (req, res) => {
    // Add custom endpoints — return true if handled
    if (req.url === '/custom/status') {
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ custom: true }));
      return true;
    }
    return false;
  },

  // Lifecycle hooks (async)
  onStart: async () => { console.log('Plugin started'); },
  onStop: async () => { console.log('Plugin stopped'); },
};

// Register plugins with .use() (chainable)
const server = new PayGateServer({ ... });
server
  .use(loggingPlugin)
  .use(anotherPlugin);

await server.start();

吊钩类型：

错误隔离： 插件错误会被捕获并记录下来——崩溃的插件永远不会导致服务器停机。

列出已注册的插件（仅限管理员）：

curl http://localhost:3402/plugins -H "X-Admin-Key: $ADMIN_KEY"
# { "count": 2, "plugins": [{ "name": "...", "version": "...", "hooks": ["beforeGate", ...] }] }

关键组（策略模板）

密钥组允许您定义可重复使用的策略模板，并将它们同时应用于多个API密钥。与团队（共享预算）不同，团队共享 政策：ACL、费率限制、定价覆盖、IP分配列表和配额。

创建组：

curl -X POST http://localhost:3402/groups \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{
    "name": "free-tier",
    "allowedTools": ["search", "read_file"],
    "rateLimitPerMin": 30,
    "ipAllowlist": ["10.0.0.0/8"],
    "quota": { "dailyCallLimit": 100, "monthlyCallLimit": 1000, "dailyCreditLimit": 50, "monthlyCreditLimit": 200 },
    "toolPricing": { "search": { "creditsPerCall": 2 } },
    "tags": { "tier": "free" }
  }'
# { "id": "grp_a1b2c3...", "name": "free-tier", ... }

将密钥分配给组：

curl -X POST http://localhost:3402/groups/assign \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{ "groupId": "grp_a1b2c3...", "key": "pgk_..." }'

策略解决规则：

列出组：

curl http://localhost:3402/groups -H "X-Admin-Key: $ADMIN_KEY"
# [{ "id": "grp_...", "name": "free-tier", "memberCount": 5, ... }]

更新/删除/移除：

# Update group policies
curl -X POST http://localhost:3402/groups/update \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{ "id": "grp_...", "rateLimitPerMin": 60 }'

# Remove a key from its group
curl -X POST http://localhost:3402/groups/remove \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{ "key": "pgk_..." }'

# Delete a group (removes all assignments)
curl -X POST http://localhost:3402/groups/delete \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{ "id": "grp_..." }'

程序化使用：

import { PayGateServer, KeyGroupManager } from 'paygate-mcp';

const server = new PayGateServer({ ... });
const { port, adminKey } = await server.start();

// Access groups directly
const group = server.groups.createGroup({ name: 'enterprise', rateLimitPerMin: 1000 });
server.groups.assignKey(apiKey, group.id);

// Resolve effective policy for a key
const policy = server.groups.resolvePolicy(apiKey, keyRecord);
// { allowedTools, deniedTools, rateLimitPerMin, quota, ipAllowlist, toolPricing, maxSpendingLimit }

文件持久性： 使用时 --state-file，组定义和密钥分配会自动保存到 *-groups.json 主状态文件旁边的文件。组可以在重启后存活，而不需要Redis。

Redis同步： 跑步时 --redis-url，组定义和密钥分配额外持久化到Redis，并通过发布/订阅在实例之间同步。所有组CRUD操作和分配更改都实时传播到其他PayGate进程。

水平缩放（Redis）

为多进程部署启用Redis支持状态。多个PayGate实例通过Redis共享API密钥、信用和使用数据：

# Single instance with Redis persistence
npx paygate-mcp wrap --server "your-mcp-server" --redis-url "redis://localhost:6379"

# With password and database
npx paygate-mcp wrap --server "your-mcp-server" \
  --redis-url "redis://:mypassword@redis.internal:6379/2"

或者在配置文件中：

{
  "serverCommand": "your-mcp-server",
  "redisUrl": "redis://localhost:6379"
}

架构：直写式缓存

PayGate使用直写缓存模式以获得最佳性能：

• 倒像 --从内存中的KeyStore提供服务（零延迟，无Redis往返）
• 写 --传播到Redis以实现跨进程共享状态
• 信用扣减 --使用Redis Lua脚本进行原子检查和扣除（防止跨进程的双重支出）
• 定期同步 --作为安全网，本地缓存每5秒从Redis刷新一次
• 发布/订阅通知 --关键突变和信用变化通过Redis PUBLISH/SUBSCRIBE实时传播到所有实例（亚毫秒延迟）

这意味着Gate.eevaluate（）保持同步和快速，而信贷操作在整个车队中保持原子性。服务器自动将Redis挂钩连接到门上——每个使用事件和信用扣减都流向Redis，而无需任何代码更改。Pub/sub确保其他实例几乎立即看到更改（无需等待5秒）。

什么被同步

部署模式

                    ┌──────────────┐
                    │   Redis 7+   │
                    │  ┌────────┐  │
                    │  │pub/sub │  │
                    └──┴───┬────┴──┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────┴─────┐ ┌───┴───┐ ┌─────┴─────┐
        │ PayGate 1 │ │  PG 2 │ │ PayGate 3 │
        │ (sub+pub) │ │ (sub) │ │ (sub+pub) │
        └─────┬─────┘ └───┬───┘ └─────┬─────┘
              │            │            │
        ┌─────┴────────────┴────────────┴─────┐
        │          Load Balancer               │
        └──────────────────────────────────────┘

实时发布/订阅 --当一个实例创建/撤销密钥或更改信用时，它会向 pg:events 频道。所有其他实例都会立即收到它并更新其本地KeyStore，而无需等待5秒的同步。信用变化包括内联数据（信用、totalSpend、totalCalls），因此接收者完全跳过Redis的往返。每个实例都有一个唯一的ID用于自我消息过滤——没有回声循环。如果发布/订阅失败，则定期同步将继续作为回退。

管理员API同步 --所有管理HTTP端点（创建密钥、撤销、轮换、充值、设置ACL、过期、配额、标签、IP分配列表、支出限制）都写入Redis。备份和撤销使用原子Lua脚本；其他突变使用即发即弃 HSET 立即在实例之间传播更改。

分布式速率限制 --使用带有Lua脚本的Redis排序集，在所有实例上原子地执行速率限制。每次速率检查都会在一次往返中执行ZREMRANGEBYSCORE+ZCARD+ZADD，防止跨进程的突发旁路。如果Redis暂时不可用，则会打开（允许）。

持续使用审计跟踪 --使用事件被附加到Redis列表（RPUSH），创建了一个从任何实例可见的共享审计跟踪。事件在流程重启后仍然存在，可以从仪表板查询。最多100k个事件，具有自动修剪功能。

优雅的后退 --如果Redis暂时不可用，PayGate将回退到本地内存操作。重新连接时，状态会自动同步。

零依赖 --Redis客户端使用Node.js net.Socket 使用原始RESP协议编码。不 ioredis，没有 redis package——纯内置网络。

配置文件模式

从JSON文件而不是CLI标志加载所有设置：

npx paygate-mcp wrap --config paygate.json

示例 paygate.json:

{
  "serverCommand": "npx",
  "serverArgs": ["@modelcontextprotocol/server-filesystem", "/tmp"],
  "port": 3402,
  "defaultCreditsPerCall": 2,
  "globalRateLimitPerMin": 30,
  "webhookUrl": "https://billing.example.com/events",
  "webhookFilters": [
    {
      "name": "production-alerts",
      "events": ["key.created", "key.revoked", "alert.fired"],
      "url": "https://alerts.example.com/webhook",
      "keyPrefixes": ["pk_prod_"]
    }
  ],
  "refundOnFailure": true,
  "stateFile": "~/.paygate/state.json",
  "toolPricing": {
    "premium_analyze": { "creditsPerCall": 10, "creditsPerKbInput": 5 }
  },
  "globalQuota": {
    "dailyCallLimit": 1000,
    "monthlyCreditLimit": 50000
  },
  "oauth": {
    "accessTokenTtl": 3600,
    "scopes": ["tools:*"]
  },
  "redisUrl": "redis://localhost:6379",
  "importKeys": {
    "pg_abc123def456": 500
  }
}

当同时指定了CLI标志和配置文件值时，CLI标志会覆盖配置文件值。

配置热重新加载

从配置文件中重新加载定价、费率限制、Webhook、配额和行为标志，而无需重新启动服务器：

# Reload from the config file used at startup
curl -X POST http://localhost:3402/config/reload \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

# One-time reload from a different config file
curl -X POST http://localhost:3402/config/reload \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"configPath": "/path/to/updated-config.json"}'

热可重新加载字段 （立即生效）：

• defaultCreditsPerCall, toolPricing --价格变动
• globalRateLimitPerMin --利率限制调整
• shadowMode, refundOnFailure --行为标志
• freeMethods --自由方法列表
• globalQuota --每日/每月通话和信用额度
• webhookUrl, webhookSecret, webhookMaxRetries --webhook基础架构（已重建）
• alertRules --警报阈值和规则

不可重新加载的字段 （报告为跳过，需要重新启动）：

• serverCommand, serverArgs --后端MCP服务器进程
• port --监听端口
• oauth --OAuth 2.1配置

响应包括更改的字段、跳过的字段和任何验证警告：

{
  "ok": true,
  "changed": ["defaultCreditsPerCall", "globalRateLimitPerMin"],
  "skipped": [],
  "warnings": [],
  "message": "Config reloaded: 2 fields updated"
}

在应用更改之前，配置文件会被验证——无效的配置会被拒绝，并显示详细的错误消息，应用的更改为零。

部署

一键部署

将PayGate部署到您首选的云平台：


提供：

https://render.com/deploy?repo=https://github.com/walker77/paygate-mcp

Fly.io：

fly launch --image ghcr.io/walker77/paygate-mcp:latest --name my-paygate
fly secrets set PAYGATE_ADMIN_KEY=your-admin-key PAYGATE_REMOTE_URL=https://your-mcp-server.com/mcp

码头工人

# Build the image
docker build -t paygate-mcp .

# Run with a remote MCP server
docker run -d \
  -p 3000:3000 \
  -v paygate-data:/data \
  -e PAYGATE_REMOTE_URL="https://my-mcp-server.com/mcp" \
  -e PAYGATE_ADMIN_KEY="your-admin-key" \
  paygate-mcp

# Run with environment variables
docker run -d \
  -p 3000:3000 \
  -e PAYGATE_PORT=3000 \
  -e PAYGATE_REMOTE_URL="https://api.example.com/mcp" \
  -e PAYGATE_DEFAULT_CREDITS=5 \
  -e PAYGATE_RATE_LIMIT=120 \
  -e PAYGATE_WEBHOOK_URL="https://hooks.example.com/paygate" \
  paygate-mcp

Docker Compose（带Redis）

# Set your MCP server URL and start
MCP_REMOTE_URL="https://my-mcp-server.com/mcp" docker-compose up -d

# View logs
docker-compose logs -f paygate

# Check health
curl http://localhost:3000/health

包括 docker-compose.yml 使用Redis启动PayGate，以实现水平扩展、状态持久性和分布式速率限制。

系统守护进程

# /etc/systemd/system/paygate-mcp.service
[Unit]
Description=PayGate MCP Proxy
After=network.target

[Service]
Type=simple
User=paygate
WorkingDirectory=/opt/paygate-mcp
ExecStart=/usr/bin/node dist/cli.js wrap \
  --remote-url "https://my-mcp-server.com/mcp" \
  --port 3000 \
  --state-file /var/lib/paygate/state.json \
  --audit-file /var/log/paygate/audit.jsonl
Restart=always
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

sudo systemctl enable paygate-mcp
sudo systemctl start paygate-mcp
sudo journalctl -u paygate-mcp -f

PM2

# Install globally
npm install -g paygate-mcp

# Start with PM2
pm2 start paygate-mcp -- wrap \
  --remote-url "https://my-mcp-server.com/mcp" \
  --port 3000 \
  --state-file ./state.json

# Or use ecosystem file
pm2 start ecosystem.config.js

生产检查表

• \[\]设置 --state-file 用于跨重启进行持久存储
• \[\]设置 --audit-file 用于保留审计跟踪
• \[\]配置 --webhook-url 用于外部计费/警报
• \[\]使用 --admin-key 或设置 PAYGATE_ADMIN_KEY （如果省略，则自动生成）
• \[\]启用Redis(--redis-url)用于多实例部署
• \[\]设置带有TLS终止的反向代理（nginx/caddy）
• \[\]配置 --cors-origin 适用于基于浏览器的客户端
• \[\]监视器 /health 带有正常运行时间检查器的端点
• \[\]废料 /metrics 使用Prometheus实现可观测性
• \[\]定期备份状态文件（或使用Redis持久化）

负载测试

A. k6 负载测试脚本包含在生产基准测试中：

# Install k6
brew install k6            # macOS
# or: https://k6.io/docs/getting-started/installation

# Start server (example: echo backend)
npx paygate-mcp wrap -- echo '{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"ok"}]}}' \
  --port 3000 --credits-per-call 1

# Run with admin key (from server startup output)
K6_ADMIN_KEY=admin_xxxx k6 run load-test.js

# Custom VUs and duration
K6_ADMIN_KEY=admin_xxxx k6 run --vus 100 --duration 60s load-test.js

# Against remote deployment
K6_PAYGATE_URL=https://paygate.example.com K6_ADMIN_KEY=admin_xxxx k6 run load-test.js

情节：

• mcp流量 --模拟代理工具调用（斜坡0→50 VU超过10秒，持续30秒）
• admin_reads --仪表板/分析读数（5个恒定VU）
• 健康检查 --负载平衡器探头（10个需求/秒恒定速率）

阈值：

• p（95）响应时间\100请求/秒

错误代码

HTTP状态代码

JSON-RPC错误代码（MCP/MCP端点）

Webhook事件类型

程序化API

import { PayGateServer } from 'paygate-mcp';

// Wrap a local server (stdio)
const server = new PayGateServer({
  serverCommand: 'npx',
  serverArgs: ['@modelcontextprotocol/server-filesystem', '/tmp'],
  port: 3402,
  defaultCreditsPerCall: 1,
  toolPricing: {
    'premium_analyze': { creditsPerCall: 10 }
  },
});

const { port, adminKey } = await server.start();

// Multi-server mode
const multiServer = new PayGateServer(
  { serverCommand: '', port: 3402, defaultCreditsPerCall: 1 },
  undefined, undefined, undefined, undefined,
  [
    { prefix: 'fs', serverCommand: 'npx', serverArgs: ['@modelcontextprotocol/server-filesystem', '/tmp'] },
    { prefix: 'api', remoteUrl: 'https://my-mcp-server.example.com/mcp' },
  ]
);

// With Redis for horizontal scaling
const redisServer = new PayGateServer(
  { serverCommand: 'npx', serverArgs: ['my-mcp-server'], port: 3402, defaultCreditsPerCall: 1 },
  undefined, undefined, undefined, undefined, undefined,
  'redis://localhost:6379'
);

// Client SDK
import { PayGateClient } from 'paygate-mcp/client';

const client = new PayGateClient({
  url: `http://localhost:${port}`,
  apiKey: 'pg_...',
});

const tools = await client.listTools();
const result = await client.callTool('search', { query: 'hello' });

安全

• 加密API密钥生成(pg_ 前缀，48个十六进制字符）
• 列表端点中隐藏的密钥
• 仅整数点数（无浮点精度攻击）
• 1MB请求体限制
• 对所有端点进行输入净化
• 管理员密钥从未在响应中公开
• API密钥从未转发到远程服务器（HTTP传输）
• 速率限制是按密钥进行的，并发安全
• 条纹webhook签名验证（HMAC-SHA256，定时安全）
• Dashboard使用安全的DOM方法（textContent/createElement）——没有innerHTML
• 带有定时安全验证的Webhook HMAC-SHA256签名
• 状态输出中屏蔽的Webhook URL
• 使用整数算术强制执行支出限制（无浮动旁路）
• 按工具ACL执行（白名单+黑名单，经过净化的输入）
• 密钥过期，具有失败关闭行为（过期=拒绝）
• OAuth 2.1与PKCE（S256）——无隐式授权，无明文挑战
• OAuth令牌是不透明的十六进制字符串（没有JWT数据泄漏）
• 配额计数器在UTC边界处自动重置
• SSE会话自动过期（30分钟），最多1000个并发，每个会话最多3个SSE
• 具有保留策略的审核日志（环形缓冲区、基于年龄的清理）
• API密钥在审核事件中被屏蔽（仅前7个字符和后4个字符可见）
• 发现端点（/.knowledge/mcp payment、/pregicing）是公开的，但是只读的
• 团队预算强制执行整数运算（不绕过浮点数）
• 团队使用情况摘要中隐藏的密钥（仅前7个字符+后4个字符）
• 团队配额在UTC日/月边界重置原子
• Redis信用扣减使用Lua脚本进行原子检查和扣减（无双重支出）
• Redis速率限制使用Lua脚本进行原子检查和记录（无突发旁路）
• 通过URL中的密码支持Redis身份验证（Redis://：password@host：端口）
• 优雅的Redis回退——如果Redis断开连接，本地操作将继续
• Redis错误时速率限制器无法打开（允许请求，从不阻止网络问题）
• 通过唯一实例ID进行发布/订阅自消息过滤（无回声循环）
• 发布/订阅用户使用专用的Redis连接（Redis协议要求）
• Red在14次传球中进行了101次对抗性安全测试

经过测试

PayGate已针对官方发布的流行MCP服务器进行了集成测试 @modelcontextprotocol npm作用域。这些测试通过以下方式包装真实的MCP服务器 npx，通过PayGate代理执行工具调用，并验证身份验证门控、信用计费和速率限制是否端到端正确工作。

跨服务器测试 验证管理员端点(/health, /keys, /balance)无论包装的后端如何，都能以相同的方式工作。所有16个集成测试均已通过。

# Run integration tests (requires internet — downloads MCP servers via npx)
npx vitest run tests/real-mcp-servers.test.ts

当前限制

• HTTP传输没有响应大小限制 --来自远程服务器的大量响应按原样转发。
• Redis密钥元数据在写入时同步 --管理员突变立即写入Redis；pub/sub提供近乎即时的跨实例更新；周期同步（5s）是一个安全网。积分、利率限制和使用率始终是原子性的。
• 每个实例都有SSE会话 --每个PayGate实例管理自己的SSE连接（HTTP流不能序列化到Redis）。

路线图

• \[x\] 持久存储(--state-file)
• \[x\] 可流式HTTP传输(--remote-url)
• \[x\] Stripe webhook集成(--stripe-secret)
• \[x\] 客户自助余额查询(/balance)
• \[x\] 使用数据导出——JSON和CSV(/usage)
• \[x\] 管理员web仪表板(/dashboard)
• \[x\] 按关键支出限额(/limits)
• \[x\] Webhook事件(--webhook-url)
• \[x\] 失败退款(--refund-on-failure)
• \[x\] 配置文件模式(--config)
• \[x\] 每个工具ACL——每个密钥的白名单/黑名单工具
• \[x\] 每个工具的速率限制——每个工具的独立限制
• \[x\] 密钥过期（TTL）-自动导出API密钥
• \[x\] 多服务器模式——将N台MCP服务器封装在一个PayGate后面
• \[x\] 客户端SDK-- PayGateClient 自动402重试
• \[x\] 使用配额——每个密钥的每日/每月通话和信用额度
• \[x\] 动态定价——按投入规模收费(creditsPerKbInput)
• \[x\] OAuth 2.1——PKCE、客户端注册、承载令牌、令牌刷新/撤销
• \[x\] SSE流式传输——具有会话管理的完整MCP流式HTTP传输
• \[x\] 审核日志-具有保留、查询API、CSV/JSON导出功能的结构化审核跟踪
• \[x\] 注册/发现--代理可发现定价（/.众所周知/mcp支付，/定价，工具/list_price）
• \[x\] Prometheus metrics-/metrics端点，带有计数器、仪表和正常运行时间
• \[x\] 密钥轮换-轮换保留信用、ACL、配额和开支限制的API密钥
• \[x\] 利率限制标头--x-RateLimit-\*和x-Credits-Remaining on/mcp响应
• \[x\] Webhook签名——具有定时安全验证的HMAC-SHA256签名有效载荷
• \[x\] 管理员生命周期事件——密钥管理操作的Webhook通知
• \[x\] IP允许列表-将API密钥限制为特定的IP或CIDR范围
• \[x\] 关键标签/元数据——为外部系统集成附加关键值标签
• \[x\] 使用分析-时间系列分析API，包括工具细分、趋势和顶级消费者
• \[x\] 警报webhooks——可配置的阈值警报（支出、信用、配额、到期、利率限制）
• \[x\] 团队管理-使用共享预算、配额和使用情况跟踪对API密钥进行分组
• \[x\] 横向扩展——Redis支持的多进程部署状态
• \[x\] 批处理工具调用-- tools/call_batch 全有或全无计费和并行执行
• \[x\] 多租户名称空间-通过名称空间过滤的端点按租户隔离API密钥和使用数据
• \[x\] 范围内的代币——短期 pgt_ 带有工具ACL缩窄、HMAC-SHA256签名、服务器端状态为零的令牌
• \[x\] 令牌撤销列表——在到期前通过O（1）查找、自动清理、Redis同步撤销作用域令牌
• \[x\] 基于使用情况的自动充值——当余额降至每日限额阈值以下时，自动充值积分
• \[x\] 管理员API密钥管理-具有基于角色权限的多个管理员密钥（super_Admin、Admin、viewer）
• \[x\] Webhook过滤器--按事件类型和键前缀将事件路由到多个目的地，并使用独立的重试队列
• \[x\] 信用转移-通过验证和审计跟踪在API密钥之间原子转移信用
• \[x\] 批量密钥操作——在一个请求中执行多个创建/备份/撤销操作，并对每个操作进行错误处理
• \[x\] 密钥导入/导出——导出密钥（JSON/CSV）以进行备份/迁移，导入时解决冲突（跳过、覆盖、错误模式）
• \[x\] Webhook事件回放——回放死信条目（全部或按索引），带有新的交付尝试和审计跟踪

需求

• Node.js>=18.0.0
• 零外部依赖

许可证

麻省理工学院