Stripe MCP Server: What an Agent Can Do With Payments

The Stripe MCP server is Stripe’s own hosted server at https://mcp.stripe.com. Connected to Claude Code, Cursor, VS Code, Codex, Claude or ChatGPT, it lets an agent search Stripe’s documentation, look up the right API method, and read or write your account through the Stripe API: customers, payments, invoices, subscriptions, products, prices, refunds, disputes and more. People sign in with OAuth and choose which accounts and sandboxes the agent may touch; unattended agents use an agent API key with only the permissions they need. Start in a sandbox, keep approval prompts on for writes, and keep refunds, payouts and price changes behind a person, even though Stripe adds its own confirmation step for some of them.

Remote server, plugin, or local package

Stripe offers three routes, and its MCP documentation↗ (opens in a new tab) recommends the first.

• Agent plugin: install the Stripe CLI and run stripe agent setup. It detects the agents you use, configures the remote server, installs Stripe’s agent skills and keeps them updated.
• Remote server by hand: point any MCP client at https://mcp.stripe.com. Nothing runs on your machine.
• Local server: npx -y @stripe/mcp runs a server on your machine with an API key. Its README says tool permissions are controlled by your restricted API key. Use it when you cannot reach a remote server; otherwise the hosted one is simpler and supports OAuth.

Setup in Claude Code, Cursor and the chat apps

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

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

VS Code takes the same URL as an http server in .vscode/mcp.json, and Codex adds it with codex mcp add stripe --url https://mcp.stripe.com. In Claude on the web or desktop, install the Stripe connector from the directory; on Team and Enterprise plans an owner adds it to the workspace first. In ChatGPT, install the Stripe plugin and sign in when prompted. If your company manages your device or network, IT may need to allow mcp.stripe.com before any of these connect. The general shape of these files is in MCP config files and the MCP docs.

OAuth or an agent API key

Use OAuth whenever a person is at the keyboard. The client opens Stripe’s consent page, where you choose one or more live accounts or sandboxes and set different permissions for each environment. Your authorized clients appear under OAuth sessions in your Stripe user settings, where you can revoke any of them, and an administrator can see and revoke other team members’ sessions or turn MCP access off for the whole team, separately for live mode and sandboxes.

Use an API key only for an agent that runs without a person and cannot do OAuth, such as a scheduled job. Stripe’s guide to API keys↗ (opens in a new tab) describes agent keys: restricted keys tagged, when you create them, as authorizing agent access. They authenticate like any restricted key, but they fall under approval rules automatically, and they show an Agent badge in the Dashboard. Pass the key from an environment variable in an Authorization: Bearer header, never on the command line or in a committed file. The deadline to know: from October 31, 2026, Stripe MCP stops accepting full-access secret keys and restricted keys without the agent tag. Anything configured with an older key needs a new agent key or an OAuth sign-in before then.

A least-privilege key for each job

A restricted key lets you set each resource to none, read or write. Stripe does not prescribe a set per job, so treat these as starting points and add only what a real task fails without:

• Support lookups: read on customers, charges, payment intents, invoices and subscriptions. No write access at all.
• Reporting and reconciliation: read on balance, balance transactions, payouts and invoices.
• Billing operations in a sandbox: write on customers, invoices and subscriptions, and nothing on refunds or prices until the workflow has been tested.
• Building an integration: a sandbox key or sandbox-only OAuth grant, never live mode.

One key per agent, named for its job, so revoking one does not stop the others and the logs show which agent did what. The same reasoning for every MCP server is in MCP security best practices.

Sandboxes first

A Stripe sandbox is an isolated test environment. Stripe’s sandboxes page↗ (opens in a new tab) says payments you create there are not processed by card networks or payment providers, recommends general sandboxes over the older test mode sandbox for new integrations, and suggests separate sandboxes for local development and CI. It also tells coding agents they can install the Stripe CLI and run stripe sandbox create --help to set up an anonymous sandbox with working keys, with no account registration. Grant the agent sandboxes only for its first weeks. Give it live read access when its sandbox work is right, and live write access, if ever, one resource at a time.

