Stripe MCP完全攻略 2026 — 公式リモートサーバー・25ツール・Restricted API Key、決済エージェントで詰まる8つのポイント

なぜStripe MCPが2026年の決済エージェント標準になりつつあるのか

Stripeはグローバルなdeveloper-first決済プラットフォームで、Payments・Subscriptions・Invoicing・Connect・Issuingなど決済ライフサイクル全域を網羅している。2024年末に Stripe Agent Toolkit を公開、2025年から2026年にかけて公式MCPサーバーとして拡張し、2026年4月のStripe Sessionsで v0.3.3 として OAuth+DCR対応・Restricted API Keyの統合などを発表した。

KanseiLinkのデータでは、Stripe(stripe-global)は信頼スコア0.7・AEOグレードA・公式MCPステータス。Agent Toolkitは Python と TypeScript の両方で提供され、OpenAI Agents SDK・LangChain・CrewAI・Vercel AI SDK の主要エージェントフレームワークから直接呼べる。決済はインフラ性が高くロックインも強い領域だが、Stripeはここで『AIエージェント時代の標準』のポジションを早期に取りに来ている。

アーキテクチャ — リモート(mcp.stripe.com)とローカル(@stripe/mcp)

Stripeは公式に2系統のMCPを用意している。

1. リモートホスト型: mcp.stripe.com

Stripe社が運用するリモートMCPサーバー。MCPクライアント(Claude Desktop / Cursor / その他MCP対応エージェント)は OAuth + Dynamic Client Registration(DCR) で接続できる。アプリの事前登録は不要で、初回接続時にユーザーがブラウザでStripeにログインしスコープを承認するだけで利用開始できる。

// MCPクライアント設定の例 (リモート)
{
  "mcpServers": {
    "stripe": {
      "url": "https://mcp.stripe.com",
      "transport": "http"
    }
  }
}

2. ローカル(stdio)型: npx -y @stripe/mcp

自社ネットワーク内に閉じたい・CI環境で動かしたい・Restricted API Keyを環境変数で渡したい——というケース向けのstdio起動型パッケージ。Stripe API Keyを環境変数 STRIPE_SECRET_KEY 等で注入する。

// MCPクライアント設定の例 (ローカル)
{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp", "--tools=all"],
      "env": {
        "STRIPE_SECRET_KEY": "rk_test_xxxxx"
      }
    }
  }
}

認証 — Restricted API Keyが本番の標準

Stripeの認証は『API Key as Bearer Token』方式で、Authorizationヘッダーに Bearer sk_xxx あるいは Bearer rk_xxx を載せる。キーには複数の種類があり、エージェント運用での選び方が安全性を大きく左右する。

OAuth + Dynamic Client Registration の効果

リモートMCPサーバー(mcp.stripe.com)はMCP仕様の Dynamic Client Registration(DCR)に準拠している。従来は『OAuthアプリの個別登録 → Client ID/Secret 発行 → コールバックURL設定 → 環境変数注入』が必要だったが、DCRではMCPクライアントが初回接続時に自動的にOAuthクライアントを動的登録 する。ユーザーは『Stripeにログインしてスコープ承認するだけ』。これはLinear・Notion等と同じ最新パターンで、エージェント運用の摩擦を大幅に削っている。

Stripe APIの構造的な罠 — Form-encoded / 最小通貨単位 / Idempotency-Key

Stripe APIには『普通のJSON APIではない』構造的な特徴が3つあり、エージェント開発で必ずぶつかる。

罠1: リクエストはForm-encoded、レスポンスはJSON

Stripeのリクエストボディは application/x-www-form-urlencoded。Content-Type を application/json で送ると失敗する。エージェントフレームワークの多くはデフォルトでJSONを送るため、Stripeを直接叩くカスタムコードを書く場合は明示的にform-encodedに切り替える必要がある。公式MCPサーバー経由ならこの差分は内部で吸収される ため、可能なら公式MCPを優先する根拠の一つだ。

