MCPサービスアカウント

AIエージェント、ボット、CIジョブ、またはバックエンドサービスが、ブラウザにユーザーを介さずにOAuthログインを完了し、Amplitude MCPを呼び出す必要がある場合は、MCPサービスアカウントを使用してください。サービスアカウントは、独自のクライアントIDとクライアントシークレットを持つ、組織所有のIDです。サービスは、これらの認証情報をOAuth 2.0クライアント認証情報フローを使用して短命なアクセストークンと交換し、そのトークンをMCPサーバーに送信します。

**可用性:**MCPサービスアカウントは、MCPアクセス権が有効になっているエンタープライズプランをご利用の組織が利用できます。

ユーザーOAuthの代わりにサービスアカウントを使用するタイミング

前提条件

  • 組織の管理者が設定を完了させている必要があります。Org管理者は、デフォルトでサービスアカウントを管理できます。
  • お客様の組織はエンタープライズプランをご利用いただいており、MCPアクセスが有効になっています。
  • 「設定」にサービスアカウントが見当たらない場合は、Amplitudeチームに連絡し、組織で有効になっているかをご確認ください。
  • お使いのMCPクライアントまたはサービスは、Streamable HTTP経由のリモートMCPをサポートしており、カスタムAuthorizationヘッダーを設定できます。
  • サービスは、新しいアクセストークンをリクエストし、現在のトークンが期限切れになる前にクライアントの認証ヘッダーを更新できます。

サービスアカウントを作成する

  1. Amplitudeで、設定 > 権限 > サービスアカウントに移動します。
  2. 「サービスアカウントを作成」をクリックします。
  3. わかりやすい名前を入力します(例:support-bot-prod)。
  4. このアカウントには読み取りアクセス権が含まれており、ALL_READと表示されます。「設定」を通じて作成された顧客アカウントは、現在読み取り専用です。
  5. 組織で権限グループを使用している場合は、サービスが必要とするプロジェクトへのアクセス権を付与するグループを選択します。 また、後からメンバーおよびグループでグループを割り当てることもできます。
  6. 作成をクリックし、クライアントIDとクライアントシークレットをコピーします。

両方の認証情報を今すぐ保存してください

Amplitudeはクライアントシークレットを一度しか表示しません。パネルを閉じる前に、この情報をシークレットマネージャーに保存してください。この認証情報を失くした場合は、ローテーションを使用して交換用の認証情報を生成します。

設定からサービスアカウントを作成するために、パーソナルアクセストークン(PAT)は必要ありません。

ロールと権限の割り当て

新しいサービスアカウントは、メンバーとして作成されます。これらは、作成管理者の権限を継承しません。彼らのプロジェクトとデータへのアクセス権は、組織の役割と権限グループによって異なります。

  1. 設定 > 権限 > メンバーとグループ(または、組織がグループを使用していない場合はメンバー)を開きます。
  2. **SA: <name>**という名前のアカウントを検索しま(例:SA: support-bot-prod)。
  3. メンバーに対して行うように、このサービスに必要なデータアクセス権を付与する権限グループまたはプロジェクトの役割を割り当てます。 カスタムロールが必要な場合は、ロール管理で定義し、そのロールをアカウントまたはそのグループに割り当てます。
  4. 接続後、引数なしでget_amplitude_contextを呼び出し、返されたプロジェクトリストを確認します。

OAuthのスコープは、アカウントで使用できるツールの種類を制限します。プロジェクトの役割と権限は、これらのツールがアクセスできるプロジェクトデータを制御します。 自動サービスと認証情報を共有する前に、両方を確認してください。

アクセストークンを取得する

地域のトークンエンドポイントでクライアントIDとシークレットを交換します。 プレースホルダを、設定からの認証情報に置き換えます。

shell
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設定を受け入れるクライアントに対するものです。 正確な形式については、クライアントのドキュメントを確認してください。

json
{
  "mcpServers": {
    "amplitude": {
      "url": "https://mcp.amplitude.com/mcp",
      "headers": {
        "Authorization": "Bearer ACCESS_TOKEN"
      }
    }
  }
}

ACCESS_TOKENをレスポンスからのトークンに置き換えます。期限が切れる前に、クライアント認証情報の交換を繰り返し、MCPクライアントが送信するヘッダーを更新してください。 静的設定は、トークンを自動的に更新しません。 新しいトークンを適用するために必要に応じて、クライアントをリロードまたは再接続してください。

接続を検証するには、引数なしでget_amplitude_contextを呼び出します({})。組織と、そのサービスアカウントがアクセスできるプロジェクトが返されます。

地域

組織のデータ領域と一致するエンドポイントを、トークンリクエストとMCP呼び出しの両方に使用してください。

スコープ

設定を通じて作成されたサービスアカウントには、読み取りアクセス権があります。

新しいサービスアカウントはall:readを使用します。古いアカウントでは、ローテーションの場合も含め、mcp:readは保持されます。どちらのスコープも、プロジェクトの権限に従って、同じ読み取りツールへのアクセスを許可します。トークンをリクエストする際は、アカウントに記載されているスコープを使用してください。既存のサービスアカウントは、設定で再作成する必要はありません。

認証情報をローテーションまたは取り消す

  • ローテーション:****サービスアカウントで、アカウントの行にあるローテーションをクリックし、確認します。ローテーションでは、新しいクライアントIDとクライアントシークレットを使用して代替アカウントを作成し、古いアカウントを無効にします。両方の新しい値を保存し、すべてのクライアントを更新し、新しいアクセストークンをリクエストします。 古い認証情報やトークンには、猶予期間はありません。 切り替え後にプロジェクトへのアクセス権を確認します。
  • 無効化:アカウントの行にある無効化をクリックし、確認します。これにより、アカウントは永久に無効になります。そのトークンを使用したその後のMCPリクエストは拒否されます。 このアカウントは、取り消し済みのステータスでリストに表示されたまま残ります。
  • 各組織は最大10個のアクティブなサービスアカウントを持つことができます。未使用のアカウントを無効にして、スロットを解放します。

計画された切り替えの場合は、別のアカウントを作成し、その権限を割り当てて検証し、サービスを更新してから、古いアカウントを無効にします。これには、利用可能なアカウントスロットが必要です。

セキュリティのベストプラクティス

  • サービスが必要とするプロジェクトとデータにのみアクセス権を付与します。
  • エージェントまたは環境ごとに1つのサービスアカウントを作成することで、他のアカウントを中断することなく、1つのサービスアカウントを無効にできます。
  • クライアントのシークレットとアクセストークンは、シークレットマネージャーに保存します。決して、これらをコミットしたり、プロンプトに貼り付けたりしないでください。
  • 定期的に、またアクセス権限を持つユーザーが離脱した場合に、認証情報をローテーションします。ローテーションする前にクライアントの更新をプランしてください。
  • サービスアカウントを定期的に確認し、未使用のアカウントを無効にします。

トラブルシューティング

トークンリクエストについては、レスポンスのerrorおよびerror_descriptionを参照してください。エラーコードだけでは、正確な原因を特定できません。

これは役に立ちましたか?

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.

このページでは