開発

Stripe MCPの使い方：接続手順とエージェントAPIキーの権限設計

Stripe MCPの使い方：接続手順とエージェントAPIキーの権限設計

Stripe MCPは、Stripeが公式に運営するMCPサーバーmcp.stripe.comに、Claude CodeやCursorなどのAIエージェントを接続してStripe APIを操作させる仕組みです。顧客や請求書の検索、商品と価格の作成、返金の申請まで、チャットからの指示で実行できます。この記事では、各クライアントからの接続設定、OAuthとエージェントAPIキーの使い分け、2026年11月30日が期限のキー移行、返金や解約に掛かる承認ルールの設計までを、設定ファイルの具体例を添えて解説する記事です。仕様は2026年10月19日時点の公式ドキュメントで確認しています。

まとめ｜Stripe MCPの接続先・認証方式・11月30日までのキー移行の要点

接続先はリモートのhttps://mcp.stripe.comの1つだけです。人が操作するClaude CodeやCursorはOAuthで接続し、無人で動く業務エージェントは「エージェント」のタグを付けた制限付きキーで接続します。

期限があります。2026年12月以降、全権限のシークレットキーとタグの無い制限付きキーは401で拒否されます。npxで動かすローカル版やAgent Toolkitも内部では同じサーバーに中継しているため、既存の設定は11月30日までにキーを差し替えてください。

本番データへの書き込みは、キーの権限をNoneから必要な分だけ開け、返金と解約には二者承認を掛けた状態で始めます。開発中のコード生成やサンドボックスでの検証から入るのが安全な順序です。

Stripe MCPサーバーの提供形態とエージェントから呼べるツール15種の範囲

Stripe MCPは2026年10月時点で公開プレビューの扱いです。まずサーバーの形と、エージェントに渡るツールの粒度を押さえます。

リモートのmcp.stripe.comが提供するAPI操作とドキュメント検索の中身

Stripe公式のMCPドキュメントによると、サーバーはStripe APIの操作と、ドキュメントやサポート記事を含むナレッジベースの検索をツールとして提供します。トランスポートはStreamable HTTPで、利用者がサーバーを立てる必要はありません。

MCPそのものの仕組みはMCP（Model Context Protocol）の解説記事にまとめています。Stripe MCPは「APIを呼ぶ役」と「実装方法を調べる役」を1つのサーバーで兼ねる点が、一般的な業務SaaSのMCPと違います。

stripe_api_readとstripe_api_writeの2ツールでのAPI操作

以前の解説記事に出てくるcreate_refundのようなリソース別のツールは、現行の一覧にはありません。API操作は汎用の4ツールに集約されています。

ツール 役割
stripe_api_search キーワードでAPIメソッドを探す
stripe_api_details メソッドのパラメーターを取得
stripe_api_read GETで読み取る
stripe_api_write POST・PATCH・PUT・DELETEで書込

このほかアカウント情報、分析、Treasuryの送金系、ドキュメント検索、実装プランナーなどがあり、合計は15種です。読み書きできるAPIは公式の一覧に載ったものに限られ、2026年10月19日時点で数えると約150メソッドでした。返金の作成やサブスクのキャンセルは含まれますが、PaymentIntentは一覧と取得だけで、決済そのものを作ることはできません。

Claude Code・Cursor・CodexからStripe MCPへの接続設定

接続の手段は、Stripe CLIによる自動設定と、クライアントごとの手動設定の2通りです。

stripe agent setupでMCPとエージェントスキルを一括で入れる手順

Stripe向けエージェントプラグインのページでは、次の2行を推奨手順としています。CLIが使っているエージェントを検出し、MCPサーバーの登録とスキルの導入をまとめて行います。

npm install -g @stripe/cli@latest
stripe agent setup

自動対応はClaude Code・Codex・Cursor・Grok・Kiro・OpenClawの6つです。npmで配布されている@stripe/cliの最新は2026年10月16日公開の1.54.0でした。プラグインは更新も自動で受け取るため、チームで設定を揃えたい場合はこちらを選びます。