POST /v1/payment_intents HTTP/1.1
Host: api.stripe.com
Authorization: Bearer rk_test_xxxxx
Content-Type: application/x-www-form-urlencoded   # ← JSONではない

amount=2000&currency=jpy&payment_method_types[]=card&
description=Order%20%231234

罠2: 金額は『最小通貨単位の整数』

Stripeは全通貨で整数を扱う。USD・EURのような2桁小数の通貨は『100倍した値』、JPYのような小数を持たない通貨は『そのままの値』。エージェントがユーザーから『2,000円』『$20』のような自然言語を受け取った場合、通貨ごとに変換ロジックを分岐する必要がある。

• amount=2000, currency=jpy → ¥2,000
• amount=2000, currency=usd → $20.00
• amount=2000, currency=eur → €20.00

罠3: Idempotency-Keyで二重課金を構造的に防ぐ

決済は『二重実行が許されない』典型操作。StripeはこれをHTTPヘッダー Idempotency-Key で設計している。同じキーで再送されたリクエストは、Stripe側で『初回の結果』を返し、二重課金を起こさない。

POST /v1/payment_intents HTTP/1.1
Authorization: Bearer rk_live_xxxxx
Idempotency-Key: order_1234_attempt_1   # ← トランザクション単位で生成
Content-Type: application/x-www-form-urlencoded

amount=2000&currency=jpy&payment_method=pm_xxxxx&confirm=true

エージェントが本番でリトライを組む際の最小ルールは: (1)決済操作には必ず冪等キーを付ける、(2)キーはトランザクション単位で生成しUUIDで管理、(3)リトライ時は同じキーを使う。これでネットワーク不安・タイムアウト由来の二重課金は構造的に防げる。

25ツール・主要オブジェクト — Payment Intents・Subscriptions・Invoices

Stripe公式MCP v0.3.3 は約25ツールを提供し、決済ライフサイクル全域をカバーする。主要なツール群は以下:

• Payment Intents: 支払い意図の作成・確認・キャンセル (Charges API は非推奨)
• Customers: 顧客の作成・更新・検索
• Products / Prices: 商品・価格の管理
• Invoices: 請求書の作成・取得・finalize / send
• Subscriptions: サブスクリプションの作成・更新・キャンセル
• Refunds: 返金処理(全額・部分)
• Payment Links: 共有可能な決済リンクの生成
• Documentation Search: Stripeドキュメントの知識ベース検索

決済エージェント開発で詰まる8つのポイント

❌ 1. Secret Keyをそのまま注入

RAKに移行し、エージェントが必要な操作だけ許可。Stripe ダッシュボード > Developers > API keys からリソース単位で権限を絞る。

❌ 2. JSON で送ってしまう

Content-Type は application/x-www-form-urlencoded。公式MCPサーバー経由なら自動で扱われるが、直接叩く場合は注意。

❌ 3. 金額の単位ミス(USD/JPYの混同)

USDは100倍、JPYはそのまま。通貨と金額をペアで扱う型を導入する。

❌ 4. Idempotency-Keyを使わない

リトライで二重課金を起こさないため、決済操作には必ず冪等キーを付ける。

❌ 5. Webhookシグネチャ未検証

Webhookエンドポイントは必ず Stripe-Signature ヘッダーをendpoint secretで検証する。検証なしのWebhookは偽造リクエストを受け入れてしまう。

❌ 6. テストモードと本番モードの取り違え

sk_test_ / rk_test_ はテストモード、sk_live_ / rk_live_ は本番モード。エージェント環境変数で明確に分離し、混在を防ぐ。

❌ 7. cursor-based pagination の誤実装

Stripeのページネーションは starting_after=<最後のオブジェクトID> 方式。デフォルト10件、最大100件。全件取得は明示的にループする必要がある。

❌ 8. エラーオブジェクトのパース忘れ

Stripeのエラーは {"error":{"type":"card_error","code":"card_declined","message":"..."}} 形式。HTTP 402(payment required)は『カード拒否』の合図。type / codeで分岐し、ユーザーに何を伝えるかを設計する。

