Stripe Claude Connector: The Complete Guide

Stripe processes payments for millions of businesses, from indie side-projects to public companies. Its dashboard and API are excellent, but the data they expose is famously deep: a single failed charge can touch a payment intent, a customer, a subscription, an invoice, a webhook event and a dispute. Answering "why did this payment fail?" often means opening five tabs and cross-referencing logs by hand.

The Stripe connector closes that gap. It is an official implementation of the Model Context Protocol (MCP) that links Claude directly to your Stripe account through a set of well-defined tools. Instead of clicking through the dashboard, you ask Claude in plain English - "pull the last invoice for this customer", "explain why payment intent pi_123 failed", "create a £20 refund on this charge" - and Claude executes against live Stripe state. Stripe documents the server in its official docs at docs.stripe.com/mcp and lists a Stripe plugin on claude.com/plugins/stripe.

Importantly, Stripe ships two complementary paths: a hosted MCP server for chat-style clients like Claude Desktop and Claude Code, and the Stripe Agent Toolkit for developers wiring Stripe into custom agents over the API. This guide covers both.

The MCP server exposes Stripe's most-used surfaces as discrete tools. StackOne catalogues roughly 130 actions; the everyday set covers:

• Payments and intents: retrieve and search payment intents, explain failures, process payments.
• Customers and subscriptions: look up and create customers, inspect and modify subscriptions, cancel at period end.
• Invoices and refunds: list, create and inspect invoices; create and track refunds.
• Products and prices: create and manage products, prices and payment links.
• Money movement: pull balance and payout data for reconciliation.
• Knowledge base: search Stripe's documentation so Claude can answer "how do I…" questions with current, accurate guidance.

Crucially, the server is permission-aware: it only exposes tools that match the scopes on the Restricted API Key you hand it. If a key cannot issue refunds, the refund tool simply is not available - which is exactly how you want a money-moving agent to behave.

Both routes use the same underlying Stripe API, but they suit different jobs.

• Use the MCP server if you want Claude Desktop, Claude Code or another MCP client to talk to Stripe interactively. Setup is minutes, and the remote server handles auth via OAuth so you never distribute a key.
• Use the Agent Toolkit if you are building your own agent or product feature in code. It wraps the Stripe API for Python and TypeScript and plugs into OpenAI's Agent SDK, LangChain, CrewAI and the Vercel AI SDK.

Many teams use both: the MCP server for day-to-day ops and debugging, the toolkit for the agent baked into their app.

Remote server (recommended)

Stripe hosts a remote MCP server at https://mcp.stripe.com that authenticates with OAuth, so no API key is ever copied into a config file. In Claude Code:

claude mcp add --transport http stripe https://mcp.stripe.com

Claude opens an OAuth flow; you approve access in your Stripe account and you are connected. In Claude Desktop, add it under Settings → Connectors rather than editing config files.

Local server

If you prefer to run the server yourself - for example to pin a Restricted API Key or scope exact tools - use the @stripe/mcp package:

npx -y @stripe/mcp --tools=all --api-key=rk_test_YOUR_RESTRICTED_KEY

Note the key goes in a command argument, not an environment variable - unusual among MCP servers, and a detail worth remembering when you add it to claude_desktop_config.json. Use a rk_test_ key while you learn; the same string will sit in plaintext in your config, so treat the file accordingly.

For code-level integrations, install the Stripe Agent Toolkit. It ships for both ecosystems:

pip install stripe-agent-toolkit      # Python npm install @stripe/agent-toolkit     # TypeScript

You configure it with a Restricted API Key and the set of capabilities you want to allow (for example, create customers and payment links but not issue refunds), then pass the resulting tools to your framework of choice - OpenAI Agent SDK, LangChain, CrewAI or the Vercel AI SDK. Because capabilities are declared up front in code, the toolkit is the better fit when you need auditable, least-privilege agents in production. Stripe also publishes @stripe/ai-sdk (Vercel) and @stripe/token-meter for usage-based billing; for the Claude connector specifically you want @stripe/mcp or the toolkit, not those.

• Failed-payment debugging: instead of tracing a failed charge across logs and webhook events, ask Claude Code to pull the payment intent and explain what happened.
• Billing logic in dev: agents validating billing logic can check live Stripe state mid-session, rather than relying on fixtures that may not match production behaviour.
• Customer-care assist: support teams ask "what was the last invoice for X?", "process a £20 refund on order Y" - and Claude executes against Stripe.
• Founder operations: a working Stripe agent that can create a new customer, generate a draft invoice for recent orders, and cancel an active subscription at period end - all in natural language.
• Finance and reconciliation: pull balance and payout data on demand.

