# Stripe MCP (`mcp.stripe.com`) — recurring OAuth session revocation, fix with a restricted key

A worked example of pitfall 9/10 in SKILL.md: a provider whose OAuth session dies
on a recurring basis, where the durable fix is to drop OAuth for a static API key.

## Symptom (the "dies after a while" complaint)
Stripe MCP works for a few days then goes "not connected." Auto-refresh is healthy
in between (the access token is 1h-lived and rotates fine), so it LOOKS like a
refresh-token expiry or a max-session cap — it is neither. Roughly weekly, Stripe
**revokes the entire OAuth grant server-side**. The next `grant_type=refresh_token`
POST returns:

```
HTTP 400  {"error":"invalid_grant","error_description":"Invalid refresh token"}
```

The whole grant is dead — not just the short-lived access token — so auto-refresh
cannot recover it. It requires a fresh interactive browser consent flow, which a
headless remote gateway cannot drive. Don't be fooled by a green smoke-test at any
given moment: the failure is intermittent revocation, not a permanently broken token.

## Why the three usual hypotheses are all wrong
Per Stripe's OAuth docs (https://docs.stripe.com/stripe-apps/api-authentication/oauth):
- **Access tokens** expire in **1 hour**.
- **Refresh tokens** expire after **1 year**, and are **rolled on every exchange** — so
  as long as you refresh at least once a year they never naturally expire.
- Hermes auto-refreshes independently of whether you call Stripe tools, so "not using
  the tools enough" is irrelevant.

So a *recurring* death cannot be refresh-token expiry (1yr) or "max OAuth session
length" (no clean documented cap). It is server-side session revocation. Do NOT
loop on refresh.

## The durable fix: drop OAuth, use a restricted API key as a Bearer token
Stripe's MCP docs (https://docs.stripe.com/mcp) are explicit that for
non-interactive / agent use, OAuth is the wrong tool — `mcp.stripe.com` accepts a
**static restricted key** (`rk_live_...`) as a Bearer token. A restricted key has
**no session, no refresh, no expiry** — it works until revoked, ending the re-auth
cycle entirely.

config.yaml change (no token files needed — delete the OAuth dance for this server):
```yaml
mcp_servers:
  stripe:
    url: https://mcp.stripe.com
    headers:
      Authorization: *** rk_live_..."      # restricted key from Dashboard
      # Stripe-Account: "acct_xxx"            # only for Connect platform / connected-account calls
```

Generate the key in Stripe Dashboard → Developers → API keys → **Restricted keys**.
Grant least-privilege scopes for what the bot actually does:
- account reads: **read** on Charges, Customers, Subscriptions, Coupons/Promotion codes
- refunds / writes: add the corresponding **write** scopes
Then `/reload-mcp` (full restart only if the breaker is tripped, per pitfall 7).

## Decision rule
For ANY unattended remote-gateway MCP server that keeps getting its session revoked
(`invalid_grant` on refresh, or `-32002 "Session expired"` after a successful refresh),
and whose provider offers a static API key — prefer the static key over OAuth. OAuth's
refresh dance is for interactive clients; it is a liability for a headless gateway.
Stripe (restricted key) and Linear (Personal API key) both fit this rule.