> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MoEngage MCP Server とコネクター

> Claude や ChatGPT などの AI アシスタントを MoEngage ワークスペースに接続し、自然言語でキャンペーンの作成、セグメントとフローの管理、パフォーマンスの分析を行います。

MoEngage は、AI アシスタントがワークスペースを直接操作できるホスト型の [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) サーバーを提供しています。アシスタントは、自然言語での会話を通じて、**キャンペーンの下書きの作成、セグメントの作成とカウント、フローの読み取りと分析、ダッシュボードの閲覧、パフォーマンスの分析** をすべて行えます。

MoEngage MCP サーバーは、MCP 互換のあらゆるクライアント向けの **カスタムコネクター** として利用できます。また、Anthropic の Claude コネクターディレクトリにも掲載されているため、サーバー URL を自分で入力することなく、Claude (Web、モバイル、Claude API、Claude Code、Claude Desktop) から直接追加できます。ChatGPT マーケットプレイスへの掲載にも積極的に取り組んでいます。

<Note>
  MCP サーバーは、Claude や ChatGPT などの外部 AI アシスタントを MoEngage ワークスペースに接続します。MoEngage ダッシュボード内で AI エージェントを構築して実行するには、[Custom Agents](/docs/ja/user-guide/ai-and-intelligence/merlin-ai/custom-agents/custom-agents-overview) を参照してください。
</Note>

<Info>
  MoEngage AI Connector (MCP サーバー) は、**DC01、DC02、DC03、DC04** で利用できます。
</Info>

## MCP サーバーの URL

クライアントでリモート MCP サーバーまたはカスタムコネクターの入力を求められた場合は、次の URL を使用します。

```text theme={null}
https://mcp.moengage.com
```

<Info>
  MoEngage の **ドキュメント** 用 MCP (ドキュメントサイトの検索) には、`https://www.moengage.com/docs/mcp` を使用します。
</Info>

<Note>
  コネクターはローカルデバイスではなく AI プロバイダーのクラウド (例: Claude の場合は Anthropic のクラウド) から実行されるため、サーバーはパブリックインターネット経由で到達可能である必要があります。`https://mcp.moengage.com` はパブリックに到達可能なため、ファイアウォールや許可リストの変更は不要です。
</Note>

## セットアップ

コネクターを利用可能にする方法は 2 つあります。

* **組織全体のセットアップ** — 管理者が組織全体に対して MoEngage を一度追加するため、各メンバーは **Connect** をクリックするだけで済みます。チームにおすすめです。
* **個人のセットアップ** — 個人が自分のアカウントにコネクターを追加します。

いずれの場合も、各ユーザーは自分の MoEngage アカウントで個別に認証するため、アシスタントはそのユーザーがすでにアクセスできるデータとツールのみを参照します。

### 組織全体のセットアップ (管理者、1 回のみ)

一度セットアップすれば、組織内の誰もが URL を自分で貼り付けることなく接続できます。

<Tabs>
  <Tab title="Claude (Team / Enterprise)">
    <Info>
      組織コネクターを追加できるのは、Claude Team または Enterprise 組織の **Primary Owner** または **Owner** のみです。
    </Info>

    1. **Settings** → **Connectors** (組織の設定) に移動します。
    2. **Add** をクリックします。
    3. MCP サーバーの URL `https://mcp.moengage.com` を入力します。
    4. **Advanced settings** (OAuth Client ID と Client Secret) は空欄のままにします。MoEngage が OAuth を自動的に処理します。
    5. **Add** をクリックします。

    これで、コネクターがすべてのメンバーの **Connectors** リストに表示されます。各メンバーは **Connect** を一度クリックして、自分の MoEngage アカウントで認証します。
  </Tab>

  <Tab title="ChatGPT (Business / Enterprise)">
    <Info>
      ワークスペースのコネクターは **ワークスペース管理者** (Business、Enterprise、または Edu プラン) が管理します。
    </Info>

    1. **Settings** → **Connectors** (ワークスペース管理者の設定) を開きます。
    2. **カスタム** または **サードパーティの MCP コネクター** の追加を選択します。
    3. MCP サーバーの URL `https://mcp.moengage.com` を入力します。
    4. 保存します。コネクターがメンバーに利用可能になり、メンバーはそれぞれの MoEngage アカウントで個別に認証します。
  </Tab>
</Tabs>

### 個人のセットアップ (ユーザーごと)

自分のアカウントを接続する場合、またはコネクターが組織全体に追加されていない場合は、こちらを使用します。

