stripe-mcps

Security middleware for AI agent payments via Stripe. Adds cryptographic signing, spend limits, replay protection, trust verification, AML sanctions screening, and audit trails to agent-initiated transactions.

Zero dependencies. Works with any MCP client.

What's New in v2.0

• AgentPass trust verification -- Check an agent's trust score before allowing payments. Untrusted agents are blocked.
• AML sanctions screening -- Screen recipients against 75K+ sanctions entries (UK HMT + OFAC SDN) before every payment.
• createTrustedPayment() -- One function: trust check + sanctions screen + MCPS sign + Stripe PaymentIntent.
• Backward compatible -- v1.x users upgrade with zero changes. Trust/sanctions features only activate when an AgentPass API key is configured.
• OWASP MCP Top 10 aligned -- Addresses tool poisoning (MCP-01), excessive agency (MCP-04), and insufficient audit (MCP-09).

The Problem

Stripe's Agent Toolkit and Machine Payments Protocol let AI agents make payments autonomously. But:

• There's no proof which agent authorised which payment
• A captured create_payment_intent call can be replayed
• No per-agent spend limits at the protocol level
• No tamper detection on payment parameters
• No audit trail linking agent identity to transactions
• No trust scoring -- any agent can spend without verification
• No sanctions screening -- payments to sanctioned entities pass through

Restricted API keys control what an agent can do. This library controls how much it can spend, proves who authorised it, and verifies the agent is trusted and the recipient is not sanctioned.

Install

npm install stripe-mcps

Quick Start (v2.0 -- Trusted Payments)

const { createTrustedPayment } = require('stripe-mcps');

// Set your AgentPass API key
process.env.AGENTPASS_API_KEY = 'apt_live_...';

// One function does everything:
// 1. Checks agent trust score (blocks if below threshold)
// 2. Screens recipient against sanctions (75K+ entries)
// 3. Signs with ECDSA P-256 (non-repudiable)
// 4. Creates Stripe PaymentIntent envelope
const result = await createTrustedPayment(
  'procurement-bot-1',  // AgentPass agent ID
  5000,                 // Amount in cents
  'usd',                // Currency
  'aws.amazon.com',     // Recipient (screened against sanctions)
  { minTrust: 50 }      // Options
);

// result.envelope    -- signed MCPS envelope
// result.receipt     -- non-repudiable receipt
// result.trust       -- { trusted: true, score: 85, level: 'TRUSTED' }
// result.sanctions   -- { clear: true, status: 'CLEAR' }

Quick Start (v1.x Compatible)

const { SecureStripeAgent } = require('stripe-mcps');

// Works exactly like v1.x -- no AgentPass needed
const agent = new SecureStripeAgent({
  agentId: 'procurement-bot-1',
  trustLevel: 'L2',  // max $100/tx, $500/day
});

const result = await agent.secureToolCall('create_payment_intent', {
  amount: 5000,
  currency: 'usd',
});

// result.envelope  -- signed ECDSA P-256 envelope
// result.receipt   -- non-repudiable payment receipt
// result.original  -- original params (forward to Stripe)

Enable AgentPass on SecureStripeAgent

const agent = new SecureStripeAgent({
  agentId: 'procurement-bot-1',
  trustLevel: 'L2',

  // v2.0: Add AgentPass trust + sanctions
  agentPassApiKey: 'apt_live_...',   // or set AGENTPASS_API_KEY env var
  agentPassMinTrust: 50,             // minimum trust score (default: 30)
});

// Now every payment tool call automatically:
// 1. Checks trust score via AgentPass
// 2. Screens recipient against sanctions
// 3. Signs and audits (as before)
const result = await agent.secureToolCall('create_payment_intent', {
  amount: 5000,
  currency: 'usd',
  description: 'aws.amazon.com',  // <-- screened against sanctions
});

Standalone Functions

Check Agent Trust

const { checkAgentTrust } = require('stripe-mcps');

const result = await checkAgentTrust('agent-id', {
  apiKey: 'apt_live_...',
  minScore: 50,
});
// { trusted: true, score: 85, level: 'TRUSTED', agentId: 'agent-id' }
// or
// { trusted: false, score: 15, reason: 'Trust score 15 below minimum 50', code: 'AGENTPASS-LOW-TRUST' }

Screen Against Sanctions

const { screenBeforePayment } = require('stripe-mcps');

const result = await screenBeforePayment('SBERBANK', {
  apiKey: 'apt_live_...',
});
// { clear: false, status: 'HIT', matchCount: 3, reason: 'Sanctions HIT: SBERBANK matched 3 record(s)' }

const clean = await screenBeforePayment('aws.amazon.com', {
  apiKey: 'apt_live_...',
});
// { clear: true, status: 'CLEAR', matches: [], matchCount: 0 }

What It Does

1. Verifies Agent Trust (v2.0)

Before any payment, checks the agent's trust score via AgentPass. Agents with low trust scores are blocked from making payments. Trust scores are calculated from transaction history, identity verification, and compliance behaviour.

Agent requests payment
    |
    v
checkAgentTrust() -- score >= threshold?
    |          |
    YES        NO --> BLOCKED (audit logged)
    |
    v
Continue to sanctions check...

2. Screens Against Sanctions (v2.0)

Every payment recipient is screened against 75,784 sanctions entries from UK HMT and OFAC SDN lists. Hits block the payment immediately.

Trust check passed
    |
    v
screenBeforePayment() -- recipient on sanctions list?
    |          |
    CLEAR      HIT --> BLOCKED (audit logged)
    |
    v
