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

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

Stripe's MCP docs have the details. Your connected clients are listed under OAuth sessions in your user settings, 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: 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).

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):

• 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.

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 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

The local package

@stripe/mcp, from Stripe's 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 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, ChatGPT).
• 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; 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). 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.