mcp-stripe

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  # authenticate

Authentication: 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

1. Read before write - Before creating customer/product/price, first use list_* or search_stripe_resources to check if it already exists, avoid duplicate objects
2. Money and contracts require confirmation - create_refund, cancel_subscription, update_subscription, update_dispute must display content and get explicit user confirmation before execution
3. When in doubt, search - If unsure about object ID, fields, or approach, first call search_stripe_documentation or search_stripe_resources, don't guess parameters

Available Tools

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:

1. Display first - List the object ID and key fields to be operated on
2. Explain impact - Refund amount/cancellation time/change content
3. Request confirmation - Wait for user to explicitly reply "confirm"/"yes"/"proceed"
4. 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 info

Create 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_xxx

Create 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_url

Create 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 URL

Refund (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 + status

Cancel 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 result

Tool 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