---
title: "Stripe MCPの使い方：接続手順とエージェントAPIキーの権限設計"
url: "https://www.issoh.co.jp/tech/details/18541/"
published: 2026-10-19
updated: 2026-10-19
categories: ["開発"]
publisher: "株式会社一創"
---

# 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ドキュメント](https://docs.stripe.com/mcp)によると、サーバーはStripe APIの操作と、ドキュメントやサポート記事を含むナレッジベースの検索をツールとして提供します。トランスポートはStreamable HTTPで、利用者がサーバーを立てる必要はありません。

MCPそのものの仕組みは[MCP（Model Context Protocol）の解説記事](https://www.issoh.co.jp/tech/details/5736/)にまとめています。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向けエージェントプラグインのページ](https://docs.stripe.com/agents/plugin)では、次の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版の認可仕様](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization)に沿っており、クライアント登録の方式は[CIMDの解説記事](https://www.issoh.co.jp/tech/details/10011/)で扱っています。

夜間バッチや問い合わせ対応ボットのように、人の操作から独立して動く処理にはOAuthが合いません。この場合に使うのが[StripeのAPIキーのページ](https://docs.stripe.com/keys)で説明されている自律エージェント用のキーです。制限付きキーを作る際に「アカウントへのエージェントアクセスの許可」を選ぶと、ダッシュボードで**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リポジトリ](https://github.com/stripe/ai)のREADMEは、現在はリモートMCPとプラグインを中心に案内しています。

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

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

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

[制限付きAPIキーのガイド](https://docs.stripe.com/keys/restricted-api-keys)では、権限はリソースごとに`None`・`Read`・`Write`から選び、既定はすべて`None`です。GETは読み取り、POSTとDELETEは書き込みに当たり、`Write`には`Read`が含まれます。

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

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

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

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

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

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

マーケットプレイス型の[Stripe Connect](https://www.issoh.co.jp/tech/details/18525/)で出店者側のデータを調べる場合、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を使ったコードを減らせます。続いてサンドボックスで商品・価格・テスト用の顧客を作らせ、本番は読み取りの調査に限って開放します。

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

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

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

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

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

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

エージェントが支払う側に回る構成は、[MPPの解説記事](https://www.issoh.co.jp/tech/details/11520/)で扱う別の領域です。Stripe操作を含む業務エージェントの要件整理から実装までを依頼する場合は、[AIエージェント開発](https://www.issoh.co.jp/service/ai/agent/)のページで対応範囲を確認できます。

## 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セッション一覧に並び、そこからアクセスを取り消せます。

## 関連記事

- [Stripeとは？決済プラットフォームの仕組み・手数料・実装パターンを開発視点で解説](https://www.issoh.co.jp/tech/details/15416/)：Stripe全体の構成と実装方式の選び方。
- [Stripe APIの使い方：PaymentIntentの作成・APIキー認証・冪等キーをNode.jsとcurlで実装](https://www.issoh.co.jp/tech/details/18527/)：MCPを通さずにAPIを直接呼ぶ場合のキーと実装。
- [MCPサーバーの作り方とAIエージェントへの接続手順｜Python SDK 2.3でツール定義・認可を実装](https://www.issoh.co.jp/tech/details/15365/)：自社データを同じ方式でエージェントに渡す場合。
- [AgentCore paymentsとは？x402・MPP対応の仕組みと料金・実装手順](https://www.issoh.co.jp/tech/details/12036/)：エージェントが支払う側に立つAWSの構成。
- [MCP（Model Context Protocol）とは？AIと外部ツールをつなぐ標準規格の仕組みをわかりやすく解説](https://www.issoh.co.jp/tech/details/5736/)：MCPの基本的な仕組み。

---

出典: [Stripe MCPの使い方：接続手順とエージェントAPIキーの権限設計](<https://www.issoh.co.jp/tech/details/18541/>)（株式会社一創）