Paynexus MCP

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密钥被组织化并存储为哈希值；明文密钥永远不会持久化

安全操作保证

API键旋转

这 rotateApiKey() 方法调用后端的 /api-keys/rotate 端点：

1. 后端（通过Supabase JWT进行身份验证）发出一个新的组织范围密钥
2. 旧密钥在永久失效之前会进入一个短暂的宽限期
3. MCP实例会立即更新其内存配置，无需重新启动
4. 所有后续请求都会自动使用新密钥

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 公司