<Tabs>
  <Tab title="Claude で接続する">
    1. **Claude Desktop** を開くか、[claude.ai](https://claude.ai/login) にアクセスします。
    2. サイドバーで **Settings** をクリックします。
    3. **Connectors** をクリックします。
    4. **Add custom connector** をクリックします。
    5. MCP サーバーの URL `https://mcp.moengage.com` を入力します。
    6. **Add** をクリックし、**Connect** をクリックします。MoEngage アカウントで認証するためにリダイレクトされます。
    7. 認証が完了すると、**Settings** の **Connectors** に MoEngage のツールが表示されます。
    8. ツールごとに **Tool permissions** (*Automatic*、*Ask first*、または *Disabled*) を設定します。[必要なツールを有効にする](#enable-the-tools-you-need)を参照してください。
  </Tab>

  <Tab title="ChatGPT で接続する">
    1. [ChatGPT](https://chatgpt.com/) を開きます。
    2. サイドバーで **Settings** をクリックします。
    3. **Connectors** (プランによっては **Connected apps**) を選択します。
    4. **Add** をクリックし、**Custom MCP Connector** を選択します。
    5. MCP サーバーの URL `https://mcp.moengage.com` を入力します。
    6. **Connect** をクリックし、MoEngage アカウントで認証します。
    7. 認証が完了すると、会話で MoEngage のツールを使用できるようになります。
  </Tab>

  <Tab title="GitHub Copilot (VS Code) で接続する">
    <Info>
      **VS Code 1.101 以降** (リモート MCP と OAuth のサポート) と Copilot の **エージェントモード** が必要です。
    </Info>

    1. VS Code でコマンドパレットを開き、**MCP: Add Server** を実行します (または `.vscode/mcp.json` を直接編集します)。
    2. **HTTP (remote server)** を選択し、URL `https://mcp.moengage.com` を入力します。
    3. 保存します。`mcp.json` のサーバーエントリーで **Auth** (CodeLens) をクリックすると、MoEngage アカウントで認証するためのブラウザーウィンドウが開きます。
    4. **Copilot Chat** を開き、**Agent** モードに切り替えると、ツールピッカーに MoEngage のツールが表示されます。

    <Note>
      その他の Copilot IDE (Visual Studio、JetBrains、Xcode、Eclipse) は現在、個人用アクセストークンでのみ MCP サーバーに接続でき、OAuth のサポートは順次展開中です。このサーバーは OAuth ベースであるため、**現時点でサポートされている Copilot クライアントは VS Code です。**
    </Note>
  </Tab>
</Tabs>

### 会話で使用する

接続後、チャットで MoEngage のツールをオンにします。

1. 新しい会話で、ツールまたはコネクターのメニューを開きます (Claude では **+** アイコン → **Connectors**)。
2. **MoEngage** をオンに切り替えます。
3. 目的を平易な言葉で依頼します ([プロンプトの例](#example-prompts)を参照)。

## 認証

MoEngage MCP サーバーは、MoEngage アカウントに紐付いた OAuth ベースの認証を使用します。MCP クライアントはワークスペースを切り替える頻度が高いため、ダッシュボードとは異なり、MCP 接続では最後に使用したワークスペースではなくワークスペースの一覧がデフォルトで表示されます。すでにサインインしている場合は、以下の最後のステップで説明する承認プロンプトに直接移動します。それ以外の場合の全体的なフローは次のとおりです。

<Steps>
  <Step title="接続を開始する">
    MCP クライアントで、新しい MoEngage 接続を開始します。MoEngage はグローバルログインページにリダイレクトします。
  </Step>

  <Step title="メールアドレスを入力する">
    **Work email** ボックスにメールアドレスを入力し、**Continue** をクリックします。MoEngage は、最後に使用したワークスペースのデータセンターのログインページにリダイレクトします。
  </Step>

  <Step title="本人確認を行う">
    **User authentication** ページで、認証アプリを開いて MoEngage の 6 桁のコードを確認し、確認ボックスに入力します。**Continue** をクリックします。
  </Step>

  <Step title="ワークスペースを選択する">
    **Login to a different workspace** ページで、接続するワークスペースと環境を選択します。環境のオプションは **Live** と **Test** です。
  </Step>

  <Step title="ワークスペースの認証を完了する">
    ワークスペースで設定されたログイン方法 (パスワード、Google、または SSO) を使用して認証を完了します。次に、承認プロンプトが表示されます。画面には次の情報が表示されます。

    * **Account** — MoEngage のメールアドレス
    * **Workspace** — 現在サインインしているワークスペース
    * **Role** — そのワークスペースでのロール (例: Manager、Admin)
    * **Data Center** — データセンターの環境

    **Accept** をクリックしてアクセスを許可します。

    <div style={{ maxWidth:"440px" }}>
      <Frame>
        <img src="https://mintcdn.com/moengage/e5VzzqYs1CiiuLiR/images/MCP-request-access.png?fit=max&auto=format&n=e5VzzqYs1CiiuLiR&q=85&s=570b3103686b0aea19e51b3648145fb6" alt="アカウント、ワークスペース、ロール、データセンターが表示された MoEngage MCP の OAuth 承認画面" width="1461" height="1337" data-path="images/MCP-request-access.png" />
      </Frame>
    </div>
  </Step>
</Steps>

### 認証に関する主な動作

* 接続では、現在のダッシュボードセッションではなく、承認時に選択した **環境**、**ワークスペース**、**ロール** が使用されます。
* 認証トークンは MCP の承認フローによって発行され、そのワークスペースと環境にスコープが限定されます。
* 別のワークスペースや環境を使用するには、MCP クライアントから接続を **再認証** し、そこで選択します。接続が中断された場合も、同じ方法で再開してください。
* すべてのアクションは、ロールで使用できるツールを含め、既存の MoEngage のロールベースの権限に従います。データの読み取りには読み取りアクセスが必要で、作成や編集には対応する作成/管理権限が必要です。
* **セッション期間**: 30 日間 (7 日間操作がない場合はタイムアウト)。
* **ダッシュボードから独立**: MCP セッションはダッシュボードセッションとは別です。一方でログインまたはログアウトしても他方には影響せず、ダッシュボードで別のワークスペースにサインインしても、MCP 接続が使用するワークスペースは切り替わりません。

## エージェント向けの設計

このサーバーは、特定のベンダーのものに限らず *あらゆる* AI アシスタントが最初の試行で正しく動作できるように設計されています。これを可能にしているのが次の 2 つの機能です。

* **`discover_schema`** は、作成対象に応じた正確な最新のリクエスト形式 (必須フィールド、許可される値、動作する例) を返すため、アシスタントが推測する必要がありません。
* **`get_content_guide`** は、コンテンツ作成 (Jinja によるパーソナライズ、メール HTML) のための検証済みのガイダンスをオンデマンドで提供するため、試行錯誤ではなく正確なコンテンツを作成できます。

<Note>
  MCP は **下書き** を作成して検証します。キャンペーンの公開とフローの開始 (公開) は、引き続き MoEngage ダッシュボードで人間が行う操作です。既存のフローの一時停止、再開、停止は `update_flow_status` で行えます。
</Note>

## できること

<CardGroup cols={2}>
  <Card title="キャンペーンの作成" icon="pen-to-square">
    A/B バリアント、複数ロケール、スケジュール、セグメンテーション、コンテンツブロックを含む、プッシュキャンペーンとメールキャンペーンの下書きを作成します。
  </Card>

  <Card title="コンテンツの作成" icon="wand-magic-sparkles">
    Jinja によるパーソナライズとメール HTML の検証済みパターンを取得し、サンプルユーザーでのコンテンツの表示をプレビューします。
  </Card>

  <Card title="セグメントの管理" icon="users">
    カスタムセグメントの作成、既存セグメントの閲覧、チャネル到達可能性を含むリアルタイムのユーザー数の取得を行います。
  </Card>

  <Card title="フローの操作" icon="diagram-project">
    フローの検索、設定とバージョンの読み取り、フローとチャネルごとのパフォーマンスの分析、一時停止または再開を行います。
  </Card>

  <Card title="検索とレビュー" icon="magnifying-glass">
    サポートされているチャネル全体でキャンペーンを検索し、キャンペーンの完全な設定とコンテンツを読み取ります。
  </Card>

  <Card title="パフォーマンスの分析" icon="chart-line">
    キャンペーンのパフォーマンス、配信ファネル、クリックの内訳、デバイス分析、ダッシュボードのチャートを取得します。
  </Card>

  <Card title="プロダクトデータの分析" icon="chart-mixed">
    行動、ファネル、リテンション、ユーザー、セッションとソースの分析を実行し、使用するイベントと属性を見つけます。
  </Card>
</CardGroup>

## 利用可能なツール

作成、編集、テスト送信は **Push と Email** でサポートされています。SMS、Webhook、WhatsApp を含むその他すべてのチャネルのキャンペーンは読み取り専用です。検索と読み取りはできますが、作成や編集はできません。`search_campaigns` の `channel` フィルターはさらに対象が限定されています。[その他の制限事項](#other-limitations)を参照してください。

使用できるツールは MoEngage のロールによって異なります。想定しているツールが見つからない場合は、[ツールリストを更新](#refresh-the-tools-list)してください。

### キャンペーンを作成する

| ツール | 説明 |
| - | - |
| `discover_schema` | キャンペーンタイプ、コンポーネント、テンプレート、または修飾子の正確なリクエスト形式 (必須/禁止フィールド、実証済みの最小限の例、そのタイプのルール) を返します。**ペイロードを作成する前に必ず呼び出してください。** |
| `create_campaign_draft` | 1 回の呼び出しでキャンペーンの下書きを作成します。 |
| `patch_campaign_components` | 既存の下書きの 1 つ以上のコンポーネントを更新します。 |
| `validate_campaign_draft` | 下書きを変更せずに、公開時の完全な検証をドライランで実行します。不足しているものがある場合は、フィールドレベルのエラーを返します。 |
| `create_personalization_preview` | 作成前にコンテンツをスポットチェックするため、サンプルユーザーでパーソナライズをレンダリングします。 |
| `test_campaign_inline` / `test_campaign_by_draft_id` | 下書きを検証するためにテストメッセージを送信します。 |
| `update_campaign_status` | すでに実行中のキャンペーン (下書きを除く) を STOP、PAUSE、または RESUME します。 |

### コンテンツを作成する

| ツール | 説明 |
| - | - |
| `get_content_guide` | コンテンツ作成のための検証済みのガイダンスで、Jinja によるパーソナライズとメール HTML を適切に記述する方法を示します。`topic` (`jinja`、`email_html`、`email_deliverability`) と、必要な部分のみを取得するためのオプションの `section` を指定します。これはコンテンツ作成の *品質* に関するガイダンスであり、リクエストの *形式* を示す `discover_schema` とは異なります。 |

### コンテンツブロック

| ツール | 説明 |
| - | - |
| `create_content_block` / `edit_content_block` | 再利用可能なコンテンツブロック (例: 共通のメールフッター) を作成または更新します。 |
| `search_content_blocks` / `get_content_blocks_by_ids` | ラベルでコンテンツブロックを検索するか、ID で取得します。 |

### セグメント

| ツール | 説明 |
| - | - |
| `create_custom_segment` | `included_filters` / `excluded_filters` からフィルターベース (ELASTIC\_SEARCH) のカスタムセグメントを作成します。セグメントの `name` は一意で、200 文字以内、HTML を含まない必要があります (`All Users` は予約済みです)。フィルター内の名前は作成時に部分的にしか検証されません。カタログに到達可能な場合、ユーザー属性の表示名や大文字/小文字が誤った内部名は事前に拒否されますが、イベント名とイベント属性名はまったくチェックされません。誤った名前も受け入れられ、後でセグメントのカウントがエラー理由なしで失敗します。 |
| `list_segments` | 既存のセグメントをページ単位で閲覧します (`page`、`page_size`、オプションの `name` フィルター)。Filter タイプと File タイプのセグメントのみをメタデータ (`id`、`name`、`type`、`source`、タイムスタンプ) として返します。Warehouse、Analytics、Composite は除外されます。 |
| `get_segment` | ID を指定して単一のセグメントの完全なフィルター定義を、`create_custom_segment` が受け付けるのと同じ形式で読み取ります。ファイルベースおよびコホートインポートのセグメントは、フィルターツリーなしでメタデータのみを返します。 |
| `start_segment_count` / `poll_segment_count` | セグメントの非同期のユーザーカウントを開始し (オプションの `callback_url` Webhook 付き)、結果をポーリングします。結果にはチャネルレベルの到達可能性が含まれ、チャネル別およびプラットフォーム別の内訳も利用できます。結果は 15 分間キャッシュされ、ジョブは通常 30 秒以内に完了します。 |
| `get_value_suggestions` | ユーザー属性またはイベント属性について、保存されている最大 5,000 件の一意の値 (`string`、`double`、または配列/オブジェクトのバリアント) を取得します。等価フィルターを記述する前に実際の値を確認するのに便利です。`array_object` 属性の場合は、`node_attribute_name` / `node_data_type` で子フィールドの値を解決します。 |
| `describe_segment_filters` | セグメントやクエリを作成する前に意図を確認するため、フィルターセットを平易な英語の文章に変換します。`create_custom_segment` とは異なり、`filter_operator` は `difference` も受け付けます。 |
| `deep_validate_segment_filters` | ワークスペースのライブカタログに照らして、フィルターセット (属性の存在、データ型、演算子) を意味的に検証します。**常に HTTP 200 を返します** — ステータスコードではなく、レスポンスの `is_valid` フィールドを確認してください。失敗した場合、`errors` に各問題のドット記法のパスが示されます。 |
| `create_recent_query` / `get_recent_query` / `get_recent_query_filters` | **セグメントを作成せずに** オーディエンスをカウントします。アドホックのオーディエンスクエリを実行し (オプションで特定の `platforms` に限定するか、`cs_id` で既存のセグメントにリンク)、結果をポーリングし、フィルターを読み戻します。クエリの実行中、`status` は `received`、`running`、または `retry_wait` で、その後 `success` (`user_count` 付き) または `failure` になります。失敗した場合、`failure_reason` に理由が示されます。`reachability` を渡すと、プッシュ、メール、SMS、WhatsApp のうちどれをカウントするかを選択できます。省略したチャネルはスキップされ、リクエストしたチャネルのみが `reachability_count` に表示されます。 |
| `is_user_in_segment` | 特定のユーザーが最大 10 個のセグメントに含まれているかどうかをリアルタイムで確認します。`segment_eligibility: false` は、そのセグメントタイプがリアルタイム評価をサポートしていない (バッチのみ) ことを意味し、"含まれていない" という意味ではありません。 |

<Info>
  * セグメントフィルターでは、ダッシュボードの表示名ではなく、イベントと属性の正確な **内部** (プラットフォーム) 名を使用する必要があります (例: "City" ではなく `moe_city`)。**イベント** 名または **イベント属性** 名として使用された表示名は作成時に受け入れられ、ユーザー属性の表示名もカタログチェックで解決できない場合は通過します。いずれの場合も、後でカウントが **エラー理由なし** で失敗します。まず `find_events`、`find_user_attributes`、`find_event_attributes` で名前を解決し ([カタログの検出](#catalog-discovery)を参照)、常に返された `name` フィールドを使用してください。
  * 等価の指定方法は属性のデータ型によって異なります。`equals` は有効な演算子ではありません。`string`、`double`、`array_string`、`array_double` 属性の場合、等価は **リスト** 値を伴う `"operator": "in"` です (例: `"value": ["Mumbai"]`)。スカラー型の場合、"is not" は同じ演算子に `"negate": true` を指定します。**配列** 属性を否定するには、フィルターの `array_filter_type` キーを削除します。`negate` と一緒に残すとフィルターが無効になります。`is` は `bool` 属性および `datetime` 属性の日付部分に対する等価演算子です。`string` 属性では空であるかのチェック (`"value": ""`) 用に予約されているため、テキストの等価には使用しないでください。`geopoint` 属性は演算子をまったく取りません。データ型ごとの正確なセットは `discover_schema(kind="component", id="segment_filters")` から取得してください。
  * イベントを実行 **していない** ユーザーをターゲットにするには、`actions` フィルターに `executed: false` を設定し、`"execution": {"type": "exactly", "count": 0}` と組み合わせます。この組み合わせは必須で、`aggregation_attributes` は省略する必要があります。または、肯定の `actions` フィルターを `excluded_filters` に配置すると、一致するユーザーが完全に除外されます。
  * 作成時によくあるエラー: `409` (名前がすでに使用されている)、`400` (フィルターの形式が正しくない、または API が受け付けない演算子)、`413` (フィルターが大きすぎる、またはネストが深すぎる)。`400` はフィールドを示さないため、バリエーションを試して再試行するのではなく、フィルターの形式を再確認してください。または、`deep_validate_segment_filters` で事前チェックを行うと、`is_valid: false` と各問題のパスを含む `200` が返されます。
</Info>

<Info>
  * PII としてマークされた属性は、MCP を通じて公開されません。
  * **Email (Standard)** と **Mobile Number (Standard)** は、PII としてマークされていない場合でもマスクされます。

  これは `get_user_events`、`get_recent_query`、`get_recent_query_users`、`get_value_suggestions` に適用されます。
</Info>

### フロー

| ツール | 説明 |
| - | - |
| `search_flows` | 名前、ステータス、その他の条件でフローを検索します。 |
| `get_flow` / `get_flow_version` | フローの設定、またはその特定のバージョンを読み取ります。 |
| `get_flow_analytics` | フローレベルのヘルスビューで、フロー全体のパフォーマンスを示します。Flow Analytics はベータ版です。 |
| `get_flow_channel_analytics` | フローのチャネル別の分析で、フロー内で Email、Push、SMS、その他のチャネルがどのようなパフォーマンスだったかを示します。Flow Analytics はベータ版です。 |
| `update_flow_status` | フローを一時停止、再開、停止、廃止、アーカイブ、またはアーカイブ解除します。停止と廃止は元に戻せません。 |

### ダッシュボード

| ツール | 説明 |
| - | - |
| `list_dashboards` | ワークスペースで利用可能な分析ダッシュボードを一覧表示します。 |
| `get_dashboard` | ID を指定して単一のダッシュボードの完全なメタデータを返します。 |
| `get_chart_data` | ダッシュボード内の特定のチャートの分析データを取得します。 |

### 検索と読み取り

| ツール | 説明 |
| - | - |
| `search_campaigns` | 名前、ステータス、ID、チャネル、配信タイプ、または日付範囲でキャンペーンを検索します。下書きを表示するには、ステータスフィルターに `DRAFT` を含めます。`channel` フィルターは Push、Email、SMS、MMS のみを受け付けます。WhatsApp と Webhook のキャンペーンを含めるには、このフィルターなしで検索します。 |
| `get_campaign` / `get_campaign_meta` | 単一のキャンペーンの完全な設定とコンテンツ、またはメタデータのみを取得します。 |

**サポートされているステータスフィルター:** `ACTIVE`、`DRAFT`、`EXPIRED`、`NOT_SENT`、`PAUSED`、`SCHEDULED`、`SENDING`、`SENT`、`STOPPED`、`UNDER_REVIEW`、`REJECTED`。

### キャンペーン分析

<Info>
  キャンペーン分析ツールでは、1 回のクエリあたりの日付範囲が最大 **30 日** に制限されています。フロー分析ツールでは最大 **90 日** まで指定できます。分析ツールはそれぞれ独自の期間を使用し、分析タイプと粒度によって異なります。`run_user_analysis` は他よりも制限が厳しく、リテンションでは時間単位の分析が 24 時間までに制限されています。
</Info>

| ツール | 説明 |
| - | - |
| `get_campaign_stats` | 配信率、開封数、クリック数、CTR、チャネル固有の指標などの集計パフォーマンスです。1 回の呼び出しで最大 50 件のキャンペーンに対応します。 |
| `get_detailed_campaign_stats` | コンバージョン目標、デバイス/プラットフォーム、ロケール、A/B バリエーション別の内訳です。 |
| `get_delivery_stats` | 配信ファネル (到達可能なユーザー、フリークエンシーキャップによる除外、送信/配信の失敗、プラットフォームごとのデバイス統計) です。 |
| `get_click_performance` | URL ごとのクリックの内訳で、合計数とユニーク数を含みます。 |
| `get_device_analytics` | OEM、アプリバージョン、休眠状態などのデバイスディメンション別のパフォーマンスで、多次元の分割に対応します。 |

### 分析

| ツール | 説明 |
| - | - |
| `discover_analyze_schema` | 分析のリクエスト形式を返します。分析を実行する前に呼び出してください。 |
| `run_behavior_analysis` | ユーザーが選択したイベントを時間の経過とともにどのように実行しているかを分析します。 |
| `run_funnel_analysis` | 順序付けられた一連のイベントにわたるコンバージョンを測定します。 |
| `run_retention_analysis` | 開始イベントの後、ユーザーが時間の経過とともにどのように戻ってくるかを測定します。 |
| `run_user_analysis` | ユーザープロパティ別にユーザーベースを分析します (例: 地域、デバイスタイプ、言語別のユーザーの内訳)。 |
| `run_session_source_analysis` | ソースプロパティ別にセッションを分析します。ソース、メディア、またはキャンペーン別のセッション数、平均セッション時間、コンバージョン、直帰率を分析します。 |

<Info>
  * PII としてマークされた属性は、MCP を通じて公開されません。
  * **Email (Standard)** と **Mobile Number (Standard)** は、PII としてマークされていない場合でもマスクされます。

  5 つの分析ツールすべてにおいて、これらの属性はユーザープロパティによるグループ化や分割には使用できません。
</Info>

### カタログの検出

セグメントを作成したり行動分析を実行したりする前に、これらを使用して適切なイベントと属性を見つけます。3 つのツールはいずれも、カタログ全体ではなく、信頼度スコア付きの上位の一致結果を返します。イベント名と属性名はワークスペースごとに異なるため、アシスタントがそれらを推測してはいけません。

| ツール | 説明 |
| - | - |
| `find_events` | 自然言語の用語 (例: "purchase") に一致するトラッキング可能なイベントを検出します。`query` とオプションの `limit` (1～50、デフォルトは 10) を受け取り、フィルターで `action_name` として使用する内部の `name` を返します。60 日を超えて非アクティブなイベントは除外されます。 |
| `find_event_attributes` | 特定のイベントの属性を検出します。`event_name` (`find_events` からの正確な名前)、`query`、オプションの `limit` を受け取ります。 |
| `find_user_attributes` | 自然言語の用語 (例: "city") に一致するユーザー属性を検出します。`query` とオプションの `limit` を受け取り、内部の `name` と、有効なフィルター演算子を決定する `data_type` を返します。 |

### フィードバック

| ツール | 説明 |
| - | - |
| `submit_feedback` | ツールの改善に役立てるため、アシスタントがツールの品質に関する問題を MoEngage に報告できるようにします。 |

## キャンペーン作成のステップ

<Steps>
  <Step title="形式を検出する">
    アシスタントは、チャネルと配信タイプに応じて `discover_schema` を呼び出し、正確なペイロード構造を取得します。
  </Step>

  <Step title="オーディエンスを見つける">
    `find_events` / `find_user_attributes` と `create_custom_segment` (リーチを確認するための `start_segment_count` と併用) を使用して、適切なユーザーをターゲットにします。
  </Step>

  <Step title="コンテンツを作成する">
    メール HTML や Jinja によるパーソナライズについては、`get_content_guide` を呼び出して検証済みのパターンを取得します。
  </Step>

  <Step title="下書きを作成する">
    `create_campaign_draft` (または既存の下書きを調整する場合は `patch_campaign_components`) を使用します。
  </Step>

  <Step title="パーソナライズをプレビューする">
    `create_personalization_preview` で、サンプルユーザーに対してコンテンツが正しくレンダリングされることを確認します。
  </Step>

  <Step title="検証する">
    `validate_campaign_draft` が公開時の完全なチェックを実行し、フィールドレベルの問題を報告します。
  </Step>

  <Step title="公開する">
    **MoEngage ダッシュボード** から下書きを確認して公開します。
  </Step>
</Steps>

## プロンプトの例

| 目的 | プロンプトの例 |
| - | - |
| キャンペーンを作成する | *"明日の IST 午前 10 時に全ユーザーへ送る 'Weekend sale' というタイトルの 1 回限りのプッシュの下書きを作成してください。"* |
| コンテンツをパーソナライズする | *"名のフォールバック付きのメールの挨拶文を書き、ユーザーの都市に触れてください。"* |
| セグメントを作成する | *"過去 7 日間にメールを開封したものの購入しなかったユーザーのセグメントを作成してください。"* |
| セグメントのリーチを確認する | *"'Cart abandoners' セグメントには到達可能なユーザーが何人いますか？"* |
| フローを確認する | *"オンボーディングフローのステップと現在のステータスを表示してください。"* |
| フローを分析する | *"過去 2 週間のウィンバックフローのチャネル別のパフォーマンスはどうですか？"* |
| パフォーマンスを確認する | *"過去 2 週間のメールキャンペーンの CTR はどれくらいですか？"* |
| ダッシュボードを読み取る | *"'Weekly engagement' ダッシュボードの数値を取得してください。"* |
| 行動を分析する | *"オンボーディングを完了したユーザーの 7 日間のリテンション分析を実行してください。"* |
| トラフィックソースを分析する | *"先月最も多くのセッションをもたらしたソースはどれで、直帰率はどれくらいでしたか？"* |
| 配信を診断する | *"前回のプッシュキャンペーンの配信率が低かったのはなぜですか？"* |
| デバイスのインサイト | *"プッシュキャンペーンにおける Android と iOS のパフォーマンスを比較するとどうですか？"* |
| カタログを調べる | *"購入関連のイベントとして何をトラッキングしていて、それらにはどのような属性がありますか？"* |
| フィルターを確認する | *"作成する前に、このセグメントのフィルターの意味を平易な言葉で説明してください。"* |
| MCP 経由でセグメントを作成する | *"過去 30 日間に 3 回以上購入したムンバイのユーザーのセグメントを作成してください。"* |
| セグメントをカウントする | *"'Cart abandoners' セグメントには到達可能なユーザーが何人いますか？チャネル別に分けてください。"* |
| 作成せずにカウントする | *"過去 7 日間にメールを開封したものの購入しなかったユーザーは何人ですか？カウントだけで、セグメントは作成しないでください。"* |
| メンバーシップを確認する | *"ユーザー 12345 は現在 'Churn risk' セグメントに含まれていますか？"* |

## 既知の動作と制限事項

お客様とアシスタントが予期せず問題に直面するのではなく回避できるよう、既知の特性を記載しています。

### 必要なツールを有効にする

書き込みツール (例: キャンペーンの作成、コンテンツブロックの編集、セグメントの作成) は、クライアントでデフォルトでオフになっている場合があります。アシスタントが操作を実行するアクセス権がないと応答した場合は、クライアントのコネクター設定でそのツールを有効にしてください。Claude では、**Settings** → **Connectors** → **MoEngage** → **Tool permissions** で設定できます。有効にできるツールは、引き続き MoEngage のロールによって制限されます。

### ツールリストを更新する

新しいツールは随時コネクターに追加されます。新しくリリースされたツールが表示されない場合は、クライアントでコネクターのツールリストを更新してください。更新オプションがない場合は、MoEngage コネクターを切断して再接続 (再認証) し、最新のツールを取得してください。

### セグメンテーションの動作

| 動作 | 詳細 |
| - | - |
| 内部名のみ | `create_custom_segment` には、`user_attributes` フィルターのみを対象とする部分的なセーフティネットとしてのカタログチェックがあり、カタログが利用できない場合はチェックなしで通過します。イベント名とイベント属性名はまったくチェックされないため、解決されていない誤った名前は、後でエラー理由なしで失敗するカウントジョブとして表面化する可能性があります。必ず最初に `find_events` / `find_user_attributes` / `find_event_attributes` で名前を解決し、`deep_validate_segment_filters` で検証してください。 |
| 古いイベントは非表示 | `find_events` は、60 日を超えて非アクティブなイベントを除外します。 |
| 等価の指定方法は属性のデータ型によって異なる | `equals` は有効な演算子ではなく、フィールドを示さない単純な `400` (Bad Request) で拒否されます。`string`、`double`、`array_string`、`array_double` 属性の場合、等価は **リスト** 値を伴う `"operator": "in"` です (例: `"value": ["Mumbai"]`)。スカラー型の場合、"is not" は同じ演算子に `"negate": true` を指定します。`notEquals` はありません。**配列** 属性を否定するには、フィルターの `array_filter_type` キーを削除します。`negate` と一緒に残すとフィルターが無効になります。`is` は `bool` 属性および `datetime` 属性の日付部分に対する等価演算子です。`string` 属性では、`is` は空であるかのチェック (`"value": ""`) 用に予約されているため、テキストの等価には使用しないでください。`geopoint` 属性は演算子をまったく取らず、`value` (緯度)、`value1` (経度)、`radius` のみを取ります。属性のデータ型ごとの正確なセットは `discover_schema(kind="component", id="segment_filters")` から取得し、作成前に `deep_validate_segment_filters` でフィルターを確認してください。 |
| 否定のイベント条件には `executed: false` と `exactly 0` が必要 | "イベントを実行していない" ことを表すには、`actions` フィルターに `executed: false` を設定し、`"execution": {"type": "exactly", "count": 0}` と組み合わせます。`aggregation_attributes` は省略する必要があります。または、肯定の `actions` フィルターを `excluded_filters` に配置します。 |
| セグメントタイプによって MCP のサポートが異なる | `create_custom_segment` は、フィルターベース (ELASTIC\_SEARCH) のセグメントのみを作成します。`list_segments` は Filter セグメントと File セグメントを返しますが、Warehouse、Analytics、Composite は除外します。`get_segment` は Filter セグメントに対してのみ完全なフィルターツリーを返し、File セグメントとコホートインポートのセグメントはメタデータのみを返します。`is_user_in_segment` は Filter セグメントをリアルタイムで評価します。ファイルベース、ファネル、リテンション、予測セグメントはバッチのみです。各タイプの意味については、[セグメントの種類](/docs/ja/user-guide/segment/getting-started/types-of-segments)を参照してください。 |
| カウントは 15 分間キャッシュされる | 期間内に成功したカウントがすでに存在する場合、`start_segment_count` はキャッシュされた結果 (`served_from_cache: true`) を返します。 |
| 検証はいずれの場合も HTTP 200 を返す | `deep_validate_segment_filters` では、レスポンス本文の `is_valid` を確認してください。 |
| 値の候補には上限がある | 属性ごとに 5,000 件の一意の値。 |
| PII 属性と連絡先属性は制限される | PII としてマークされた属性は MCP を通じて公開されず、`get_user_events`、`get_recent_query`、`get_recent_query_users`、`get_value_suggestions` では利用できません。**Email (Standard)** と **Mobile Number (Standard)** は、PII としてマークされていない場合でも、これらのツールではマスクされます。 |
| ロールベースの権限が適用される | セグメントとクエリの作成には、MoEngage のロールに対応する作成/管理権限が必要です。読み取りツールには読み取りアクセスが必要です。[セキュリティと権限](#security-and-permissions)を参照してください。 |

### セグメンテーションの制限

セグメンテーションツール自体はレート制限を適用しません。以下の制限は、ツールが呼び出す MoEngage API によるものです。一定期間内に作成できるセグメントやクエリの数に関する公開されたクォータはなく、ポーリング間の最小間隔も適用されず、同時実行のカウントジョブ数に関する上限も文書化されていません。

| 制限 | 値 |
| - | - |
| `is_user_in_segment` の 1 回の呼び出しで評価されるセグメント数 | 10 |
| `get_value_suggestions` で返される値 | 5,000 件の一意の値 |
| `list_segments` の 1 ページあたりに返されるセグメント数 | 1～100 (デフォルトは 10) |
| セグメントカウント結果のキャッシュ | 15 分 |
| フィルターのペイロードサイズ | サイズが大きすぎる、またはネストが深すぎるフィルターは `413` (Payload Too Large) エラーで拒否されます |
| フィルターのネストの深さ | `nested_filters` は 1 レベル |

プラットフォームレベルでは、引き続きレート制限が発生する場合があります。

<Note>
  リアルタイムのメンバーシップチェックを含む一部のセグメンテーション API は、トラフィックが多い場合に `429` (Too Many Requests) エラーを返すことがあります。公開されたリクエストクォータはありません。`429` が発生した場合は、約 60 秒後に再試行してください。すべてのツール呼び出しは MoEngage API ゲートウェイも経由し、ゲートウェイが独自のトラフィック制御を適用する場合があります。
</Note>

### その他の制限事項

* キャンペーンの **公開** は MCP では利用できません。下書きは MoEngage ダッシュボードから公開します。
* **キャンペーンの作成は Push と Email のみです。** SMS、Webhook、WhatsApp のキャンペーンは検索と分析が可能ですが、作成と編集は MoEngage ダッシュボードで行う必要があります。
* **キャンペーンの `channel` フィルターは Push、Email、SMS、MMS のみを受け付けます。** WhatsApp と Webhook のキャンペーンはチャネルでフィルタリングできないため、結果に含めるにはフィルターを省略してください。WhatsApp は他の場所ではサポートされています。フロー分析は WhatsApp に対応しており、WhatsApp はセグメントの到達可能性カウントにも表示されます。
* キャンペーン分析の **日付範囲** は、1 回のクエリあたり **30 日** に制限されています。フロー分析では最大 **90 日** まで指定できます。
* **バッチサイズ**: `get_campaign_stats` は 1 回のリクエストで最大 **50 件のキャンペーン ID** を受け付けます。
* **コンテンツサイズ**: メール HTML は大きくなる場合があります (10～50 KB)。完全なコンテンツは意図的に取得してください。
* **キャンペーン名の日付形式**: キャンペーン名では、日付が **DDMMYY** としてエンコードされていることがよくあります (例: `230326` = 2026 年 3 月 23 日)。分析結果がすべてゼロの場合は、まず日付範囲を確認してください。
* **PII 属性と連絡先属性は分析ツールでは利用できません。** `run_behavior_analysis`、`run_funnel_analysis`、`run_retention_analysis`、`run_session_source_analysis`、`run_user_analysis` では、これらの属性をユーザープロパティによるグループ化や分割に使用できません。
  * PII としてマークされた属性は、MCP を通じて公開されません。
  * **Email (Standard)** と **Mobile Number (Standard)** は、PII としてマークされていない場合でもマスクされます。
* **分析レスポンスの形式**: 統計はチャネル横断の単一の構造として返されます。キャンペーンのチャネルに該当しない指標は、存在しないのではなく `0` として返されます。ゼロ以外のフィールドからキャンペーンのチャネルを推測しないでください。

## セキュリティと権限

* MCP サーバーは、**下書きの作成と検証**、**セグメントの作成**、キャンペーン、フロー、ダッシュボードの **読み取りと分析** を行えます。キャンペーンの公開は **行いません**。公開はダッシュボードで人間が行う操作です。
* すべてのアクションは、認証されたユーザーの **ワークスペースとロール** にスコープが限定されます。ロールに権限がないツールは利用できません。
* AI アシスタントと共有されるデータは、各 AI プロバイダーのデータ取り扱いポリシーの対象となります。MoEngage は、AI の[サブプロセッサー](https://www.moengage.com/moengage-list-of-sub-processors/) (Anthropic と OpenAI を含む) を Web サイトに掲載しています。
* 詳しくは、MoEngage の[プライバシーポリシー](https://www.moengage.com/privacy-policy/)と[利用規約](https://www.moengage.com/terms-of-use/)を確認してください。

## トラブルシューティング

<AccordionGroup>
  <Accordion title="MCP サーバーまたはデータにアクセスできない">
    接続は、ダッシュボードセッションとは関係なく、承認時に選択したワークスペースと環境に紐付けられています。

    1. 想定しているワークスペースに対して接続が承認されたことを確認します。ダッシュボードでワークスペースを変更しても、接続は変更されません。
    2. 接続先を別のワークスペースに変更するには、MCP クライアントから再認証し、そのワークスペースを選択します。
  </Accordion>

  <Accordion title="想定していたツールが利用できない">
    まず、クライアントのコネクター設定でツールが **有効** になっていることを確認します。[必要なツールを有効にする](#enable-the-tools-you-need)を参照してください。次に、MoEngage のロールに対応する権限 (例: 作成ツールの場合はキャンペーンの作成/管理) があることを確認します。新しく発表されたツールの場合は、[ツールリストを更新](#refresh-the-tools-list)してください。
  </Accordion>

  <Accordion title="新しく発表されたツールが表示されない">
    コネクターのツールリストを更新するか、MoEngage コネクターを切断して再接続し、再認証してください。[ツールリストを更新する](#refresh-the-tools-list)を参照してください。
  </Accordion>

  <Accordion title="ワークスペースまたはデータセンターの切り替え時に再認証が失敗する">
    アクティブな接続でワークスペースやデータベースを切り替えると、一時的にエラーが発生することがあります。しばらく待ってから再認証してください。通常は再試行で接続に成功します。
  </Accordion>

  <Accordion title="セグメントのカウントがエラー理由なしで失敗する">
    これはほとんどの場合、フィルターで内部名ではなく表示名が使用されていることを意味します。[カタログの検出](#catalog-discovery)で名前を解決し、セグメントを再度作成する前に `deep_validate_segment_filters` で再検証してください。
  </Accordion>

  <Accordion title="セグメントまたはクエリが作成されない">
    レスポンスで具体的なエラーコードを確認してください。`409` は名前がすでに使用されていること、`400` はフィルターの構造またはその演算子のいずれかが無効であること、`413` はフィルターが大きすぎるかネストが深すぎることを意味します。`400` にはフィールドレベルの詳細は含まれません。それ以外は正しく見えるフィルターで `400` が発生する場合は、通常、演算子が原因です。適切な演算子は属性のデータ型によって異なります。テキスト (`string`) 属性の場合、等価はリスト値を伴う `"operator": "in"` です。`equals` でも `is` でもありません (`is` は `bool` 属性と空であるかのチェック用です)。まず `deep_validate_segment_filters` を実行してください。単純な `400` の代わりに、`is_valid: false` と各問題のパスを含む `200` が返されます。[セグメント](#segments)のよくあるエラーに関する注記を参照してください。
  </Accordion>

  <Accordion title="is_user_in_segment が segment_eligibility: false を返した">
    これは "含まれていない" という意味ではなく、セグメントタイプがリアルタイム評価をサポートしていないことを意味します (ファイルベース、ファネル、リテンション、予測セグメントはバッチのみ)。セグメントのタイプを確認するか、`start_segment_count` による保存済みのカウントを代わりに使用してください。
  </Accordion>

  <Accordion title="アシスタントがセグメンテーションツールを利用できない">
    ツールの利用可否は、MoEngage のロールとクライアントのコネクター設定によって異なります。[セキュリティと権限](#security-and-permissions)と[必要なツールを有効にする](#enable-the-tools-you-need)を参照してください。
  </Accordion>
</AccordionGroup>