Claude Codeの.mcp.jsonでキーを環境変数から渡す設定例

OAuthで使う場合、Claude Codeでは次のコマンドで登録し、起動後に/mcpを実行するとブラウザで認可画面が開きます。

claude mcp add --transport http stripe https://mcp.stripe.com/

無人の処理でエージェントAPIキーを使うなら、キーをコマンドに直接書かず、プロジェクトの.mcp.jsonから環境変数を参照させます。STRIPE_AGENT_KEYは任意の変数名です。

{
  "mcpServers": {
    "stripe": {
      "type": "http",
      "url": "https://mcp.stripe.com",
      "headers": {
        "Authorization": "Bearer ${STRIPE_AGENT_KEY}"
      }
    }
  }
}

このファイルはリポジトリにコミットしても、キーの値そのものは含まれません。シェル側で変数を設定してからClaude Codeを起動します。

Cursor・VS Code・Codexで設定ファイルの置き場所と書式が違う点

接続先は共通でも、設定ファイルの場所とキー名はクライアントごとに異なる仕様です。CursorはホームのJSONにmcpServers、VS Codeはワークスペースの.vscode/mcp.jsonにserversと書きます。Codexはcodex mcp add stripe --url https://mcp.stripe.comで登録でき、キーを使う場合はTOMLで変数名を指定します。

[mcp_servers.stripe]
url = "https://mcp.stripe.com"
bearer_token_env_var = "STRIPE_AGENT_KEY"

Codexの設定はChatGPTデスクトップアプリとIDE拡張でも共有されるため、1回の認証で3つの画面から使えます。社内ネットワークで接続できないときは、管理部門にmcp.stripe.comへの通信許可を依頼してください。

OAuthとエージェントAPIキーの使い分けと2026年11月30日のキー移行

認証方式の選び方を誤ると、12月に業務エージェントが止まります。ここが本稿で最も手当てが必要な箇所です。

対話型はOAuth、無人で動く業務エージェントはエージェントAPIキー

OAuthで操作できる範囲は、接続したStripeユーザーの権限に基づくものです。同意画面で本番環境とサンドボックスを選び、環境ごとに権限を変えられます。認可の流れはMCPの2026-07-28版の認可仕様に沿っており、クライアント登録の方式はCIMDの解説記事で扱っています。

夜間バッチや問い合わせ対応ボットのように、人の操作から独立して動く処理にはOAuthが合いません。この場合に使うのがStripeのAPIキーのページで説明されている自律エージェント用のキーです。制限付きキーを作る際に「アカウントへのエージェントアクセスの許可」を選ぶと、ダッシュボードでAgentのバッジが付きます。

12月から全権限キーとタグの無い制限付きキーが401になる影響範囲

公式MCPドキュメントには、2026年11月30日までに移行するよう告知があります。12月以降、sk_で始まる全権限のシークレットキーと、Agentタグの無いrk_の制限付きキーは受け付けられず、OAuthへの誘導を含む401が返ります。

影響を受けるのは、キーをAuthorizationヘッダーに入れて接続している設定すべてです。OAuthで接続している個人の開発環境は対象外。差し替えは、サンドボックスで新しいエージェントキーを試してから本番キーを作り、古いキーを失効させる順で行います。

npx版@stripe/mcpとAgent Toolkitも同じサーバーへ中継する仕組み

「ローカルで動かしているから関係ない」とは言えません。npmレジストリから取得した@stripe/mcp 0.3.3（2026年3月24日公開）の実体は、標準入出力で受けた要求をmcp.stripe.comへ転送する中継プログラムで、渡したキーはAuthorizationヘッダーに入ります。受け付ける引数は--api-keyと--stripe-accountの2つだけで、古い記事にある--toolsは「削除済み」の警告が出て無視されます。

LangChainやVercel AI SDKからStripeを呼ぶ@stripe/agent-toolkitも、最新の0.9.0（2026年2月12日公開）は内部でmcp.stripe.comに接続する作りでした。どちらもキーの移行対象になるとみて、11月中にエージェントキーへ替えておくのが安全です。GitHubのstripe/aiリポジトリのREADMEは、現在はリモートMCPとプラグインを中心に案内しています。