The tools

The server keeps its tool list short and reaches most of the API through four general tools, which saves context:

• stripe_api_search finds API methods by keyword, and stripe_api_details returns a method’s parameters.
• stripe_api_read calls any supported GET method; stripe_api_write calls any supported POST, PATCH, PUT or DELETE method. The supported list covers customers, charges, payment intents, invoices, subscriptions, coupons, promotion codes, products, prices, payment links, refunds, disputes, webhook endpoints, tax settings, balance and payouts (read only), Issuing and more.
• get_stripe_account_info returns the connected account.
• search_stripe_documentation searches Stripe’s docs and support articles, and stripe_implementation_planner guides the agent through choosing Stripe products for an integration.
• Preview tools: stripe_analytics queries metrics and runs reports (natural-language SQL needs Sigma), and get_balance_summary for Treasury is in public preview.

Tool calls are logged, and Stripe points to MCP tool call logs in Workbench for reviewing what an agent did. If you run a Connect platform, you can act for a connected account by sending a Stripe-Account header, but only with a restricted key: OAuth does not cover connected accounts.

What must never be automated without a person

Anything that moves money out, changes what customers pay, or cannot be undone needs a person to approve it every time. That means refunds, payouts and outbound transfers, creating or updating prices, coupons, promotion codes and payment links, canceling subscriptions, voiding invoices or marking them uncollectible, and changing tax settings or webhook endpoints.

Stripe helps with some of this. When an agent acts on your behalf through OAuth, Stripe requires human confirmation before certain stripe_api_write actions, such as refunds and outbound payments: the agent hands you a link, you review and approve, and it retries. An unapproved request expires after 24 hours. For agent keys, Stripe’s two-party approval rules↗ (opens in a new tab) come with defaults for refunds and subscription cancellations, and an admin can add rules for created payment intents, new subscriptions, credit notes and bank account changes, with conditions on amount or rate, and a reviewer who is never the requester.

Price changes are not on Stripe’s list of approvable actions, so there your own client is the only gate. Keep stripe_api_write on ask in Claude Code, even if you allow the read tools, and never add it to an allow rule. How allow and ask rules behave in each permission mode is in Claude Code auto-approve.

{
  "permissions": {
    "allow": [
      "mcp__stripe__stripe_api_search",
      "mcp__stripe__stripe_api_details",
      "mcp__stripe__stripe_api_read",
      "mcp__stripe__search_stripe_documentation"
    ],
    "ask": ["mcp__stripe__stripe_api_write"]
  }
}

Stripe also warns about the other direction: turn on human confirmation of tools, and be careful running Stripe beside other MCP servers, because of prompt injection. Customer names, descriptions, metadata and dispute evidence are text written by other people. An agent that reads a customer record and can also issue a refund is exactly the combination described in indirect prompt injection.

The Stripe Agent Toolkit, in one line

If you are building your own agent rather than connecting an assistant, the Stripe Agent Toolkit gives LangChain, the OpenAI Agents SDK, CrewAI and the Vercel AI SDK Stripe tools through function calling, in TypeScript (@stripe/agent-toolkit) and Python (stripe-agent-toolkit); it now lives in Stripe’s stripe/ai repository↗ (opens in a new tab), which absorbed the old agent-toolkit repository.

Where the approvals and follow-ups go

The safe pattern is an agent that investigates and a person who acts. With fenbs connected beside Stripe at https://fenbs.ai/api/mcp, an agent working a dispute or a failed invoice can write up what it found as a task in To Do, with the Stripe object IDs in the note and the proposed action in the plan, and a person decides whether to refund, retry or change the price. Record the line itself, such as “no agent issues refunds or changes prices”, as a rule on the Decisions and rules page, which every connected assistant reads before it starts, and History shows which assistant filed or updated each task.

Be clear about the limits. fenbs does not approve or block anything in Stripe; Stripe’s confirmations, approval rules and your client’s prompts do that. And keep card data, bank details and customer personal data out of task notes entirely: an object ID is enough for a person with Stripe access to find the rest.