Connect Codex to Stripe

What you get

Stripe runs a remote MCP server at mcp.stripe.com and publishes a local stdio package, @stripe/mcp. Codex’s docs don’t mention Stripe, and Stripe’s install page doesn’t mention Codex, so everything below is a translation rather than a copy.

The remote server exposes a fixed tool surface instead of one tool per API endpoint. Four tools cover generic API access: stripe_api_search, stripe_api_details, stripe_api_read, and stripe_api_write. The rest are single-purpose: get_stripe_account_info, create_refund, search_stripe_resources, fetch_stripe_resources, search_stripe_documentation, stripe_implementation_planner, send_stripe_mcp_feedback, and stripe_report. Behind stripe_api_read and stripe_api_write sits Stripe’s “Supported API methods” list: customers, charges, refunds, PaymentIntents, invoices, subscriptions, products, prices, payment links, coupons, disputes, and tax settings.

Stripe’s install docs cover five clients as of 2026-07-16: Cursor, Claude Code, ChatGPT, VS Code, and a generic “Custom clients” HTTP path. I fetched that page directly and it doesn’t mention Codex, OpenAI’s CLI, or config.toml anywhere.

Setup

Remote (start here)

Stripe’s page says “We strongly recommend using restricted API keys to limit your agent’s access to exactly the functionality it requires,” and separately, “Don’t embed restricted or secret API keys in code. Instead, provide API keys to your agent through a secrets vault or environment variable.” Codex’s bearer_token_env_var does that second part, reading the token from your environment instead of storing it in the file.

[mcp_servers.stripe]
url = "https://mcp.stripe.com"
bearer_token_env_var = "STRIPE_SECRET_KEY"
default_tools_approval_mode = "writes"

That URL is the bare host. There is no /mcp path on it, which trips people who’ve configured other remote servers.

Export the key before you start Codex:

export STRIPE_SECRET_KEY=rk_live_...

On PowerShell: $env:STRIPE_SECRET_KEY = "rk_live_...". The variable name says secret, but a restricted rk_ key is what belongs in it.

Write that block by hand. codex mcp add takes stdio servers only, with a documented syntax of codex mcp add <name> --env VAR=VALUE -- <command>, and there’s no --url flag on it. Remote entries come from editing config.toml yourself or from the MCP UI in the desktop app or IDE extension. For OAuth instead of a key, run codex mcp login stripe. Stripe’s take: “OAuth is more secure than using your secret key because it allows more granular permissions and user based authorization.”

OAuth stops short at Connect. Stripe’s page says “Connect platforms can make MCP calls as their connected accounts. However, you can’t use OAuth. Instead, use restricted access keys with the appropriate Connect permissions.” Pass the account header next to the token:

[mcp_servers.stripe]
url = "https://mcp.stripe.com"
bearer_token_env_var = "STRIPE_SECRET_KEY"
default_tools_approval_mode = "writes"
http_headers = { "Stripe-Account" = "acct_xxxxxxxxx" }

Then confirm it came up:

codex mcp list

Stdio

@stripe/mcp is at 0.3.3, published 2026-03-24. Stripe’s own invocation is npx -y @stripe/mcp --api-key=YOUR_STRIPE_SECRET_KEY, and that’s the shape aggregator sites will hand you. Don’t put the key in args. Codex spawns the process without a shell, so the string you write is the string that shows up in your OS process list for anything that can run ps, and config.toml sits in plaintext on disk besides.

The package’s readme gives you the way out: “Alternatively, you could set the STRIPE_SECRET_KEY in your environment variables.” Codex forwards a named variable from its own environment with env_vars, so the key stays out of the file and out of the argument list:

[mcp_servers.stripe]
command = "npx"
args = ["-y", "@stripe/mcp"]
env_vars = ["STRIPE_SECRET_KEY"]
startup_timeout_sec = 30

For a connected account here, add --stripe-account=CONNECTED_ACCOUNT_ID to args. That’s an account ID rather than a secret, so it’s fine sitting there.

Gotchas

A cold npx has to download @stripe/mcp before it answers the handshake, which blows the default 10-second startup window. That’s what startup_timeout_sec = 30 above is for.

Codex doesn’t hand the server your whole shell environment. It builds the child’s environment from a short built-in whitelist, and env_vars is how you add to it. Exporting STRIPE_SECRET_KEY and then leaving env_vars out gets you a server that starts and then fails to authenticate.

There’s no --tools flag on the current package. Older Stripe agent-toolkit material and plenty of aggregator pages still show --tools=all, and the readme in stripe/ai has nothing like it. Tool permissions come from the key instead: “Tool permissions are controlled by your Restricted API Key (RAK).”

Skip the plugin path for now. Stripe’s stripe/ai repo does carry a Codex plugin, but its README says “This directory isn’t live in the Codex marketplace yet — submissions are still manual.” openai/codex #24771, open since 2026-05-27, reports the Stripe page appearing in Codex Desktop’s plugin catalog with an install that doesn’t work. The TOML above works today.

Keep default_tools_approval_mode = "writes" on. stripe_api_write and create_refund move real money, and a prompt injection that reaches them costs you more than a restart does.

Related

• Connect an MCP server: the general shape, both transports
• mcp_servers.<id>.command: stdio launcher syntax
• mcp_servers.<id>.url: remote endpoint and auth keys
• mcp_servers.<id>.env: env versus env_vars, and the environment whitelist
• mcp_servers.<id>.startup_timeout_sec: raising the handshake window
• “handshaking with MCP server failed”: when the launch itself dies
• Install Codex CLI: if you’re starting from zero