MCP Spotlight: Stripe MCP Server — 25 Tools, OAuth 2.0 + DCR, Knowledge Base Search, and the Payment-Agent Default of 2026
Server: Stripe MCP Server by Stripe Version: v0.3.3 (Stripe Sessions, April 2026) · License: Apache 2.0 (open source SDK) Tools: ~25 (payments + knowledge base) · Auth: API key, restricted key, OAuth 2.0 + DCR Coverage: Payments · Subscriptions · Invoicing · Connect · Issuing · Customers · Products · Prices · Refunds · Disputes · Payouts · Balance · Tax · Radar · Terminal Plus: Native Stripe Docs search · Support articles search · Stripe changelog Docs: docs.stripe.com/mcp Marketplace: marketplace.stripe.com/apps/stripe-mcp
Stripe is the global payments backbone for internet commerce. Every meaningful agent workflow that touches money — checkout flows, subscription management, refund handling, dispute response, revenue reporting — eventually needs Stripe. The official Stripe MCP Server is the bridge that lets AI agents participate in the full Stripe API surface, with a 25-tool design that splits into two layers: transactional tools that mutate the API and knowledge-base tools that search Stripe's docs, support articles, and changelog.
The April 2026 v0.3.3 release added OAuth 2.0 with Dynamic Client Registration (DCR) — a major step toward the "agent-as-first-class-Stripe-customer" model where SaaS products embed Stripe in their agents without sharing API keys. Stripe also lists the MCP server in the Stripe App Marketplace, with one-click install for ChatGPT, Claude, and Perplexity. This is the payment-agent default of 2026.
The Architecture: Two-Layer Design
The Stripe MCP server's tool surface is intentionally split into two layers:
Layer 1: Transactional Tools (~17 tools)
These are the operational tools that act on a Stripe account:
| Tool | What It Does |
|---|---|
create_customer | Create a new Customer object with metadata |
update_customer | Modify customer fields, payment methods, default currency |
list_customers | List customers with email/created/metadata filters |
create_payment_link | Create a one-time Payment Link for a Price |
create_payment_intent | Create a PaymentIntent with custom amount/currency/metadata |
create_invoice | Create an invoice for a customer with line items |
finalize_invoice | Finalize a draft invoice (moves it to Open state) |
create_subscription | Create a recurring subscription |
update_subscription | Update plan, quantity, trial, cancel-at-period-end |
cancel_subscription | Cancel a subscription immediately or at period end |
create_product | Create a Product (catalog item) |
create_price | Create a Price (one-time or recurring, fixed or metered) |
create_refund | Refund a charge, full or partial |
list_invoices | List invoices with status/customer/date filters |
list_subscriptions | List subscriptions with status/customer/price filters |
retrieve_balance | Get current balance, pending, available |
list_payouts | List payouts with status/date filters |
Layer 2: Knowledge Base Tools (~3 tools)
These search Stripe's docs and support surface:
| Tool | What It Does |
|---|---|
search_stripe_documentation | Search Stripe's official docs for API references, guides, integration patterns |
search_support_articles | Search Stripe's support knowledge base for common issues |
fetch_stripe_changelog | Read the Stripe API changelog for the latest changes |
The two-layer design is the architectural lesson. Most "API wrapper" MCP servers dump you in the API surface with no doc context. The agent has to guess the right endpoint. Stripe solves this with built-in doc search — the same agent that calls create_payment_intent can call search_stripe_documentation("payment intent confirmation") to get the current docs inline.
The Killer Combination: Doc Search + API Call
The pattern that makes Stripe MCP special:
User: "Help me integrate Stripe Checkout for a one-time $49 product
with a 14-day refund window and a custom branding color."
Agent:
1. search_stripe_documentation("checkout integration one-time payment")
→ Returns current Checkout integration guide
2. search_stripe_documentation("branding custom color checkout")
→ Returns current branding customization doc
3. create_product(name="My Product", description="...")
4. create_price(product=prod_123, unit_amount=4900, currency="usd")
5. create_payment_link(price=price_456, after_completion={...})
6. Returns the link to the user
The agent reads the current Stripe docs (Context7-style "always-current knowledge") and then makes the right API calls. The result: working integration code that uses current Stripe patterns, not stale training-data patterns.
OAuth 2.0 + Dynamic Client Registration
The April 2026 v0.3.3 release added OAuth 2.0 + DCR as a first-class auth mode. This is significant for the SaaS-embedded-agent model:
- For SaaS companies building Stripe-powered agents: Their users authorize the SaaS to act on their Stripe account via OAuth, no API keys exchanged
- For end users: The OAuth flow is standard Stripe — "Authorize [App] to access your Stripe account?", with a clear scope of what the agent can do
- For security teams: No long-lived API keys in agent config files, no shared secrets, scope-minimal access
Combined with Stripe's Restricted Keys (which can be scoped to a single resource, like one product or one customer), the auth model supports:
- Read-only agents — restrict to read scope, no mutation possible
- Refund-only agents — restrict to refund resources only
- Per-customer agents — restrict to a single customer ID
- Per-product agents — restrict to a single product catalog
This is the right auth model for production agents. The OAuth flow gives the user control. The restricted key gives the operator fine-grained scope. Facio's HITL gating gives per-operation review. Three layers of defense-in-depth.
The Stripe App Marketplace Listing
Stripe lists the MCP server in the Stripe App Marketplace — a one-click install for major AI surfaces:
- ChatGPT — Stripe is a verified App in the ChatGPT app directory
- Claude — official Anthropic connector with the Stripe MCP server
- Perplexity — for Pro users
- Cursor / Windsurf / Cline — via MCP config
The marketplace listing includes the OAuth flow, the scopes requested, the publisher identity (Stripe), and the privacy policy. For end users, this is the "Stripe-vetted, Stripe-blessed" signal that the integration is legitimate.
For SaaS products that embed Stripe in their own agents, the marketplace listing is also the template: list your MCP server in the AI-app directories, document the auth model, identify the publisher, give users a one-click install path.
Facio Integration
{
"mcpServers": {
"stripe": {
"command": "npx",
"args": ["-y", "@stripe/mcp"],
"env": {
"STRIPE_SECRET_KEY": "${credentials.STRIPE_SECRET_KEY}"
}
}
}
}
Facio's audit trail captures every Stripe MCP call with the tool, the parameters, the Stripe API response, and the resulting resource ID. For a regulated finance team (PSD3, DORA, PCI-DSS scope), this is the complete transactional record: "Agent created invoice in_1234 at 14:32 UTC for cust_5678, amount $4900 USD, status draft."
For HITL workflows, the tool annotations map to gate requirements with finance-grade rigor:
| Tool Class | Severity | Suggested Gate |
|---|---|---|
list_*, retrieve_*, search_* | Read | None — autonomous |
create_payment_link, create_customer | Write, low risk | Soft confirm |
create_invoice, finalize_invoice | Write, contextual | Hard confirm (creates collectible artifact) |
create_refund | Write, destructive | Hard confirm + reason required (money leaves the account) |
cancel_subscription | Write, destructive | Hard confirm + reason required (cancels recurring revenue) |
create_dispute_evidence | Write, contextual | Hard confirm (legally binding evidence submission) |
update_customer.default_payment_method | Write, contextual | Hard confirm (changes billing instrument) |
The Stripe use cases are the ones where HITL gating is non-negotiable. A hallucinated refund amount, a misclassified dispute response, a wrongly-cancelled subscription — these are real money consequences. Facio's destructive-hint annotations should be configured to require explicit human approval with a stated reason for any create_refund, cancel_subscription, or update_* on critical fields.
For multi-Stripe-account setups (one Stripe account per region, per business unit, per product line), the pattern is one MCP server per Stripe account, each with its own scoped restricted key. The agent switches context per account, the audit trail is per-account, and the HITL gating is per-account.
Quickstart
# 1. Get a Stripe API key (test mode for development)
# https://dashboard.stripe.com/test/apikeys
# 2. Install the Stripe MCP server
npm install -g @stripe/mcp
# 3. Configure your MCP client
{
"mcpServers": {
"stripe": {
"command": "npx",
"args": ["-y", "@stripe/mcp"],
"env": {
"STRIPE_SECRET_KEY": "sk_test_..."
}
}
}
}
# 4. First prompts
# "How do I integrate Stripe Checkout for a one-time payment? Show me current docs."
# "Create a $49 product called 'Annual Report' with a Payment Link and custom branding."
# "Refund the most recent charge to cus_ABC123 — reason: customer requested cancellation"
# "Show me all subscriptions set to cancel at period end, grouped by plan"
# "What's the current best practice for handling SCA on European cards?"
Use Cases
Integration code generation: "Help me integrate Stripe Checkout for my SaaS." Agent searches docs, finds the current pattern, generates working code, explains the key decisions.
Customer support automation: "This customer says they were double-charged. Find the duplicate charges and process a refund for the second one." Multi-step investigation + refund creation.
Subscription management: "For each customer on the Pro plan who hasn't logged in for 60 days, send a re-engagement email and offer a 20% discount for the next 3 months." Cross-tool workflow with Stripe as the billing source of truth.
Revenue reporting: "What's our MRR breakdown by product line and plan tier for the last 90 days?" Aggregate queries across subscriptions and invoices.
Dispute response: "A customer filed a dispute for charge ch_1234. Pull the charge, the related invoice, the customer's history, and draft a dispute response with evidence." Time-sensitive workflow where the agent's speed matters.
Tax setup: "We just expanded to Canada. What do I need to configure for Stripe Tax?" Doc search → current requirements → configuration plan.
Webhook debugging: "My customer.subscription.updated webhook isn't firing. Check the webhook endpoint config and the recent events." API introspection + log analysis.
Pricing experiments: "Create a new Price variant for our Pro plan: $99/mo and $990/yr with a 17% annual discount. Make it inactive until I confirm." Create resources in draft state, await confirmation.
Refund automation with policy: "Auto-approve refunds under $50 with reason 'customer requested'. Anything over $50 needs my approval." The MCP call surface + Facio's destructive gating enables this policy directly.
Connect platform management: "List all connected accounts with 'rejected' or 'restricted' status. For each, draft a remediation email to the account holder." Connect-specific tools with multi-tenant context.
The Two-Layer Pattern: A Template
Stripe's two-layer design — transactional tools + knowledge-base tools — is the template every "API + docs" MCP server should copy. The agent doesn't need to guess endpoints from memory; it searches the current docs inline, then calls the API with current parameter names.
For SaaS vendors with both an API and extensive documentation, this pattern is uniquely valuable:
- Stripe — payments API + docs
- Twilio — communications API + docs
- SendGrid — email API + docs
- Auth0 — identity API + docs
- Twilio Segment — CDP API + docs
- Datadog — monitoring API + docs
Every one of these would benefit from the Stripe pattern. The agent that calls create_* benefits from being able to call search_* first.
Bottom Line
The Stripe MCP Server is the payment-agent default of 2026. ~25 tools, two-layer design (transactional + knowledge base), Apache 2.0, OAuth 2.0 + DCR, Restricted Key support, Stripe App Marketplace distribution, maintained by Stripe itself.
For any agent that touches money — checkout integration, subscription management, refund handling, dispute response, revenue reporting — this is the bridge. The agent reads the current Stripe docs inline, makes the right API calls, and surfaces the transactions for human review. The full payments lifecycle, in one conversational surface.
For the broader MCP ecosystem, the two-layer pattern is the design lesson every "API + docs" vendor should copy. Don't ship just the API. Ship the docs search alongside. The agent doesn't need to memorize your API surface; it queries your docs at the moment of the call.
npx -y @stripe/mcp with STRIPE_SECRET_KEY=sk_test_... and your agent has Stripe.
MCP Spotlight is a series covering servers that give AI agents real capabilities. Every server is evaluated for design clarity, ecosystem impact, and integration fit with Facio's HITL-first agent runtime.