# Stripe MCP server: URL, setup, tools and agent API keys

> Stripe's official MCP server at mcp.stripe.com: OAuth or agent API keys, setup in Claude Code, Cursor and Codex, its tools, approvals for refunds, and fixes.

Updated 2026-11-04 · https://upsy.ai/guides/stripe-mcp-server

## Short answer

Stripe runs an official MCP server (a connector that lets an AI agent use your Stripe account) at `https://mcp.stripe.com`. Add it to your client and sign in to Stripe: on the consent page you pick the accounts and sandboxes the agent may use, and whether it may read or also write in each. In Claude Code:

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

Then run `/mcp` to sign in. Or run `stripe agent setup` from the Stripe CLI, which sets up Claude Code, Codex and Cursor for you. For agents that can't use OAuth, Stripe now wants an **agent API key**: from December 2026, the server stops accepting plain secret keys and untagged restricted keys. Stripe's server is enough for most people; add Stripe through Upsy if you want it in the same connection as your other apps, with a level for each agent.

## Stripe's MCP server

| | |
|---|---|
| Address | `https://mcp.stripe.com` (Streamable HTTP, no SSE) |
| Status | Public preview |
| Sign-in | OAuth with dynamic client registration, or an agent API key as `Authorization: Bearer` |
| Access | Chosen on Stripe's consent page: live accounts and sandboxes, with different permissions for each |
| Connect platforms | An agent API key with the `Stripe-Account` header. OAuth doesn't cover connected accounts |
| Admin | Team-wide on or off, separately for live mode and sandboxes, at [MCP and CLI access](https://dashboard.stripe.com/settings/mcp-and-cli-access) |
| Logs | Workbench › Logs › MCP tool calls |
| Limits | Stripe's API limits: 100 requests a second in live mode, 25 in a sandbox ([rate limits](https://docs.stripe.com/rate-limits)) |

Stripe's [MCP docs](https://docs.stripe.com/mcp) have the details. Your connected clients are listed under **OAuth sessions** in your [user settings](https://dashboard.stripe.com/settings/user), where **Revoke access** cuts one off. Admins can revoke anyone's sessions from **Team and security**.

### The agent API key change

"Starting in December, Stripe MCP will stop accepting full-access secret keys and restricted API keys without the Agent tag." So an `sk_` key, or an `rk_` key created before, stops working after November 30, 2026, and the server answers with a `401` that points the client to OAuth.

To keep a key-based setup working, create an [agent API key](https://docs.stripe.com/keys#agent-keys): a restricted key you mark as authorizing agent access when you create it, with only the permissions the agent needs. It shows an **Agent** badge in the Dashboard. Or reconnect with OAuth.

### Connect it to your client

**Any supported client.** `npm install -g @stripe/cli@latest`, then `stripe agent setup`. It finds Claude Code, Codex and Cursor and configures them ([Stripe CLI](https://docs.stripe.com/cli/agent/setup)).

**Claude Code.** Run the command above, then `/mcp` and sign in. Stripe also has a Claude Code plugin in Anthropic's official plugin directory. With an agent API key instead, put `"headers": {"Authorization": "Bearer ${AGENT_API_KEY}"}` in `.mcp.json`.

**Claude.** Add Stripe from Claude's connector directory. On Team and Enterprise, an Owner adds it first.

**Cursor.** Add `{"mcpServers":{"stripe":{"url":"https://mcp.stripe.com"}}}` to `~/.cursor/mcp.json`, or type `/add-plugin stripe`.

**VS Code.** Add `{"servers":{"stripe":{"type":"http","url":"https://mcp.stripe.com"}}}` to `.vscode/mcp.json`.

**Codex.** Run `codex mcp add stripe --url https://mcp.stripe.com`, or install the plugin with `codex plugin add stripe@openai-curated`. With an agent API key, set `bearer_token_env_var = "AGENT_API_KEY"` in the server's entry in `config.toml`.

**ChatGPT.** Install Stripe's plugin from ChatGPT's plugin directory.

**Gemini CLI.** Run `gemini extensions install https://github.com/stripe/ai`, then `/mcp auth stripe`.

### Its tools

Stripe's server now has a few general tools instead of one per action. `stripe_api_read` and `stripe_api_write` call any method on Stripe's list of supported API methods, which keeps the tool list short ([tools](https://docs.stripe.com/mcp#tools)):

| Area | Tools |
|---|---|
| API | `stripe_api_search`, `stripe_api_details`, `stripe_api_read` (any supported `GET`), `stripe_api_write` (any supported `POST`, `PATCH`, `PUT` or `DELETE`) |
| Account | `get_stripe_account_info` |
| Analytics (preview) | `stripe_analytics` |
| Treasury (preview) | `get_balance_summary`, `setup_recipient`, `convert_currency`, `send_money`, `transfer_money` |
| Atlas | `atlas_company_formation` |
| Other | `search_stripe_documentation`, `stripe_implementation_planner`, `send_stripe_feedback` |

- **What `stripe_api_write` can do** includes creating and updating customers, invoices, subscriptions, coupons, payment links, Checkout Sessions and webhook endpoints, cancelling subscriptions, and creating refunds. Payouts are read-only.
- **Old tool names are gone.** Pages that list 31 tools such as `create_customer` and `create_refund` describe the earlier version.
- **Docs search needs a sign-in too.** There's no separate docs-only server; without an account, read Stripe's [llms.txt](https://docs.stripe.com/llms.txt).

### Approvals for money moves

Some actions carry **Human confirmation**: creating a refund, and Treasury's `convert_currency`, `send_money` and `transfer_money`. The agent gets a link instead of a result. You click **Approve** in the Dashboard, then tell the agent to try again. An unapproved request expires after 24 hours.

Agent API keys also come with [approval rules](https://docs.stripe.com/account/approvals) for refunds, cancelled subscriptions, outbound payments and transfers, payouts and currency conversions. A blocked call returns `approval_required`.

Stripe also asks you to turn on your client's tool-approval setting, and to take care with prompt injection when Stripe is connected next to other servers.

### Where Stripe's server stops

- **It's a preview.** Tools and limits may change, as the switch to `stripe_api_read` and `stripe_api_write` showed.
- **Write is broad.** With write access, `stripe_api_write` covers every supported write method. Narrower limits need an agent API key with only some permissions, or your client's per-tool settings.
- **No record across your other apps.** Stripe logs its own MCP calls in Workbench; what the agent did elsewhere is in each client.

For one or two clients, Stripe's server, with its OAuth permissions and approvals, is enough.

## Stripe MCP servers compared

| | Stripe's server | Upsy | `@stripe/mcp` (local) |
|---|---|---|---|
| Who runs it | Stripe | Upsy, on top of Stripe's server | You, as a local proxy to Stripe's server |
| Sign-in | OAuth, or an agent API key | OAuth to Upsy; Upsy signs in to Stripe | An API key |
| Tools | Stripe's | Stripe's, listed on request | Stripe's, through the proxy |
| Limits | Read or write per account and environment; key permissions; approvals | Picked tools per agent, on top of Stripe's | The key's permissions |
| Accounts | Several, picked at sign-in | Several, each with its own access | One key per proxy |
| Record | Workbench MCP logs | Upsy's History, next to your other apps | Workbench MCP logs |

### The local package

`@stripe/mcp`, from Stripe's [stripe/ai](https://github.com/stripe/ai) repository (formerly `agent-toolkit`), used to run Stripe's tools on your machine. Since early 2026 it only forwards calls to the hosted server: `npx -y @stripe/mcp --api-key=KEY`, with `--stripe-account=acct_…` for a connected account. The old `--tools` flag now says it "has been removed" and that your key's permissions decide. Because it forwards your key, the December key change applies to it too. Stripe's docs describe only the hosted server.

Community servers such as `atharvagupta2003/mcp-stripe` call Stripe's API with your secret key, without Stripe's approvals.

## Upsy's Stripe MCP server

Upsy connects to Stripe's hosted server with your Stripe sign-in, so Stripe's consent page, permissions and approvals all still apply. It's the same address as Upsy's other apps, `https://upsy.ai/connect`.

What it adds:

- **Stripe next to your other apps.** One server holds Stripe, Gmail, Slack, Linear and more, so an agent can, say, read a customer's emails and their Stripe invoices in one request.
- **A level per agent.** Pick the Stripe tools each agent may use, such as `stripe_api_read` but not `stripe_api_write`, enforced by Upsy on top of what you allowed at Stripe. Claude Code can read while another agent may write, from one Stripe sign-in.
- **The same connection in every client:** Claude, Claude Code, Cursor, Codex, ChatGPT, Grok, Muse, or anything with remote MCP and OAuth.
- **History and alerts:** every Stripe tool an agent runs, listed under that agent with its other apps.

If you only use Stripe, in one or two clients, connect Stripe's server directly.

### Connect Stripe to Upsy

1. Go to [upsy.ai](https://upsy.ai) and click **Set up Upsy**.
2. Open **Apps**, click **Connect an app** and pick **Stripe**. On Stripe's consent page, choose the accounts and sandboxes, and read or write for each. Start with a sandbox if you're trying it out.
3. On the **Assistants** page, click **Add assistant** and choose your client under **Which assistant?** for its exact steps.

### Add the server to your client

Signing in opens an Upsy page: tick Stripe and click **Allow**. To limit an agent, use **Pick actions** for Stripe on its page afterwards.

- **Claude Code:** `claude mcp add --transport http --scope user upsy https://upsy.ai/connect`, then `/mcp` to sign in.
- **Cursor:** add `{"mcpServers":{"upsy":{"url":"https://upsy.ai/connect"}}}` to `~/.cursor/mcp.json`, then click **Connect** next to upsy.
- **Codex:** `codex mcp add upsy --url https://upsy.ai/connect`, then `codex mcp login upsy`.
- **Claude and ChatGPT:** add `https://upsy.ai/connect` as a custom connector ([Claude](/guides/claude/custom-connector), [ChatGPT](/guides/chatgpt/custom-connector)).
- **Grok and Muse:** paste the setup prompt Upsy shows into a chat and approve the sign-in.

Server details, such as OAuth endpoints and token lifetimes, are in the [Gmail MCP server guide](/guides/gmail-mcp-server#server-details); they're the same for Stripe.

### Check that it works

> Using Upsy, which Stripe account am I connected to? Then list my five most recent payments.

The agent should name the account, then list payments with amounts and dates. The calls show in Upsy's **History** under that agent, and in Stripe's Workbench logs.

### Picking Stripe tools

With **Pick actions**, a sensible start is `stripe_api_read`, `stripe_api_search`, `stripe_api_details`, `get_stripe_account_info` and `search_stripe_documentation`: the agent can look anything up but change nothing. Add `stripe_api_write` only for agents that should create customers, invoices or payment links, and keep Stripe's approvals on for refunds. **Read-only** allows only tools Stripe marks read-only, and never one whose name says it changes something, such as write, send or transfer.

## Troubleshooting

### `missing_api_key`: "No valid API key provided."

The client reached Stripe's server without signing in. Start the sign-in again: `/mcp` in Claude Code, or reconnect in your client.

### `invalid_api_key` after November 30

Your key is a plain secret key or an untagged restricted key, which Stripe's server no longer accepts. Create an agent API key, or switch to OAuth.

### "The provided key … does not have the required permissions"

Your agent API key lacks a permission the call needs. Edit the key's permissions in the Dashboard, or ask for something it can do.

### `approval_required`, or the agent sends you a link

The action needs your approval. Open the link, click **Approve**, then tell the agent to try again within 24 hours.

### "No such customer" or other missing objects

The object is in the other mode. Live mode and sandboxes don't share data, so check which environment the agent is using, and that you granted it at sign-in.

### Live mode is greyed out on "Choose an environment"

An admin may have turned MCP off for live mode under **MCP and CLI access**, or your role may not allow it. Ask an admin.

### Codex keeps saying "Authentication for Stripe was requested and accepted. Retry this tool call now."

An open Codex bug ([issue #55932](https://github.com/openai/codex/issues/55932)). Until it's fixed, use an agent API key with `bearer_token_env_var`.

### "The user hasn't allowed you to use Stripe's …"

That's Upsy refusing a tool outside the agent's level, such as `stripe_api_write` when you didn't pick it. Change Stripe's level on the agent's page in Upsy.

## Security and privacy

- **Try it in a sandbox first.** Grant live mode only once you trust the agent and the prompts you use.
- **Keep approvals on.** Turn on your client's tool approvals, and leave Stripe's approval rules on for refunds, payouts and transfers.
- **Least access.** At sign-in, give read access where it's enough. For keys, use agent API keys with only the permissions needed, and revoke sessions you no longer use under **OAuth sessions**.
- **Prompt injection.** An email, ticket or web page can carry instructions aimed at your agent, and Stripe warns about this when it shares a client with other servers. Keep write access away from agents that read untrusted content.
- **Through Upsy,** agents never get your Stripe token: they call Upsy, and Upsy calls Stripe. Upsy emails you when one agent reads 100 or more items in 10 minutes or deletes 50 or more, and when a new agent or app connects.

## FAQ

### What is the Stripe MCP server URL?

`https://mcp.stripe.com`, over Streamable HTTP. Sign in with OAuth, or send an agent API key as a bearer token.

### Is there an official Stripe MCP server?

Yes. Stripe hosts it, in public preview. Claude, ChatGPT, Cursor and Codex also list Stripe-made plugins or connectors that use it.

### How do I add the Stripe MCP server to Claude Code?

Run `claude mcp add --transport http stripe https://mcp.stripe.com/`, then `/mcp` to sign in, or run `stripe agent setup`.

### Can I still use my Stripe secret key?

Only until November 30, 2026. After that, Stripe's server accepts only agent API keys and OAuth.

### Can a Stripe MCP agent issue refunds?

It can ask to, with write access. Refunds carry Human confirmation, so you approve each one in the Dashboard first.

### Can I make the Stripe MCP server read-only?

Yes. Grant read access on Stripe's consent page, use an agent API key with read permissions only, or pick only Stripe's read tools for the agent in Upsy.

### Is `@stripe/mcp` still maintained?

It still works, but only as a local proxy to the hosted server. Stripe recommends connecting to `https://mcp.stripe.com` directly.

### Does the Stripe MCP server work in test mode?

Yes. Pick a sandbox on the consent page, or use an agent API key from a sandbox.

---

Upsy connects personal AI assistants (Muse, Grok, ChatGPT, Claude, Cursor, Claude Code, Codex, Devin) to your Gmail, Google Calendar, Google Drive, Slack, Notion and other apps through one MCP server, with a shared memory, files and a cloud browser signed in to your sites. You choose what each assistant may do in each app, see everything it did, and turn it off in one click. Upsy is free. To add Upsy to an assistant, add a remote MCP server (Streamable HTTP) named Upsy at https://upsy.ai/connect. It signs in with OAuth; there is no API key.