Stripe MCP Transaction Skill
Execute transaction operations via Stripe MCP server.
File-based Pipeline (Pass Paths Only)
When integrating billing operations into multi-step workflows, persist all context and artifacts to disk, passing only paths between agents/sub-agents.
Recommended directory structure (within project): runs/<workflow>/active/<run_id>/
- Input:
01-input/goal.md(requirements),01-input/context.json(known customer/invoice/subscription/payment_intent IDs, etc.) - Plan:
03-plans/stripe-actions.md(list of operations to execute; money/contracts must be written here and await confirmation first) - Output:
05-final/receipt.md+05-final/receipt.json(object type + ID + key fields + next steps) - Logs:
logs/events.jsonl(summary of each tool call; do not log sensitive information verbatim)
Connection Configuration
MCP Server: https://mcp.stripe.com
Claude Code Connection:
claude mcp add --transport http stripe https://mcp.stripe.com/
claude /mcp # authenticateAuthentication: OAuth preferred; if API key needed, use restricted key as Bearer token.
Mode: Test mode by default. Switching to live requires user to explicitly say "live" and double confirmation.
Three Hard Rules
- Read before write - Before creating customer/product/price, first use
list_*orsearch_stripe_resourcesto check if it already exists, avoid duplicate objects - Money and contracts require confirmation -
create_refund,cancel_subscription,update_subscription,update_disputemust display content and get explicit user confirmation before execution - When in doubt, search - If unsure about object ID, fields, or approach, first call
search_stripe_documentationorsearch_stripe_resources, don't guess parameters
Available Tools
| Category | Tool | Description |
|---|---|---|
| Account | get_stripe_account_info | Get account info |
| Balance | retrieve_balance | Query available/pending balance |
| Customer | create_customer, list_customers | Create/list customers |
| Product | create_product, list_products | Create/list products |
| Price | create_price, list_prices | Create/list prices |
| Invoice | create_invoice, create_invoice_item, finalize_invoice, list_invoices | Full invoice workflow |
| Payment Link | create_payment_link | Create shareable payment link |
| Payment Intent | list_payment_intents | List payment intents (query only) |
| Refund | create_refund | ⚠️ Dangerous - requires confirmation |
| Dispute | list_disputes, update_dispute | ⚠️ update requires confirmation |
| Subscription | list_subscriptions, update_subscription, cancel_subscription | ⚠️ update/cancel require confirmation |
| Coupon | create_coupon, list_coupons | Create/list coupons |
| Search | search_stripe_resources, fetch_stripe_resources, search_stripe_documentation | Search objects/documentation |
Cannot do (not in tool list):
- ❌ Create PaymentIntent / charge directly
- ❌ Create subscription (create_subscription)
- ❌ Create Promotion Code (only coupon)
- ❌ Delete objects
Dangerous Action Handling Flow
Before executing create_refund, cancel_subscription, update_subscription, update_dispute:
- Display first - List the object ID and key fields to be operated on
- Explain impact - Refund amount/cancellation time/change content
- Request confirmation - Wait for user to explicitly reply "confirm"/"yes"/"proceed"
- Execute and receipt - Return operation result + object ID + status
Example confirmation prompt:
About to execute refund:
- PaymentIntent: pi_xxx
- Amount: £50.00 (full amount)
- Reason: requested_by_customer
Reply "confirm" to proceed, or "cancel" to abort.Default Configuration
- Currency: Prioritize user-specified currency; if not specified, use existing object currency (Price/Invoice/PaymentIntent); if still unclear, ask
- Amount: Accept decimal input, auto-convert to smallest unit integer (e.g., £19.99 → 1999)
- Output receipt: Object type + ID + key fields + next steps
Common Workflows
Create Customer
1. search_stripe_resources or list_customers to check if already exists
2. If not exists, create_customer(name, email, metadata)
3. Return cus_xxx + key infoCreate Product and Price
1. list_products to check if product already exists
2. create_product(name, description)
3. create_price(product=prod_xxx, unit_amount=amount in smallest unit, currency="gbp", recurring if needed)
4. Return prod_xxx + price_xxxCreate and Send Invoice
1. Confirm customer ID (if unknown, query with list_customers)
2. create_invoice(customer=cus_xxx, collection_method, days_until_due)
3. create_invoice_item(invoice=inv_xxx, price=price_xxx, quantity)
4. finalize_invoice(invoice=inv_xxx)
5. Return inv_xxx + hosted_invoice_urlCreate Payment Link
1. Confirm price ID (if unknown, query with list_prices)
2. create_payment_link(line_items=[{price, quantity}], after_completion if needed)
3. Return payment link URLRefund (Dangerous)
1. list_payment_intents to find target payment
2. Display pi_xxx + amount + customer info
3. Request user confirmation
4. After confirmation, create_refund(payment_intent=pi_xxx, amount for partial refund, reason)
5. Return re_xxx + statusCancel Subscription (Dangerous)
1. list_subscriptions(customer=cus_xxx) to find target
2. Display sub_xxx + current status + next billing date
3. Ask: cancel immediately or at period end (cancel_at_period_end)
4. After confirmation, cancel_subscription(subscription=sub_xxx)
5. Return cancellation resultTool Parameter Details
See tools.md
Error Handling
- Object doesn't exist: Use search_stripe_resources or fetch_stripe_resources to find correct ID
- Parameter error: Use search_stripe_documentation to query correct parameter format
- Insufficient permissions: Prompt user to check API key permission scope
- Network error: Suggest retry or check MCP connection status