---
name: iblai-connect-stripe
description: "Read and write Stripe data through the Stripe API and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Stripe data, or to set up a Stripe MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Stripe connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/stripe — not part of the iblai/vibe repository. Checked against Stripe's documentation on October 20, 2026; test it against your own Stripe setup before you rely on it.

Online payments platform. A Stripe account holds customers, PaymentIntents, charges, refunds, disputes, products and prices, subscriptions, invoices, payouts and balance transactions.

## Auth & conventions

- **API:** Stripe API (REST). REST API with form-encoded requests and JSON responses covering Customers, PaymentIntents, Refunds, Products, Prices, Subscriptions, Invoices, Payouts and more. List methods use cursor pagination (limit 1-100, starting_after).
- **Base URL:** https://api.stripe.com/v1/
- **Access:** Public, self-serve. Anyone with a Stripe account creates keys on the Dashboard API keys page. Sandboxes have their own test keys (sk_test_, rk_test_); live keys (sk_live_, rk_live_) act on real money.
- **Auth:** API key (HTTP Basic or Bearer); Restricted API key; OAuth (Stripe MCP and Connect). Send the key as the Basic auth username or as a Bearer token. Stripe recommends restricted keys (rk_) with only needed permissions over full-access secret keys (sk_). Restricted keys can be tagged as agent keys, which are subject to approval rules.
- **Limits:** Global limit 100 requests/second in live mode, 25 in sandbox; most endpoints 25/second; Search API 20 reads/second; 50 concurrent live requests. HTTP 429 carries Stripe-Rate-Limited-Reason. Reads average at most 500 per transaction (10,000/month minimum).
- Keep Stripe credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Customers** — GET /v1/customers lists customers; retrieve one by ID.
- **PaymentIntents and charges** — List and retrieve PaymentIntents and charges with status and amounts.
- **Invoices** — List and retrieve invoices and their line items.
- **Subscriptions** — List and retrieve subscriptions and schedules.
- **Balance and payouts** — Retrieve balance, balance transactions and payouts.

## Writes

- **Create customer** — POST /v1/customers creates a customer record.
- **Create and finalize invoice** — Create invoice items and an invoice, then finalize it; finalizing makes it payable. **Confirm with the user first.**
- **Create refund** — Create a refund for a charge or PaymentIntent; sends money back to the customer. **Confirm with the user first.**
- **Cancel subscription** — Cancel a customer's subscription. **Confirm with the user first.**
- **Create payment link** — Create a payment link for products and prices.

## Expose it to an ibl.ai agent (MCP)

Stripe publishes an official MCP server, Stripe MCP (https://docs.stripe.com/mcp). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - For an API key or service credential use `auth_type=token` with `auth_scope=platform` for one key across the organization, or scope it to a single agent for one key per agent.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "List Stripe invoices that are open and past due, with customer email and amount"
- "Create a customer for Dana Lee and send her an invoice for $450"
- "How much did we refund last month, and for which charges?"
- "Show active subscriptions that renew in the next 7 days"

## Guardrails

- Holds PCI cardholder-related data (card brand, last four, billing details) and customer personal data. Full card numbers are tokenized by Stripe, not returned by the API. Refunds move money.
- Request the narrowest Stripe scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- Stripe API authentication: https://docs.stripe.com/api/authentication
- Stripe rate limits: https://docs.stripe.com/rate-limits
- Stripe MCP server: https://docs.stripe.com/mcp
- Stripe MCP: https://docs.stripe.com/mcp
- This connector on ibl.ai: https://ibl.ai/developer/connectors/stripe
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections