Stripe Agents — Clawdie Docs

The add-stripe skill gives your agent Stripe tools as MCP tools registered inside the jail. Set a Restricted API Key in .env and the agent can look up customers, create payment links, list invoices, and issue refunds — all from chat.

Prerequisites

A Stripe account. Start with a test mode key (rk_test_...). The skill works in test mode — no real charges.

Setup

1. Create a Restricted API Key

Go to Stripe Dashboard → Developers → API Keys → Restricted Keys. Create a new key with only what your agent needs:

Resource	Permission	Required for
Balance	Read	`stripe_get_balance`
Customers	Read	`stripe_list_customers`, `stripe_get_customer`
Payment Intents	Read	`stripe_list_payment_intents`
Payment Links	Write	`stripe_create_payment_link`
Invoices	Read	`stripe_list_invoices`
Refunds	Write	`stripe_create_refund`
Subscriptions	Read	`stripe_list_subscriptions`

Security

Never use your full secret key. Always use a Restricted API Key. Start read-only, then add write permissions incrementally as you test.

2. Add to .env

STRIPE_SECRET_KEY=rk_test_your_key_here

3. Apply the skill

npx tsx scripts/apply-skill.ts .agent/skills/add-stripe

# Rebuild the jail agent runner
cd jail/agent-runner && npm install && npm run build

The agent now has Stripe tools. No restart needed — tools load on next jail session.

Available tools

Tool	Description
`stripe_get_balance`	Current account balance (available + pending)
`stripe_list_customers`	List customers, filter by email
`stripe_get_customer`	Get a customer by ID
`stripe_list_payment_intents`	Recent payment intents, filter by customer
`stripe_create_payment_link`	Create a payment link for a price ID
`stripe_list_invoices`	List invoices, filter by customer/status
`stripe_create_refund`	Issue a refund by payment intent or charge ID
`stripe_list_subscriptions`	List subscriptions, filter by customer/status

Tools are only registered when STRIPE_SECRET_KEY is present. If the key is absent, no Stripe tools appear — the skill is inert.

Example conversations

☎

Customer lookup

"Find John's account and show me his last invoice"
→ stripe_list_customers(email: "john@...") then stripe_list_invoices(customer_id: "cus_...")

♦

Payment link

"Create a payment link for the Pro plan"
→ stripe_create_payment_link(price_id: "price_...")
Returns URL to share immediately.

✎

Refund

"Issue a refund for Sarah's last payment"
→ Looks up customer, finds payment intent, calls stripe_create_refund — asks you to confirm first.

▤

Balance check

"What's our Stripe balance?"
→ stripe_get_balance()
Returns available and pending by currency.

How it works

Stripe tools are implemented in jail/agent-runner/src/stripe-tools.ts and registered into the existing ipc-mcp-stdio MCP server. This is the same server the agent uses for scheduling tasks and sending messages — no additional processes or config files needed.

STRIPE_SECRET_KEY is passed to the jail via encrypted stdin (in JailAgentInput.secrets), never via environment variables or files. Bash subprocesses inside the jail cannot read it.

The Stripe SDK is lazy-loaded on first tool call, so there is no startup cost if Stripe tools are never used in a session.

Compliance notes

PCI DSS: The agent never handles raw card data — Stripe tokenizes everything. The agent only works with customer IDs, payment intent IDs, and invoice IDs.
Refunds: Require explicit agent decision. The agent will ask for confirmation before issuing — prompt your AGENTS.md accordingly.
GDPR: Customer data retrieved by the agent is held in the jail session (sandboxed) and not persisted unless the agent explicitly writes it to its workspace.

Roadmap

Webhook inbound — agent reacts to Stripe events (payment succeeded, subscription cancelled)
Product and price management tools
Checkout session creation
Token metering for per-customer LLM cost billing