使用说明
Paynexus MCP
A Node.js + TypeScript Model Control Plane (MCP) client for the Paynexus payment infrastructure — built for AI agents, automated pipelines, and production-grade integrations.
概述
Paynexus MCP是一个严格类型的包装器，使AI代理和自动化系统能够与Paynexu后端安全交互。它仅通过经过身份验证的REST端点运行，强制执行生产中定义的每一层业务逻辑、安全控制和合规性策略。
身份验证由 Supabase认证 -提供基于JWT的会话管理、行级安全强制和组织范围的API密钥发布，而不暴露任何直接的数据库访问。
特性
- 创建结账会话 --即时安全、可审计的付款结账
- 确认付款 --实时验证和结算付款状态
- 获取交易记录 --通过过滤检索完整的交易历史记录
- 触发并检索合规性扫描 --直接与合规系统接口
- Webhook自动注册 --以编程方式注册HMAC安全的webhook侦听器
- API键旋转 --无缝旋转和撤销密钥，不会中断服务
生产架构
AI Agent / Automated System
│
▼
Paynexus MCP (this package)
│ Bearer token (Supabase JWT)
▼
Paynexus Backend (Rust / Axum)
│
├──► Supabase Auth (JWT validation, RLS enforcement)
├──► Supabase DB (zero direct access from MCP)
├──► Compliance Engine
└──► Webhook Dispatcher
在生产中，MCP从不直接接触数据库。所有请求在到达任何业务逻辑之前都会经过Supabase Auth的验证。
配置和使用
1.安装
npm install @paynexus/mcp
2.环境变量
创建一个 .env 文件基于 .env.example:
PAYNEXUS_ENV=production
PAYNEXUS_API_KEY=pnx_live_xxxxxxxxxxxxxxxx
PAYNEXUS_BASE_URL=https://api.paynexus.ai
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
LOG_LEVEL=info
对于沙盒/开发：
PAYNEXUS_ENV=sandbox
PAYNEXUS_API_KEY=pnx_test_xxxxxxxxxxxxxxxx
PAYNEXUS_BASE_URL=https://paynexus-mcp.thankfulpond-3f5b4265.eastus2.azurecontainerapps.io
3.基本示例
import { PaynexusClient, logger } from '@paynexus/mcp';
async function main() {
const client = new PaynexusClient();
// Create a checkout session
const session = await client.createCheckout(4900, 'usd');
logger.info('Created session', { id: session.id, url: session.url });
}
main();
看 example.ts 以完整的端到端示例为例。
沙盒演示
无需后端设置。实时沙箱端点支持具有真实响应有效载荷的完整MCP流（ID如 cs_demo_*, wh_demo_*, pk_demo_*).
BASE=https://paynexus-mcp.thankfulpond-3f5b4265.eastus2.azurecontainerapps.io
# 1. Login — any email + password
TOKEN=$(curl -s -X POST $BASE/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"demo@paynexus.ai","password":"demo"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
# 2. Create API key
curl -X POST $BASE/api-keys/create \
-H "Authorization: Bearer $TOKEN"
# 3. Create checkout session
curl -X POST $BASE/checkout/demo \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"amount":4900,"currency":"usd"}'
# 4. Register webhook
curl -X POST $BASE/webhooks/create \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"url":"https://webhook.site/demo","events":["checkout.confirmed"]}'
# 5. Rotate API key
curl -X POST $BASE/api-keys/rotate \
-H "Authorization: Bearer $TOKEN"
# 6. Inspect full session state
curl $BASE/session -H "Authorization: Bearer $TOKEN"
所有响应都是真实的JSON——沙盒的行为与生产环境完全相同。
安全与运营
身份验证（Supabase Auth）
在生产中，Paynexus使用 Supabase认证 对于所有身份和会话管理：
- 登录问题a Supabase JWT 绑定到用户的组织
- JWT作为
Bearer每个MCP请求上的令牌 - 在处理任何操作之前，后端通过Suabase的Auth API验证JWT
- 行级安全（RLS） 在数据库层强制执行——即使令牌被滥用，也不可能发生跨租户数据泄漏
- API密钥被组织化并存储为哈希值；明文密钥永远不会持久化
安全操作保证
| 保证 | 实施 |
|---|---|
| 无直接数据库访问 | MCP包中无数据库驱动程序 |
| 环境隔离 | X-Paynexus-Env header阻止沙盒密钥进入生产路线 |
| 键编校 | 结构化记录器自动编校与匹配的任何值 pnx_ 前缀 |
| 审计跟踪 | 每个MCP操作都会用经过身份验证的用户ID记录在服务器端 |
API键旋转
这 rotateApiKey() 方法调用后端的 /api-keys/rotate 端点：
- 后端（通过Supabase JWT进行身份验证）发出一个新的组织范围密钥
- 旧密钥在永久失效之前会进入一个短暂的宽限期
- MCP实例会立即更新其内存配置，无需重新启动
- 所有后续请求都会自动使用新密钥
Webhook注册
这 WebhookManager 用途 crypto.randomBytes(32) 为每个端点注册生成加密安全的HMAC秘密。机密和侦听器URL通过TLS传输到后端，并通过Supabase的加密列加密存储。
使用以下方式验证传入的webhook有效负载：
webhookManager.verifySignature(payload, signature, secret);
部署
生产部署通过以下方式处理 GitHub操作 使用Azure容器应用程序。推到 main 触发自动构建和部署管道——不需要手动步骤。
git push origin main
# ↳ GitHub Actions builds Docker image
# ↳ Pushes to Azure Container Registry
# ↳ Deploys to Azure Container Apps (eastus2)
许可证
麻省理工学院© Paynexus 公司