Continue to spend limits...

3. Signs Every Payment

Each Stripe tool call gets an ECDSA P-256 digital signature covering the full payload, agent identity, nonce, and timestamp. The signature proves:

• Which agent made the request
• The exact parameters at the time of signing
• When the request was created

If anyone modifies the amount, recipient, or any parameter after signing, verification fails.

4. Blocks Replay Attacks

Every signed request includes a unique nonce and timestamp. The nonce store rejects any request it has seen before. The timestamp window (default 5 minutes) rejects stale requests.

5. Enforces Spend Limits by Trust Level

Agents are assigned trust levels with associated financial limits. An agent cannot exceed its limits regardless of API key permissions.

| Level | Per Transaction | Daily Limit | Use Case | |-------|----------------|-------------|----------| | L0 | $0 | $0 | No financial access | | L1 | $10 | $50 | Micro-payments, subscriptions | | L2 | $100 | $500 | Standard procurement | | L3 | $1,000 | $5,000 | Enterprise purchasing | | L4 | Unlimited | Unlimited | Full access (audited) |

6. Generates Non-Repudiable Receipts

Every payment produces a cryptographic receipt that can be independently verified. v2.0 receipts include trust score and sanctions status.

console.log(result.receipt);
// {
//   receipt_id: 'rcpt_a1b2c3d4e5f6',
//   tx_hash: 'sha256...',
//   agent_id: 'procurement-bot-1',
//   tool: 'create_payment_intent',
//   amount: 5000,
//   currency: 'usd',
//   status: 'authorised',
//   trust_score: 85,
//   sanctions_status: 'CLEAR',
// }

7. Maintains Hash-Chained Audit Trail

Every transaction is logged in a tamper-evident chain where each entry references the hash of the previous entry. v2.0 adds trust and sanctions events to the chain.

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | AGENTPASS_API_KEY | AgentPass API key (apt_live_xxx) | (none -- disables trust/sanctions) | | AGENTPASS_MIN_TRUST | Minimum trust score (0-100) | 30 | | AGENTPASS_BASE_URL | AgentPass server URL | https://agentpass.co.uk |

Constructor Options

new SecureStripeAgent({
  // v1.x options (unchanged)
  agentId: 'my-agent',
  trustLevel: 'L2',
  keys: { publicKey, privateKey },
  spendLimits: { L2: { per_tx: 25000, daily: 100000 } },
  nonceWindowMs: 300000,
  maxAuditEntries: 10000,
  onPayment: (receipt) => { /* ... */ },
  onBlock: (blocked) => { /* ... */ },

  // v2.0 options
  agentPassApiKey: 'apt_live_...',
  agentPassMinTrust: 50,
  agentPassBaseUrl: 'https://agentpass.co.uk',
});

How It Fits

Your AI Agent
    |
    v
stripe-mcps v2.0 (trust + sanctions + sign + limit + audit)
    |
    +--> AgentPass API (trust score + sanctions screening)
    |
    v
@stripe/agent-toolkit or mcp.stripe.com
    |
    v
Stripe API

API Reference

| Export | Description | |--------|-------------| | SecureStripeAgent | Main class -- wraps Stripe tool calls with full security | | createTrustedPayment() | Trust + sanctions + sign + receipt (standalone) | | checkAgentTrust() | Check agent trust score via AgentPass | | screenBeforePayment() | Screen recipient against sanctions (75K+ entries) | | generateKeyPair() | Generate ECDSA P-256 key pair | | signPayment() | Sign a payment message | | verifyPayment() | Verify a signed envelope | | createReceipt() | Generate a transaction receipt | | NonceStore | Replay protection store | | SpendPolicy | Spend limit engine | | AuditLog | Hash-chained audit trail | | isPaymentTool() | Check if a tool name is financial | | extractAmount() | Extract amount/currency from Stripe params |

OWASP MCP Security Alignment

stripe-mcps v2.0 addresses multiple items from the OWASP MCP Top 10:

| OWASP MCP | Risk | stripe-mcps Control | |-----------|------|---------------------| | MCP-01 | Tool Poisoning | ECDSA signature on every tool call -- tampered params fail verification | | MCP-04 | Excessive Agency | Spend limits per trust level + AgentPass trust scoring | | MCP-05 | Insufficient Sandboxing | Sanctions screening blocks payments to sanctioned entities | | MCP-09 | Insufficient Logging | Hash-chained audit trail with SIEM export (RFC 5424) | | MCP-10 | MCP Authentication Weaknesses | ECDSA P-256 + nonce replay protection + agent identity |

Standards

• Signing: ECDSA P-256
• Trust: AgentPass trust scoring (agentpass.co.uk)
• Sanctions: UK HMT (57K) + OFAC SDN (18K) via AgentPass
• Audit: JSON + RFC 5424 syslog
• Replay: Nonce + timestamp window
• Based on MCPS Internet-Draft (IETF)

Tests

npm test

Backward Compatibility

v2.0 is fully backward compatible with v1.x. If you don't set AGENTPASS_API_KEY, the library behaves identically to v1.0.1. All existing APIs, options, and return values are preserved. The only additions are:

• trust and sanctions fields in secureToolCall() return values (both null when AgentPass is not configured)
• agentpass_enabled field in getAuditTrail() return value
• New exports: createTrustedPayment, checkAgentTrust, screenBeforePayment
• New constructor options: agentPassApiKey, agentPassMinTrust, agentPassBaseUrl

License

MIT

Contributing

Issues and PRs welcome. Security issues: [email protected]