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

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.