Stripe MCP: The Complete Guide to Connecting AI Agents to Stripe

Want an AI agent to spin up a customer, draft an invoice, or refund a charge without you hand-writing the API calls? That's the pitch of Stripe MCP, Stripe's implementation of the Model Context Protocol (MCP). It's a server that hands an AI agent a set of tools for talking to the Stripe API and searching Stripe's knowledge base. Plug it into something like Cursor, Claude Code, or ChatGPT and you can create customers, draft invoices, generate payment links, issue refunds, manage subscriptions, and pull up Stripe docs, all in plain language. No API plumbing required. This guide walks through what the server is, how to set it up locally or remotely, the tools it ships with, and the part most write-ups skip: how to run it safely inside a production agent.

What is the Stripe MCP server?

What is the Model Context Protocol (MCP)?

MCP is an open standard for wiring AI applications up to external tools and data. Anthropic introduced it in November 2024 (see modelcontextprotocol.io), and plenty of AI editors and agent runtimes have picked it up since. The docs call it "an open protocol supported across a wide range of clients and servers." Why does it matter? Standardization. Rather than every vendor inventing its own integration shape, a provider ships one MCP server and any MCP-compatible client just works.

What Stripe MCP does

Per Stripe's documentation, "The Stripe Model Context Protocol (MCP) server provides a set of tools that AI agents can use to interact with the Stripe API and search our knowledge base (including documentation and support articles)."

So there are really two jobs here:

• Acts on your Stripe account. Create and list customers, products, prices, invoices, payment links, refunds, subscriptions, and more.
• Answers questions about Stripe. search_stripe_documentation searches Stripe's docs and support articles, so an agent can ground its code suggestions in the actual API.

Stripe MCP vs the Stripe Agent Toolkit

People mix these up. They're related, but they aren't the same thing. The broader Stripe Agent Toolkit (@stripe/agent-toolkit, Python + TypeScript) wires Stripe into agent frameworks like the OpenAI Agents SDK, LangChain, CrewAI, and the Vercel AI SDK through function calling, built on Stripe's official SDKs. The MCP server is the MCP-format surface of those same tools. Both now live in the stripe/ai monorepo (the old stripe/agent-toolkit repo redirects there). Rule of thumb: grab the Agent Toolkit when you're embedding Stripe inside a framework-based agent, and the MCP server when you want an MCP client to talk to Stripe.

Remote vs local: two ways to run Stripe MCP

There's one official MCP server, with two access modes.

Remote (recommended). Stripe hosts a server at https://mcp.stripe.com. It connects clients via OAuth per the MCP spec, and for clients that don't speak OAuth it'll also accept an API key as a Bearer token in the Authorization header.

Local. You can run a launcher with npx -y @stripe/mcp --api-key=.... Here's a nuance worth flagging. In the current package line (latest 0.3.3, published March 2026), the local @stripe/mcp is a thin stdio-to-HTTP proxy. It forwards your local MCP client's traffic to https://mcp.stripe.com, attaching your key as a Bearer header. It does not run the tools fully offline. Same https://mcp.stripe.com URL behind both modes.

Heads-up on stale tutorials: the widely-copied npx -y @stripe/mcp --tools=all --api-key=... command no longer works as advertised. The --tools flag has been removed. Pass it now and you just get a warning that "Tool permissions are now controlled by your Restricted API Key (RAK)." The only accepted arguments are --api-key and --stripe-account. Tool scoping is now controlled by your Restricted API Key (more on that below).

What can the Stripe MCP server do? (tools reference)

Stripe's docs list roughly two dozen tools, grouped by resource type. Which ones actually show up depends on what your Restricted API Key is allowed to do.

Account and balance

• get_stripe_account_info
• retrieve_balance

Customers, products, and prices

• create_customer, list_customers
• create_product, list_products
• create_price, list_prices

Payment links and payment intents

• create_payment_link
• list_payment_intents

Invoices and invoice items

• create_invoice, create_invoice_item, finalize_invoice, list_invoices

Coupons, refunds, subscriptions, and disputes

• create_coupon, list_coupons
• create_refund
• cancel_subscription, list_subscriptions, update_subscription
• list_disputes, update_dispute

Search and documentation

• search_stripe_resources, fetch_stripe_resources
• search_stripe_documentation: searches Stripe's knowledge base, docs, and support articles

How to get started with the Stripe MCP server

Prerequisites: create a Restricted API Key

First thing, before you connect anything: create a Restricted API Key (RAK), prefixed rk_, at the API keys dashboard. Stripe pushes hard for restricted keys over full secret keys (sk_) because they let you "limit your agent's access to exactly the functionality it requires." And since the --tools flag is gone, the RAK's permissions are now what decides which MCP tools an agent can even see and call. Build in sandbox/test mode first. MCP access is managed separately for sandbox and live.

Option A: connect to the remote server

For Claude Code, register the hosted server over HTTP transport:

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

The first command adds the remote server (OAuth); the second confirms it's connected. This is the cleanest path for Claude Code Stripe MCP setups, since OAuth keeps credentials out of your config files.

Option B: run it locally with npx

npx -y @stripe/mcp --api-key=YOUR_STRIPE_SECRET_KEY

For Stripe Connect platforms acting on a connected account:

npx -y @stripe/mcp --api-key=YOUR_STRIPE_SECRET_KEY --stripe-account=CONNECTED_ACCOUNT_ID

You can also supply the key via a STRIPE_SECRET_KEY environment variable instead of passing --api-key. There's a Docker image too, mcp/stripe.

Client setup

Cursor (Stripe MCP Cursor) works remote or local. Remote:

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