Reception has skewed positive among developers and operators. The most-cited win is collapsing failed-payment investigations from a multi-tab archaeology session into a one-line question to Claude. PulseMCP highlights invoicing flows; Composio and Merge.dev document end-to-end Claude Code + Stripe setups; community write-ups celebrate the speed of being able to inspect live Stripe state without leaving the terminal.

The honest counterweight: a connector that can move money or change subscriptions deserves the most careful permissioning of any in the directory. Read-first is good practice; in test mode is better while you learn.

Most friction reported by users comes from a handful of recurring issues. Knowing them in advance saves an afternoon:

• Authorization errors on a tool: if Claude reports it cannot perform an action, the Restricted API Key almost certainly lacks that permission. The server is permission-aware, so the fix is to add the scope in the Stripe Dashboard and refresh the credentials - not to widen the key blindly.
• Test vs live confusion: rk_test_ and rk_live_ keys look almost identical, and the server does not warn you which mode it is in. Drop a live key in by accident and Claude is touching real money. Double-check the prefix before any write action.
• Key in the wrong place: with the local server the key is a CLI argument (--api-key=…), unlike most MCP servers that read an env var. Put it in the wrong field and the server silently fails to authenticate.
• Package confusion: @stripe/mcp, @stripe/agent-toolkit, @stripe/ai-sdk and @stripe/token-meter all exist for different jobs. For the MCP connector install @stripe/mcp; the toolkit is for code agents.
• Prompt-injection exposure: Stripe explicitly recommends enabling human confirmation of tool calls and being cautious when the Stripe server runs alongside other MCP servers, since a malicious document could try to trigger a payment action.

Treat the Stripe connector with the same care as any payments tooling. The single most important rule when handing a key to an AI agent: use a Restricted API Key (RAK), never an unrestricted secret key. RAKs let you grant read-only or write access per resource - so you can let Claude read everything but, say, only create refunds up to a limit, or nothing at all. Because the MCP server reflects those scopes as available tools, the key is the permission model.

Beyond that: prefer test mode while you build trust; reserve write actions (refunds, subscription changes, invoice creation) for narrow, reviewed tasks with confirmation enabled; and remember that the remote OAuth server cannot enforce arbitrary account-level restrictions the way a tightly scoped RAK on the local server can (a known limitation discussed in the stripe/ai GitHub repo). For high-stakes automation, the local server with a hand-scoped RAK gives you the most control.

• Real money: write actions can affect customers and revenue; always review before automating.
• Stripe-shaped scope: the connector knows Stripe, not your wider stack. For cross-system finance work, pair it with other connectors.
• Rate limits: heavy or unusual queries can hit Stripe's API limits; expect to refine prompts and batch carefully.
• OAuth ceiling: the remote server cannot enforce some fine-grained account restrictions; the local server with a scoped RAK is stricter.

Both the MCP server and the Agent Toolkit are free - they are open-source tooling Stripe publishes to make its API agent-friendly. You pay only Stripe's normal processing fees on real transactions, exactly as you would from the dashboard or a direct API call. There is no separate licence or per-seat charge for the connector itself.

The practical limits are Stripe's standard API rate limits (which differ between test and live mode) and whatever scopes you put on the Restricted API Key. If you build a high-volume agent, design around Stripe's documented rate limits and use idempotency keys for any write operations so retries cannot double-charge.

Developers integrating or debugging Stripe; support and ops teams handling refunds, invoices and customer queries; founders and finance teams who want fast answers about live Stripe state. Anyone whose work touches Stripe regularly will feel the leverage immediately.

What can it do?

Search payments, manage customers and subscriptions, list and inspect invoices, create and track refunds, pull balance and payout data, and create payment links.

Is it safe?

Treat like any payments tool - test mode and read-first; reserve writes for narrow, reviewed tasks.

Is it official?

Yes - Stripe's docs cover the MCP server and there is an official Stripe plugin listed by Claude.

Which clients can use it?

Claude Desktop, Claude Code and other MCP-compatible clients.

The Stripe connector compresses a lot of context-switching: debugging payments, answering customer queries, reconciling balances - all become questions Claude can answer against live Stripe state. The reward is huge; the responsibility, too. Read-first, test-mode while you learn, and tight scope on writes.

For anyone whose work touches Stripe, it's one of the most consequential connectors in the directory. Explore more in the complete Claude Connectors Directory.