返金や解約をエージェントに任せる前に決める権限と承認ルールの設計

エージェントキーの安全性は、キーに開ける権限と、承認ルールの2段で決まります。

制限付きキーのRead・Write・Noneをリクエストログから決める手順

制限付きAPIキーのガイドでは、権限はリソースごとにNone・Read・Writeから選び、既定はすべてNoneです。GETは読み取り、POSTとDELETEは書き込みに当たり、WriteにはReadが含まれます。

  1. サンドボックスで権限なしのエージェントキーを作る
  2. 想定する指示をエージェントに一通り実行させる
  3. キーのリクエストログで403になったリソースだけ権限を足す
  4. 同じ権限で本番のキーを作り直す

問い合わせ対応ボットなら、顧客・請求書・支払いのReadから始めます。キーは用途ごとに分け、経理用と問い合わせ用で同じキーを共有しません。

返金とサブスク解約に既定で掛かる二者承認とapproval_required

二者承認のガイドによると、エージェントタグ付きキーには、返金の作成とサブスクリプションのキャンセルに既定の承認ルールが掛かります。該当する操作を試みるとapproval_requiredのエラーが返り、承認リクエストが自動で作られます。

承認されると操作は自動で完了し、14日以内に処理されなければ期限切れです。金額の条件を足して「1万円を超える返金だけ承認」のように絞れます。担当者が1人だけのアカウントでも、エージェントキーを対象にしたルールなら保存できます。サブスクの設計はStripe Billingの実装手順を参照してください。

連結アカウントをStripe-Accountヘッダーで操作するConnectの設定

マーケットプレイス型のStripe Connectで出店者側のデータを調べる場合、OAuthは使えません。プラットフォームのエージェントキーに連結アカウント向けの権限だけを付け、ヘッダーで対象を指定します。

{
  "mcpServers": {
    "stripe": {
      "url": "https://mcp.stripe.com",
      "headers": {
        "Authorization": "Bearer ${STRIPE_AGENT_KEY}",
        "Stripe-Account": "acct_xxxxxxxxx"
      }
    }
  }
}

この値は設定ファイルに固定されるため、出店者ごとに切り替えるボットは、接続をアカウント単位で分ける設計が必要です。

Stripe MCPを本番の業務に入れてよい条件と導入を見送る場面

導入の可否は、書き込み先が本番かどうかと、同居するMCPサーバーの顔ぶれで決めます。

開発支援とサンドボックス検証から本番の読み取りへ進める条件と順番

最初に入れてよいのは、実装中のコード生成と仕様の調べものです。stripe_api_searchとドキュメント検索は本番データに触れず、古いAPIを使ったコードを減らせます。続いてサンドボックスで商品・価格・テスト用の顧客を作らせ、本番は読み取りの調査に限って開放します。

ダッシュボードのワークベンチには、MCPのツール呼び出しが引数と応答ごとに残ります。本番の書き込みを開ける前に、ここで1〜2週間分の呼び出しを見て、意図しない操作が無いことを確かめてください。

Webや受信メールを読むMCPと同居させる構成で書き込みを許さない理由

公式ドキュメントは、他のMCPサーバーと併用する際のプロンプトインジェクションに注意を促しています。ブラウザ操作や受信メールを読むサーバーと同じエージェントにWrite権限を渡すと、外部の文章に紛れた指示で返金や価格変更が走る経路ができます。

この構成では書き込みを許可しません。読み取り専用のキーに限るか、Stripe MCPだけを載せた別のエージェントに分けます。OAuth接続で返金や送金を指示した場合も、Stripeが発行する確認URLで人が内容を承認するまで実行されず、24時間で失効します。

自社の業務エージェントにStripe操作を組み込む設計を外部に任せる目安

