MCPサービスアカウント
AIエージェント、ボット、CIジョブ、またはバックエンドサービスが、ブラウザにユーザーを介さずにOAuthログインを完了し、Amplitude MCPを呼び出す必要がある場合は、MCPサービスアカウントを使用してください。サービスアカウントは、独自のクライアントIDとクライアントシークレットを持つ、組織所有のIDです。サービスは、これらの認証情報をOAuth 2.0クライアント認証情報フローを使用して短命なアクセストークンと交換し、そのトークンをMCPサーバーに送信します。
**可用性:**MCPサービスアカウントは、MCPアクセス権が有効になっているエンタープライズプランをご利用の組織が利用できます。
ユーザーOAuthの代わりにサービスアカウントを使用するタイミング
| 状況 | 用途 | なぜですか? |
|---|---|---|
| ある人がClaude、Cursor、ChatGPT、または別のAIクライアントを使用しています。 | ユーザーOAuth | エージェントは、その人の権限の下、その人のように動作します。 |
| 共有ボット、バックエンドエージェント、MCPゲートウェイ、またはスケジュール済みジョブ | MCPサービスアカウント | インタラクティブなログインはありません。この値の範囲の設定、ローテーション、無効化設定は個別に実行でき、特定のユーザーのアカウントにも依存しません。 |
| イベントデータの送信 | SDKまたはHTTP V2 API | MCPはイベントを取り込みません。 |
前提条件
- 組織の管理者が設定を完了させている必要があります。Org管理者は、デフォルトでサービスアカウントを管理できます。
- お客様の組織はエンタープライズプランをご利用いただいており、MCPアクセスが有効になっています。
- 「設定」にサービスアカウントが見当たらない場合は、Amplitudeチームに連絡し、組織で有効になっているかをご確認ください。
- お使いのMCPクライアントまたはサービスは、Streamable HTTP経由のリモートMCPをサポートしており、カスタム
Authorizationヘッダーを設定できます。 - サービスは、新しいアクセストークンをリクエストし、現在のトークンが期限切れになる前にクライアントの認証ヘッダーを更新できます。
サービスアカウントを作成する
- Amplitudeで、設定 > 権限 > サービスアカウントに移動します。
- 「サービスアカウントを作成」をクリックします。
- わかりやすい名前を入力します(例:
support-bot-prod)。 - このアカウントには読み取りアクセス権が含まれており、
ALL_READと表示されます。「設定」を通じて作成された顧客アカウントは、現在読み取り専用です。 - 組織で権限グループを使用している場合は、サービスが必要とするプロジェクトへのアクセス権を付与するグループを選択します。 また、後からメンバーおよびグループでグループを割り当てることもできます。
- 作成をクリックし、クライアントIDとクライアントシークレットをコピーします。
両方の認証情報を今すぐ保存してください
Amplitudeはクライアントシークレットを一度しか表示しません。パネルを閉じる前に、この情報をシークレットマネージャーに保存してください。この認証情報を失くした場合は、ローテーションを使用して交換用の認証情報を生成します。
設定からサービスアカウントを作成するために、パーソナルアクセストークン(PAT)は必要ありません。
ロールと権限の割り当て
新しいサービスアカウントは、メンバーとして作成されます。これらは、作成管理者の権限を継承しません。彼らのプロジェクトとデータへのアクセス権は、組織の役割と権限グループによって異なります。
- 設定 > 権限 > メンバーとグループ(または、組織がグループを使用していない場合はメンバー)を開きます。
- **SA: <name>**という名前のアカウントを検索しま(例:SA: support-bot-prod)。
- メンバーに対して行うように、このサービスに必要なデータアクセス権を付与する権限グループまたはプロジェクトの役割を割り当てます。 カスタムロールが必要な場合は、ロール管理で定義し、そのロールをアカウントまたはそのグループに割り当てます。
- 接続後、引数なしで
get_amplitude_contextを呼び出し、返されたプロジェクトリストを確認します。
OAuthのスコープは、アカウントで使用できるツールの種類を制限します。プロジェクトの役割と権限は、これらのツールがアクセスできるプロジェクトデータを制御します。 自動サービスと認証情報を共有する前に、両方を確認してください。
アクセストークンを取得する
地域のトークンエンドポイントでクライアントIDとシークレットを交換します。 プレースホルダを、設定からの認証情報に置き換えます。
curl -X POST https://mcp.amplitude.com/token \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=CLIENT_ID" \
--data-urlencode "client_secret=CLIENT_SECRET" \
--data-urlencode "scope=all:read"
レスポンスからaccess_tokenおよびexpires_inを読み取ります。expires_inは、トークンの有効期間(秒単位)です。期限が切れる前に、ネットワーク遅延のわずかな余裕を持たせて、同じクライアント認証情報で新しいトークンをリクエストしてください。
**アカウントのスコープと一致させます。**設定ラベルALL_READは、トークンリクエスト内のall:readに対応します。MCP_READをリスト表示する古いアカウントの場合は、scope=mcp:readをリクエストします。常に、そのアカウントに許可されている明示的な範囲を送信してください。
エージェントまたはMCPクライアントに接続します。
すべてのMCPリクエストで、クライアントシークレットではなく、access_tokenをベアラートークンとして送信します。次の例は、カスタムヘッダーを使用してmcpServers設定を受け入れるクライアントに対するものです。 正確な形式については、クライアントのドキュメントを確認してください。
{
"mcpServers": {
"amplitude": {
"url": "https://mcp.amplitude.com/mcp",
"headers": {
"Authorization": "Bearer ACCESS_TOKEN"
}
}
}
}
ACCESS_TOKENをレスポンスからのトークンに置き換えます。期限が切れる前に、クライアント認証情報の交換を繰り返し、MCPクライアントが送信するヘッダーを更新してください。 静的設定は、トークンを自動的に更新しません。 新しいトークンを適用するために必要に応じて、クライアントをリロードまたは再接続してください。
接続を検証するには、引数なしでget_amplitude_contextを呼び出します({})。組織と、そのサービスアカウントがアクセスできるプロジェクトが返されます。
地域
| 地域 | MCPサーバのURL | トークンエンドポイント |
|---|---|---|
| 米国(デフォルト) | https://mcp.amplitude.com/mcp | https://mcp.amplitude.com/token |
| EUレジデンシー: | https://mcp.eu.amplitude.com/mcp | https://mcp.eu.amplitude.com/token |
組織のデータ領域と一致するエンドポイントを、トークンリクエストとMCP呼び出しの両方に使用してください。
スコープ
| 設定ラベル | OAuthスコープ | 許可する |
|---|---|---|
ALL_READ | all:read | アカウントのプロジェクト権限に従って、ツールを読み取り、クエリを実行します。 |
設定を通じて作成されたサービスアカウントには、読み取りアクセス権があります。
新しいサービスアカウントはall:readを使用します。古いアカウントでは、ローテーションの場合も含め、mcp:readは保持されます。どちらのスコープも、プロジェクトの権限に従って、同じ読み取りツールへのアクセスを許可します。トークンをリクエストする際は、アカウントに記載されているスコープを使用してください。既存のサービスアカウントは、設定で再作成する必要はありません。
認証情報をローテーションまたは取り消す
- ローテーション:****サービスアカウントで、アカウントの行にあるローテーションをクリックし、確認します。ローテーションでは、新しいクライアントIDとクライアントシークレットを使用して代替アカウントを作成し、古いアカウントを無効にします。両方の新しい値を保存し、すべてのクライアントを更新し、新しいアクセストークンをリクエストします。 古い認証情報やトークンには、猶予期間はありません。 切り替え後にプロジェクトへのアクセス権を確認します。
- 無効化:アカウントの行にある無効化をクリックし、確認します。これにより、アカウントは永久に無効になります。そのトークンを使用したその後のMCPリクエストは拒否されます。 このアカウントは、取り消し済みのステータスでリストに表示されたまま残ります。
- 各組織は最大10個のアクティブなサービスアカウントを持つことができます。未使用のアカウントを無効にして、スロットを解放します。
計画された切り替えの場合は、別のアカウントを作成し、その権限を割り当てて検証し、サービスを更新してから、古いアカウントを無効にします。これには、利用可能なアカウントスロットが必要です。
セキュリティのベストプラクティス
- サービスが必要とするプロジェクトとデータにのみアクセス権を付与します。
- エージェントまたは環境ごとに1つのサービスアカウントを作成することで、他のアカウントを中断することなく、1つのサービスアカウントを無効にできます。
- クライアントのシークレットとアクセストークンは、シークレットマネージャーに保存します。決して、これらをコミットしたり、プロンプトに貼り付けたりしないでください。
- 定期的に、またアクセス権限を持つユーザーが離脱した場合に、認証情報をローテーションします。ローテーションする前にクライアントの更新をプランしてください。
- サービスアカウントを定期的に確認し、未使用のアカウントを無効にします。
トラブルシューティング
トークンリクエストについては、レスポンスのerrorおよびerror_descriptionを参照してください。エラーコードだけでは、正確な原因を特定できません。
| 症状 | 確認する内容 | 修正 |
|---|---|---|
トークンをリクエストするとinvalid_clientが発生する | 不正な認証情報、間違った地域、またはアカウントがローテーションまたは無効化されました。 | 地域と両方の認証情報の値を確認してください。 トークンの例に示すように、これらをURLエンコードされたフォームフィールドとして送信します。 ローテーション後、新しいクライアントIDとシークレットを使用します。 |
トークンをリクエストするとinvalid_scopeが発生する | 範囲は、スペルミス、形式が正しくない、またはそのアカウントで許可されていない可能性があります。 | そのアカウントに記載されているスコープを使用します。 古いアカウントでは、all:readの代わりにmcp:readが必要な場合があります。 |
MCPを呼び出すとinvalid_tokenまたは401が発生する | トークンの有効期限が切れているか、地域が間違っているか、アカウントがローテーションまたは無効になっています | アクティブなアカウントの場合、正しいリージョンのエンドポイントから現在の認証情報を使用して新しいトークンをリクエストし、MCPヘッダーを更新します。 無効化されたアカウントは再利用できません。 |
| 接続されるが、プロジェクトがリストに表示されない | アカウントのプロジェクト権限とグループメンバーシップ | メンバーおよびグループまたはメンバーで**SA: <name>**を見つけ、そのグループとプロジェクトのロールを確認してから、get_amplitude_contextを再度呼び出してください。 |
| ツールがありません | トークンの範囲、接続オプション、およびこのツールがこのクライアントと組織で使用できるかどうか | アカウントに許可された明示的な範囲をリクエストし、クライアントヘッダーを更新します。 設定を通じて作成された顧客アカウントは、現在読み取り専用です。まだ期待される読み取りツールが見つからない場合は、クライアントのツールリストまたは検出設定を確認し、Amplitudeチームに連絡して、利用可能性を確認してください。 |
| サービスアカウントオプションが表示されない | プランの適格性、MCPアクセス、サービスアカウントの有効化、および管理権限 | 組織管理者に設定 > 権限を確認してもらってください。サービスアカウントでは、エンタープライズプランとMCPアクセス権の両方を有効にする必要があります。このオプションがまだ見つからない場合は、Amplitudeチームにお問い合わせください。 |
| Createがlimitエラーで失敗する | この組織にはすでに10個のアクティブなサービスアカウントがあります。 | 未使用のサービスアカウントを無効にします。 |
これは役に立ちましたか?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.