โ† BLOG
ยท Arc0 team

Stripe MCP: let an agent read, ask before it writes

Connect Stripe's MCP server to Claude Code, Cursor or Codex, start in a sandbox with a restricted key, and hold every agent write for your approval.

You want to ask Claude to list your recent invoices and get a straight answer from your Stripe account. You don't want the same assistant cancelling a subscription because a line in a support email sounded like an instruction.

The short answer: Stripe's own MCP server lives at https://mcp.stripe.com, and adding it takes a command or a few lines of config per client. It's the quickest start, and a good one. If you want reads allowed and every write held until you approve it, put a rule in front of Stripe that knows which actions write.

Arc0 publishes this blog and is the worked example for that rule; the Stripe steps work without it.

Stripe's MCP server, set up in your client

Stripe runs a remote MCP server at https://mcp.stripe.com. MCP, the Model Context Protocol, is the standard way an AI client plugs into an outside service, and a remote server lives on the web, so there's nothing to install. Each client adds it a little differently (Stripe's MCP docs).

Claude Code. Add the server, then run /mcp inside Claude Code to sign in with OAuth.

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

Codex. One command does it.

codex mcp add stripe --url https://mcp.stripe.com

Cursor. Add the server to ~/.cursor/mcp.json.

{
  "mcpServers": {
    "stripe": {
      "url": "https://mcp.stripe.com"
    }
  }
}

Or let Stripe do it. Stripe's recommended route is stripe agent setup in the Stripe CLI, which configures the Stripe plugin and MCP server for the agents it detects, Claude Code, Codex and Cursor among them.

Then you choose how the agent signs in. Stripe offers OAuth, where the client acts on behalf of your Stripe user, or an agent API key for autonomous access. OAuth is a sign-in in your browser, like any "Log in with" button, so nothing secret gets pasted anywhere.

For an agent key in Claude Code, Stripe's docs put it in the project's .mcp.json as a header, with the key held in an environment variable rather than typed on the command line.

Authorization: Bearer ${AGENT_API_KEY}

That last part matters more than it looks. A key typed into a command lives on in your shell history, which is a strange place to keep the keys to your revenue.

Use OAuth for an assistant you sit with. Save the agent key for the agent that runs while you're asleep.

The November 30 key change

Stripe's MCP server is narrowing which keys it accepts. Starting in December, it stops accepting full-access secret keys and restricted keys without the Agent tag, and Stripe asks you to migrate by November 30, 2026. A rejected key gets a 401 with an OAuth discovery challenge, so a setup that worked last month simply starts failing.

To make an agent-tagged key, select Authorizing agent access to your account when you create a restricted key.

If you set this up months ago with an sk_ key, fix it this week. A 401 with no explanation is a bad way to find out.

Start in a sandbox, with a restricted key

Connect a sandbox before you connect live mode. A Stripe sandbox is an isolated test environment where payments aren't processed by card networks or payment providers. It has its own keys, with _test_ in the prefix (pk_test_, rk_test_, sk_test_), and objects in one mode can't be reached from the other. For new integrations, Stripe recommends general sandboxes, with separate ones for local development and CI.

OAuth lets you keep the two apart. The consent page lets you grant access to live mode accounts or sandboxes, with different permissions per environment. Give the agent a sandbox today and decide about live mode after you've watched it work.

Then pick the key. A restricted API key sets Read, Write or None per resource, and every resource starts at None. Write permissions imply read permissions. Restricted keys start rk_live_ or rk_test_, while secret keys start sk_live_ or sk_test_. Stripe's advice is to always use a restricted key instead of an unrestricted secret key, especially when the key goes to an AI agent.

Our suggested set for a reading agent, as our advice rather than Stripe's: Read on customers, invoices, subscriptions, PaymentIntents, charges and balance, and None on everything else. Add Write on customers only if you want the agent to create customers or tag them with metadata, and only after the reads have earned it.

One more sandbox perk: there you can always see your API keys, while a live key you create yourself can't be revealed again after the first view.