開発者が手元で使う範囲なら、本稿の設定で十分に回ります。外部の支援を検討すべきなのは、問い合わせ対応や経理処理のエージェントが本番の返金・請求書発行まで担い、キーの分割、承認ルール、他システムとの権限分離を同時に設計する段階です。

エージェントが支払う側に回る構成は、MPPの解説記事で扱う別の領域です。Stripe操作を含む業務エージェントの要件整理から実装までを依頼する場合は、AIエージェント開発のページで対応範囲を確認できます。

Stripe MCPのよくある質問｜サンドボックス・ローカル版・返金・履歴

Stripe MCPの導入時によく出る質問に、2026年10月時点の公式情報で答えます。

Stripe MCPはサンドボックスだけに限定して使えますか？

使えます。OAuthの同意画面で接続先の環境を選べるため、サンドボックスだけを許可すれば本番データには届きません。管理者はダッシュボードの設定で、チーム全体のMCPアクセスを本番環境とサンドボックスで別々に有効・無効にできます。エージェントキーを使う場合も、サンドボックスで作ったキーは本番のデータを読めません。検証期間中は本番側のMCPアクセスを無効にしておくと、設定の取り違えによる事故を防げます。

npxで起動する@stripe/mcpの–toolsが効かないのはなぜですか？

現行の0.3.3では--toolsの引数が削除されているためです。指定すると「削除済み」の警告が出て、引数は無視されます。使えるツールの範囲は、渡した制限付きキーの権限で決まる仕組みに変わりました。ツールを絞りたい場合は、キーの権限をNoneから必要なリソースだけ開けてください。なお、このローカル版も内部ではmcp.stripe.comへ中継しているため、2026年12月以降はエージェントキーが必要です。

Stripe MCPからエージェントに返金を実行させられますか？

返金の実行は可能ですが、承認の仕組みによる二重の歯止めがある設計です。OAuthで接続している場合は、エージェントが示す確認URLで人が内容を承認してから再実行させる流れで、24時間以内に承認しなければ失効します。エージェントキーの場合は、返金の作成に既定の承認ルールが掛かり、approval_requiredが返ります。どちらも、エージェントの判断だけで返金が完了しない作りです。

Stripe Agent ToolkitとStripe MCPはどう使い分けますか？

Claude CodeやCursorなど既製のクライアントから使うならStripe MCPに直接つなぎます。自社アプリの中でLangChainやVercel AI SDKを使い、関数呼び出しのツールとしてStripeを渡したい場合がAgent Toolkitの出番です。ただし0.9.0は内部でmcp.stripe.comに接続するため、認証の要件はMCPと同じと考えてください。新規の構築では、まずリモートMCPとプラグインで足りるかを確かめます。

エージェントがStripe MCPで実行した操作の履歴はどこで見られますか？

ダッシュボードのワークベンチで、ログタブの「MCPツールコール」を開きます。呼び出しごとのステータス・引数・応答が見られ、日付・ステータス・ツール・MCPクライアントによる絞り込みも可能です。承認ルールに掛かった操作は、設定のセキュリティ履歴にも承認リクエストの作成と結果が残ります。OAuthで接続したクライアントはユーザー設定のOAuthセッション一覧に並び、そこからアクセスを取り消せます。

関連記事

お気に入りに入れた記事の一覧

この記事は以下の記事からリンクされています

この記事に関連するサービス

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.10.15　テックブログ リゾートトラスト不正アクセス：会員2.6万件・カハラ横浜3.6万件の対象確認と窓口
  2. 2025.09.03　コラム ストループ効果とは？原典1935年の実測値と年齢別の平均・テストのやり方
  3. 2026.10.16　テックブログ バーガーキング不正アクセスで約1,118万件の情報漏洩｜対象確認・案内メールの真偽と運営側のログ点検
  4. 2026.01.20　テックブログ PineDramaとは？TikTokのショートドラマアプリの日本配信・料金・安全性を解説
  5. 2025.09.03　コラム Google AIモードの履歴の消し方と残る理由｜いつまで残るか・使い方・オフにする方法【2026年10月】

RELATED POSTS 関連記事

一覧へ戻る

目次