Amplitude MCP Analytics セットアップ
MCP サーバーをインストルメントして、すべてのツールコールを Amplitude イベントにし、製品の他の Amplitude データ（リテンション、収益、Web/モバイル使用状況）と結合可能にします。
権威ある SDK リファレンスはパッケージの README です:
https://github.com/amplitude/Amplitude-MCP-Analytics-Node (npm: @amplitude/mcp-analytics)。
この SDK はプレビュー版であり急速に進化しています — 常に最新の README を取得し、インストール、API の形状、設定、デフォルトイベントについてはそれに従ってください。 記憶にあるスニペットやこのスキルの要約に依存せず、SDK API の詳細については README が優先されます。
4 つのステップがあります。ステップ 1～2 は必須で README に記載されています — このスキルでは、どのセクションに従うべきか、どの不変条件を確認すべきかを指示します。ステップ 3～4 は強く推奨され、SDK の外部（サーバーのツールスキーマと製品の Web アプリ）での変更が必要なため、ここに完全に文書化されています（SDK README では意図的にカバーされていません）。
順番に実行してください：ステップ 1（ツールコール）→ ステップ 2（ID）→ ステップ 3（Rationale）→ ステップ 4（UTM、サーバーがリンクを返す場合のみ）。何かを「完了」と呼ぶ前に ID を正しく設定してください — 後続のすべてはそれに依存します。
始める前に
以下を確認してください：
- これは
@modelcontextprotocol/sdk上に構築された Node/TypeScript MCP サーバーであること。この SDK は他の言語/ランタイムをサポートしていません。 - ユーザーがイベントを送信したいプロジェクトの Amplitude API キー を（取得できる状態で）持っていること。
- リポジトリが使用するパッケージマネージャー（pnpm/npm/yarn）— それに応じてインストールコマンドを調整してください。
ステップ 1 — SDK をインストールしてツールコールを追跡する（必須）
README を取得し、その Install および Quick start セクションに従ってください。常に最新の公開バージョンをインストール（例：pnpm add @amplitude/mcp-analytics@latest）してください — 記憶からバージョンを固定せず、このスキルからインストールコマンドを複製しないでください。
配線後に確認する不変条件（README がそれぞれ説明しています）：
analytics.instrumentServer(server, ...)はserver.connect()の前に実行される — 順序が重要です。- すべての ツールハンドラが
analytics.instrumentTool(...)でラップされていること。ラップされていないツールは追跡されません。ラッパーはハンドラと同一の形状を持ち、サーバーがバインドされなかった場合は何もしないパススルーなので、防御的にラップしても安全です。 - デフォルトイベントはすべて
[MCP]プレフィックスを持つため、製品の既存の Amplitude イベントと衝突することはありません。現在のイベントセットとプロパティについては、README の デフォルトイベント テーブル（およびリポジトリ内のdocs/events.md）を参照してください。
オプション：instrumentTool/instrumentServer の extra を介して、安定したカスタムディメンション（プラン層、チーム、機能フラグ）をアタッチします — README の カスタムイベントプロパティ セクションを参照してください。
ステップ 2 — ID を正しく設定する（必須、ステップ 1 を「完了」と呼ぶ前にこれを行ってください）
MCP イベントは、製品が Web/モバイルから Amplitude に既に送信している 同じ user_id を保持する必要があります。これをスキップすると、MCP の使用状況はプロダクトデータと結合できない切り離された集団として表示されます — これにより統合のほとんど意味が失われます。
現在の API については README の Identity セクションに従ってください。サーバーレベルのバインディング、ハンドラ内でのリクエストごとの setIdentity()、リクエストの authInfo クレームからのオプトインの resolveIdentity マッピングを提供しています。サーバーの認証モデルに合ったものを選んでください。
ユーザーに伝えるべき動作の1つ：完全に匿名でアンカーのないイベントは、明示的に emitAnonymousEvent: true でオプトインされない限り、デフォルトでドロップされます（ユーザーとしてカウントされません）。これは集計のみの追跡の場合です — これをオンにする前にユーザーの同意を得てください。カウント対象が変わるためです。
ステップ 3 — Rationale をキャプチャする（推奨）
人間がボタンをクリックするのとは異なり、エージェントはなぜツールを呼び出したかを伝えることができます。これをキャプチャすることで、データを「何が起こったか」から「ユーザーが何をしようとしていたか」に変えることができます。
SDK 側は1回の呼び出し（analytics.setRationale(...) — README の Rationale セクションを参照）ですが、SDK はツール入力から自力で rational を読み取ることはありません：rationale がどのようにサーバーに到達するかは、このスキルが実装するサーバー側の規約です。 実戦で試されたパターンはスキーマインジェクション — すべてのツールの入力スキーマにオプションの rationale フィールドを追加します。パラメータがエージェントが既に読むスキーマ内に記述されているため、エージェントは促されることなく、すべてのクライアントで、クライアント側の変更ゼロでそれを記入します：
// すべてのツールの入力スキーマに追加（zod の例）：
rationale: z
.string()
.optional()
.describe(
'このツールを呼び出している理由と、その結果から何を学べるかを簡単に説明してください。',
),
次に、インストルメントされたハンドラ内でそれを読み取り、SDK に渡します：
analytics.instrumentTool(async (args, extra) => {
if (typeof args.rationale === 'string') {
analytics.setRationale(args.rationale);
}
return doWork(args);
}, { name: 'search' });
フィールドをオプションにすることで、エージェントが省略した場合でも何も壊れません。これは予約済みプロパティ [MCP] Rationale として出力されます（1,000 文字に切り詰められ、最後の書き込みが優先されます）。サンプルだけでなく、すべてのツールで行う価値があります。
ステップ 4 — 外部リンクに UTM タグを付ける（推奨、サーバーが URL を返す場合のみ）
このステップは完全に SDK の外部にあります — サーバーが URL を構築する方法を変更し、製品の Web 側アナリティクスに依存します。SDK README ではカバーされていません。
ツールの応答にリンク（ダッシュボード、ドキュメント、製品ページ）が含まれている場合、サーバーから出る前にタグを付けて、クリックスルーが MCP/エージェントトラフィックに帰属され、ダイレクトとして表示されないようにします：
function addUtmParams(url: string, clientName?: string): string {
const u = new URL(url);
u.searchParams.append('utm_source', 'mcp');
u.searchParams.append('utm_medium', 'referral');
// 接続されているクライアント（例：「Claude」、「Cursor」）、わかっている場合：
u.searchParams.append('utm_content', clientName ?? 'unknown');
return u.toString();
}
ツール応答内のすべての URL 構築パスをこのような1つの中央関数に通します — タグ付けされていないリンクが1つあるだけで、そのフローの帰属ストーリーが壊れます。
前提条件（これをユーザーに明示的に伝えてください）： これは、Web アナリティクスがページビューイベント（またはサイトがランディング時に発火するイベント）で UTM パラメータをキャプチャする場合にのみ機能します。Amplitude の Browser SDK 2 はデフォルトでこれを行います — Track marketing attribution を参照してください（UTM、リファラー、クリック ID パラメータは標準でキャプチャされます）。カスタムのページビュートラッカーを使用している場合、UTM 値がそれらのイベントにも届いていることを確認する必要があります。そうしないと、MCP タグ付きクリックを結合する対象がなくなります。
関連する Amplitude ドキュメント：
- Browser SDK 2 — Track marketing attribution（Web 側の UTM キャプチャ、このステップの実装の半分）
- Sessions, channels, and attribution for marketing analytics（タグ付けされたトラフィックがチャネル分析になる方法）
- Autocapture（ページビューなど）
インストルメント後
イベントが流れ始めたら、コーディングエージェントを Amplitude の公開 analyze-mcp-server スキルに向けて、意図クラスタリングを実行し、ツールコールのエラーパターンを意図別に表面化させてください。（このプロジェクトに mcp-intent-error-analysis スキルがインストールされている場合、それが該当します — ユーザーがデータを流して分析したい場合にそれを使用し、ここでその分析を複製しないでください。）
よくある間違いのフラグ
- 現在の README ではなく古い API スニペットに従う — 毎回取得し直してください。SDK はプレビュー版で急速に変化しています。
- 最新リリースではなく固定/古いバージョンをインストールする。
server.connect()の後でinstrumentServer()を呼び出す — 前である必要があります。- 一部のツールハンドラだけをラップし、他はラップしない — すべてのツールに
instrumentToolが必要です。 - Web/モバイルで使用されているものと一致しない
user_idを送信する — 結合可能性を壊し、統合の目的全体を損ないます。 - ユーザーの理解なしに
emitAnonymousEvent: trueをオンにすると、アンカーレストラフィックで集計カウントが水増しされます。 - UTM の前提条件（Web 側のキャプチャ）を忘れて、リンクにタグを付けるだけで十分だと考えること。