So copy a live key straight to wherever it will live.

Ask the sandbox your real questions first. Better a strange customer record in a sandbox than one you find in live mode the next morning, created late at night by an agent that took "set up a test customer" literally.

What the agent can do once it's connected

Stripe's tool and method lists below are as of November 10, 2026, and Stripe changes them.

Stripe's server is broad by design. Stripe describes its stripe_api_read tool as calling any API GET and stripe_api_write as calling any POST, PATCH, PUT or DELETE, and it publishes the list of supported methods beside them. That's a lot of Stripe through two tools.

The supported writes include creating a refund, cancelling a subscription, voiding an invoice, deleting a coupon and updating a dispute. Create payout isn't on the list: payouts appear only as list and retrieve. The Treasury tools send_money, transfer_money and convert_currency are in public preview and marked for Human confirmation.

A key limits which resources the agent reaches, not which writes it makes there. This is our reading of Stripe's key docs, not a Stripe statement: permission is set per resource, and Write covers both POST and DELETE, so a key that can write customers can make any write on customers. No key setting says "create, yes; delete, no" inside one resource. The permissions themselves don't ask anyone either; asking a person is the job of Stripe's approval rules, which it attaches to agent-tagged keys separately.

Think of a restricted key as the rooms the agent may enter. It isn't a list of what the agent may do once it's inside.

So the useful question isn't which key, it's which writes run without you.

Stripe's own guardrails

Stripe has two controls for risky actions, and they're good at what they cover.

Human confirmation. Some methods are marked Human confirmation, create refund among them. When the agent calls one, it gives you a URL; you approve in the Stripe Dashboard, then tell the agent to retry, and a request you don't approve within 24 hours expires. Stripe is explicit that "confirmation depends on the action, not only the tool name," and that it's separate from your client's own tool-approval setting.

Approval rules. Stripe admins can require approval for actions such as a refund created, a subscription created or canceled, or a payment intent created, and a designated reviewer approves or denies. A user can't approve their own request, and requests left unapproved for 14 days expire. Agent-tagged keys are automatically subject to approval rules, and Stripe starts them on a default set: refund created, subscription canceled, outbound payment, outbound transfer, payout created and currency conversion. When a rule applies, Stripe returns an approval_required error and submits an approval request.

Stripe also advises turning on your client's tool-approval setting, and cautions about prompt injection when you combine its server with others. Prompt injection is text inside something the agent reads that tries to give it orders. Do turn the setting on, and know the habit it builds: by mid-afternoon, clicking Approve is muscle memory.

If your worry is refunds, payouts and cancellations, Stripe's controls are aimed squarely at it. Everyday writes like "update this customer" aren't in the default rules, and whether Human confirmation applies depends on the action. You can add approval rules of your own, but an admin sets them up action by action. The rule in the next section covers every write in one line.

Comparison of what each control limits: a Stripe restricted key sets Read, Write or None per resource and asks no one unless the key is agent-tagged, when Stripe approval rules apply; Stripe Human confirmation depends on the action; an Arc0 rule holds every write for a person's approval

Reads allowed, every write held: set it up with Arc0

The general fix for "read freely, ask before writing" is a check between the agent and Stripe that knows which actions write and holds each one for a person. Because it sits outside the client, it's the same check whether you're in Claude Code or Cursor. Arc0 is our worked example: you connect Stripe once, and every action is graded read, write or destructive.

Request path: an agent in any client sends a Stripe request to the Arc0 policy check, which lets read actions through to Stripe and holds write actions in the Arc0 dashboard until a person approves, with the audit log beside the check