PAY.JP・Square・LINE Payとの比較

『グローバルにスケールするSaaSやEC』ならStripeが第一選択、『日本国内ECで国内銀行口座への売上振込・電子帳簿対応』ならPAY.JP、『店舗POS + 短期売掛』ならSquare、『LINEユーザーへのQR決済』ならLINE Pay、という棲み分けが2026年の現実解。エージェント連携の成熟度はStripeが頭一つ抜けており、新規エージェント設計はStripeを軸に置き、国内特殊要件のあるユーザーセグメントだけ補完するパターンが多い。

本番投入前チェックリスト

• Secret Keyではなく rk_live_ Restricted API Keyを発行している
• エージェントが必要なリソース(Payments・Customersなど)のみ書き込み権限を付与している
• Content-Type は form-encoded、レスポンスは JSON である前提で実装している
• 通貨と金額を必ずペアで扱う型・ヘルパー関数を導入している
• 決済操作には必ず Idempotency-Key ヘッダーを付与し、UUIDで管理している
• Webhookエンドポイントで Stripe-Signature をendpoint secretで検証している
• テストモード(sk_test_/rk_test_)と本番モードを環境変数で明確に分離している
• Payment Intents APIを使い、レガシーの Charges API は使っていない
• エラーレスポンスの type / code を分岐ロジックに組み込んでいる
• テストカード番号(4242 4242 4242 4242, 4000 0000 0000 0002)で正常/拒否ケースをCIに含めている

FAQ

Q1. Stripe公式MCPと3rdパーティMCPはどちらを選ぶべきですか?

原則は公式(mcp.stripe.com または @stripe/mcp)です。KanseiLinkデータでは公式の stripe-global は信頼スコア0.7・AEOグレードAで、3rdパーティの stripe-jp(同0.6・成功率73%・33件報告)を上回ります。3rdパーティを選ぶのは『公式が提供していないカスタムツール』が必要な特殊ケースに限定するのが妥当です。

Q2. Restricted API Keyのスコープ設計はどう始めるべきですか?

『最小権限の原則』で組みます。新規顧客の決済を扱うエージェントなら Customers: Write / Payment Intents: Write / Charges: Read 程度から始め、必要に応じて拡張。Refunds や Subscriptions を扱うのは別キーに分離するのが安全。Stripe ダッシュボードで複数のRAKを発行し、エージェント単位で割り当てます。

Q3. テスト環境でPayPay等の国内決済を試せますか?

テストモード(sk_test_)でPayPayを含む payment_method を選択するテストカード/フローが提供されています。本番環境で日本円・PayPayを使うには、Stripe Japanアカウントの本番有効化(法人情報・本人確認)が必要です。

Q4. Subscriptionsをエージェントで自動管理する際の注意点は?

(1)プラン変更時の按分(proration)を proration_behavior で明示する、(2)失敗時の dunning(再試行)ロジックはStripeのSmart Retriesに任せる、(3)解約はユーザー意図を必ず確認しエージェントの暴走による誤キャンセルを防ぐ。Stripe Billingの自動催促を活用し、エージェントは『判断と承認』を担う層に留めるのが現実的です。

Q5. KanseiLink上でStripe公式(stripe-global)はなぜ AAA ではなく A なのですか?

2026-05時点で stripe-global の usage_count が 0件で実エージェント挙動データが未蓄積のためです。技術仕様・MCPステータスは A グレード相当ですが、実エージェントが本番でどれくらい成功したか(サンプル数)が貯まると AAA に昇格する可能性は十分あります。エージェント開発者が report_outcome でデータを返してくれると業界全体の検証が早まります。

Q6. 公式MCPサーバーがアクセス制限される国・地域はありますか?

本記事公開時点で、Stripe MCPサーバー自体に地域制限は確認されていません。ただしStripeアカウント自体は対応国・通貨に制約があるため、エージェントが扱える決済範囲はアカウントの所在国・サポート通貨に依存します。グローバル展開を前提とするなら Stripe Connect のマルチアカウント戦略も検討してください。