Local:

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp@latest"],
      "env": { "STRIPE_SECRET_KEY": "<<YOUR_SECRET_KEY>>" }
    }
  }
}

Claude Desktop. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp@latest"],
      "env": { "STRIPE_SECRET_KEY": "<<YOUR_SECRET_KEY>>" }
    }
  }
}

VS Code (note the top-level key is servers, not mcpServers):

{
  "servers": {
    "stripe": {
      "type": "http",
      "url": "https://mcp.stripe.com"
    }
  }
}

Windsurf uses the file ~/.codeium/windsurf/mcp_config.json, with the same local npx shape as Cursor/Claude Desktop above.

Any other MCP client. Point it at the remote URL with a Bearer header:

{
  "stripe": {
    "url": "https://mcp.stripe.com",
    "headers": { "Authorization": "Bearer <<YOUR_SECRET_KEY>>" }
  }
}

And if you want, you can call a tool over raw HTTP JSON-RPC:

curl https://mcp.stripe.com/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <<YOUR_SECRET_KEY>>' \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"create_customer","arguments":{"name":"Jenny Rosen","email":"jenny.rosen@example.com"}},"id":1}'

Administrators turn MCP on per environment under Dashboard > Settings > MCP, and OAuth sessions can be revoked under user settings.

Stripe MCP in practice: natural-language use cases

The tools map straight onto Stripe primitives, so the prompts end up reading like things you'd just say out loud:

• "Create a customer named Alice with email alice@example.com" → create_customer
• "Draft an invoice for $200 and finalize it" → create_invoice + finalize_invoice
• "Issue a $50 refund for the latest payment" → create_refund
• "How do I set up a usage-based subscription?" → search_stripe_documentation

This is where Stripe MCP payments workflows earn their keep. Support agents working through refunds and disputes. Billing agents drafting invoices. Developer assistants that answer Stripe API questions from the live docs instead of guessing.

Is the Stripe MCP server safe? Security best practices

Financial tools aren't the place to wing it. Give an agent the wrong scope and it can fire off create_payment_link, create_refund, or the destructive cancel_subscription with no undo. Stripe's official guidance gets specific:

• Use Restricted API Keys (`rk_`) scoped to only the functionality the agent needs, not full secret keys. (The local launcher will even print a warning if you pass an sk_ key.)
• Never embed keys in code. Stripe says to "provide API keys to your agent through a secrets vault or environment variable."
• Operate in sandbox/test mode while building; MCP access is managed separately for sandbox vs live.
• Enable human confirmation of tool execution so a person approves high-risk actions.
• Prefer OAuth where the client supports it. It's more granular, user-scoped, and revocable than a raw secret key.
• Watch for prompt injection when combining the Stripe MCP server with other MCP servers. Stripe explicitly recommends "exercising caution when using the Stripe MCP with other servers to avoid prompt injection attacks." A tool that reads free-text (support tickets, records) can carry instructions that hijack the agent.

A model that holds up in practice: the agent proposes a financial action, a human approves anything past a threshold, and every call gets logged.

Running Stripe MCP at scale in an agent workforce

There's a quieter production problem the setup guides rarely get into: tool overload. Hand a generic LLM two dozen-plus tools (and third-party connectors that wrap the API can expose way more) and tool-selection accuracy starts slipping while cost and latency creep up. A finance agent rarely touches search_stripe_documentation. A support agent probably shouldn't see create_payment_link at all.

So you curate. Scope each agent role down to the smallest toolset that does the job, read-only for support, full read/write for finance, enforced at the RAK level. This is exactly the kind of work gamut.so (the platform behind Datawizz) is built for: running an AI agent knowledge workforce on specialized language models, where tool routing and per-role scoping let a smaller, focused model with a curated toolset outperform a large generic model with everything switched on. Once you're moving Stripe MCP from a demo into something that touches real money, that governance layer is where reliability comes from.

Beyond tool access: how agents actually pay

Worth pulling two ideas apart here. Stripe MCP gives an agent tool access to your Stripe account. It is not, on its own, a rail for an agent to go out and autonomously spend money on the open market. Stripe is building that part separately. The Agentic Commerce Protocol (co-developed with OpenAI) powers Instant Checkout in ChatGPT, the Shared Payment Token lets an app kick off a payment without exposing card credentials, and the Machine Payments Protocol targets streaming agent-to-agent micropayments. Even Stripe's own leadership stays measured about it: the Collison brothers' early-2026 annual letter said agentic commerce "suffers from having been overhyped too early in some corners." For most teams right now, the practical, shipping value is the MCP server and Agent Toolkit. The payment-rail story is still maturing.

FAQ

What is the Stripe MCP server? A server implementing the Model Context Protocol that exposes Stripe API tools and a documentation search to any MCP-compatible AI client.

What's the difference between the remote and local server? Remote (https://mcp.stripe.com) is hosted by Stripe with OAuth or Bearer auth. The local @stripe/mcp package is a stdio-to-HTTP proxy that forwards to that same remote server using your API key.

How do I add Stripe MCP to Claude Code? Run claude mcp add --transport http stripe https://mcp.stripe.com/, then claude /mcp to verify.

Is `--tools=all` still valid? No. The --tools flag has been removed; tool scoping is now controlled by your Restricted API Key permissions.

Should I use a secret key or a restricted key? A Restricted API Key (rk_). Stripe strongly recommends it over a full secret key.

How do I authenticate, OAuth or API key? Use OAuth where the client supports it (more granular and revocable); otherwise pass a restricted key as a Bearer token.

Can Stripe MCP search Stripe documentation? Yes. The search_stripe_documentation tool queries Stripe's docs and support articles.

Is it free? The MCP server itself is free; you still pay standard Stripe transaction fees on any payments processed.