One limit, plainly: Arc0's Stripe actions don't include refunds, payment collection, payouts or subscription cancellation. If you want an agent issuing refunds, use Stripe's own server with its Human confirmation and approval rules. For an agent that should read Stripe and never move money, the short list is the point.

  1. Connect Stripe in Arc0 with a restricted key, sandbox first. Arc0's Stripe app connects with a Stripe API key; restricted keys are recommended, and publishable keys aren't supported. The key stays in Arc0's vault: calls run server-side, and credentials never reach the agent or the model (security).

  2. Check the action list. There are ten actions, each one graded (scopes and actions).

    • Reads (8): stripe.list_customers, stripe.get_customer, stripe.list_invoices, stripe.list_subscriptions, stripe.list_payment_intents, stripe.list_charges, stripe.get_balance and stripe.get_account.
    • Writes (2): stripe.create_customer, and stripe.update_customer_metadata, which sets or clears metadata keys on a customer.
    • Destructive: none.
  3. Hold every write. On the Build plan, which is free, one app rule asks before any Stripe write (policies).

    stripe:write~ask

    Leave reads on Allow. An override for a single action would win over this rule, which in turn wins over the policy default.

  4. Review an approval. An approval holds the exact request for a person, and the agent can't approve its own request. You review it in the Arc0 dashboard, which shows the exact action, its version, the arguments and the acting user (approvals). Deny it and the execution ends with no call to Stripe; ignore it and it expires after 24 hours.

  5. Add Arc0 to your client. Point the client at the Arc0 MCP endpoint, and interactive clients sign in with OAuth.

    https://api.arc0.ai/mcp

    The same URL and the same rule apply in Claude, ChatGPT, Cursor, Claude Code, Codex and VS Code (client setup, or the guides for Claude, Cursor and Codex).

Arc0 also keeps Development and Production environments apart, each with its own users, keys and policies (environments), which pairs naturally with a Stripe sandbox and a live account.

This is one step more than Stripe's own command. The step is where the rule lives, outside any single client, so moving from Cursor to Claude Code doesn't mean setting it up again.

Arc0 has two Stripe writes, so holding all of them is easy; the real tradeoff is that it can't do the rest of Stripe. If your questions are about customers, invoices, subscriptions, payments and balance, the ten actions cover them.

The safest write is one that waits for you. Picture the agent setting a metadata key on the wrong customer because two of them share a surname. With the rule on, that's a request you decline, not a record you fix.

Check what ran

Whatever holds the writes, read the record afterwards. Arc0 keeps an audit log of the calls your agent makes through it on every plan, kept 7 days on Personal and 30 on Build.

On Stripe's side, your OAuth sessions are listed in your Dashboard user settings, where the overflow menu has Revoke access. Admins can also switch MCP access on or off for the whole team, separately for live mode and sandbox.

Read the log after the agent's first week. You'll learn what it actually reaches for, which is rarely what you'd have guessed.

Prompts to try

These prompts assume Stripe is connected through Arc0, so the agent calls Arc0's action ids; on Stripe's own server you'd see stripe_api_read instead. Start in the sandbox, then repeat in live mode once the answers look right. If the agent reaches for a different action than the one listed, the log will show it.

PromptAction it should call
"List my recent invoices."stripe.list_invoices, which lists invoices on the account
"List my active subscriptions and their status."stripe.list_subscriptions
"Why did my recent payments fail?"stripe.list_payment_intents, which includes the last failure code
"What's my available versus pending balance?"stripe.get_balance, which reports both per currency
"Find the customer with this exact email address."stripe.list_customers, which can filter by exact email
"Add a metadata key source: webinar to this customer."stripe.update_customer_metadata, a write, so it waits in the Arc0 dashboard

The last one is the test that matters. The right result is a pause, not a changed record.

For an agent that should read Stripe and never move money on its own, Arc0 is our pick. It has no refund, payout or cancel action to misuse, and once the stripe:write~ask rule is in place, every write waits for you. If you want an agent issuing refunds, stay on Stripe's server and lean on its Human confirmation and approval rules.

Connect Stripe in Arc0, add the rule from the policies docs, and sign up free to start.

Then ask it to list your recent invoices.

Get started

One plug. Every app. Any agent.

Your users connect their apps once, under your brand. Your agent, or Claude, ChatGPT and Cursor, acts through one MCP endpoint, with every action on the record.