Skip to main content

​
概要

Nudgen は、アプリのオリジンにある /mcp エンドポイントで MCP サーバーをホストしています。このサーバーは Streamable HTTP 経由の MCP 2026-07-28 に対応し、OAuth 2.1 を必要とします。このトランスポートに対応するクライアントを接続してください。ブラウザーで Nudgen にサインインし、ワークスペースを選択して、クライアントが要求する権限を承認します。後からダッシュボードでワークスペースを切り替えても、接続先は選択したワークスペースのままです。

​
これが重要な理由

アシスタントは、ダッシュボード セッションやパーソナル アクセス トークンを扱うことなく、連絡先やキャンペーンの参照、近隣ビジネスの検索、コンテンツの下書き、キャンペーン開始の準備を行えます。実際に送信または予約する前に、毎回ブラウザーで内容を確認します。

​
クライアントを接続する

本番環境のエンドポイントは次のとおりです。
OAuth 対応クライアントに リモート HTTP MCP サーバーとして追加します。クライアントはエンドポイントから Nudgen の認可サーバーを検出し、ブラウザーでのサインインと同意フローを開きます。クライアントにアクセスを許可するワークスペースを選択し、必要なスコープだけを承認してください。 ディスカバリー ドキュメント： 認可サーバーは、PKCE S256、リソース バインディング、リフレッシュ トークンのローテーションを伴う認可コード フローを使用します。Client ID Metadata Documents と動的クライアント登録に対応しています。 Codex CLI では、次のコマンドを使用します。
nudgen という名前のクライアントがすでに設定されている場合は、そのエントリを /mcp URL で更新してください。 データの参照だけが必要な場合は、campaigns:read を要求します。クライアントが連絡先、下書き、ブランド設定、またはインポートしたリードを変更する場合は、campaigns:write を追加します。開始承認をリクエストする必要がある場合に限り、campaigns:send を追加してください。
パーソナル アクセス トークンは開発者 API の認証に使用できますが、/mcp の認証には使用できません。MCP クライアントは OAuth サインインを完了する必要があります。

​
利用できるツール

create_campaign は、**キャンペーンの下書き（one-time、drip、lifetime）**を保存します。直接送信または予約することはできません。get_campaign を使うと、開始前に件名、内容、リンク、オーディエンス、送信者を確認できます。 サーバーは、campaigns:read で次の読み取り専用リソースも公開します。

​
マップリードを検索してインポートする

  1. 都市名と marketing agency など、場所とビジネス キーワードを指定して search_map_leads を呼び出すようアシスタントに依頼します。
  2. 任意のフィルターとして、radiusKm（1～100）、lat と lng、メールアドレスを公開しているビジネスだけを残す emailOnly を使用できます。
  3. 結果に nextPageToken が含まれる場合は、それを pageToken として渡して次のページを読み込みます。
  4. 同じ場所とキーワードに加えて、保存するリード オブジェクトを指定し、import_map_leads を呼び出すようアシスタントに依頼します。1 回の呼び出しで最大 200 件のリードを受け付けます。
インポートすると、接続先ワークスペースに連絡先が書き込まれます。メールアドレスのないリードはスキップされます。既存のリードは更新されます。

​
キャンペーン開始を承認する

  1. get_campaign で下書きを確認するようアシスタントに依頼します。
  2. キャンペーン ID と、希望する「今すぐ送信」または正確な予約時刻を指定して prepare_campaign_launch を呼び出すよう依頼します。1 回限りの承認 URL が返されます。この時点ではメールは送信されません。
  3. URL を開き、ワークスペース、推定受信者数、内容、送信者、送信時刻を確認して、開始を承認をクリックします。
  4. クライアントに戻り、同じキャンペーン ID、送信時刻、approvalId を指定して launch_campaign を呼び出します。
承認は 10 分後に期限切れになり、1 回だけ使用できます。キャンペーンまたは送信者が変更された場合は、新しい承認をリクエストしてください。Nudgen は開始時に、送信者の準備状態、対象受信者、サブスクリプション、クォータ、キューの利用可否を再確認します。配信は、キャンペーン ワーカーが開始処理を行った後に始まります。
launch_campaign を承認して完了すると、実際のメールが送信される可能性があります。実際のオーディエンスを承認する前に、ダッシュボードのテスト送信フローで受信トレイのプレビューを確認してください。

​
アクセスを管理する

設定 → API キー → 接続済み MCP アプリを開くと、各クライアントの接続先ワークスペースとスコープを確認できます。アクセスが不要になった接続は、ここで取り消してください。取り消すと、そのトークンと保留中の開始承認が無効になります。後から OAuth で再接続できます。 OAuth の認可は最長 90 日間有効です。ワークスペースへのアクセス権を失った場合も、クライアントはそのワークスペースの接続を使用できなくなります。

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

Bearer トークンと直接 REST エンドポイントを使用するスクリプトについては、開発者 API を参照してください。

​
検索範囲と情報補完

APIとMCPは既定で5 kmを使用し、整数の radiusKm 1～100を受け付けます。ダッシュボードの確認画面は表示しません。nextPageToken を pageToken に渡す際は同じ検索条件を維持してください。空のページにも次のページがある場合があります。 enrichmentPending は未完了のWebサイト調査を示します。利用可能な businessSummary と businessSources を確認してください。インポートした情報はキャンペーンの導入文の個別化に役立ちます。メールがない場合、調査が続いている可能性があります。 enrichmentRetryToken がある場合、campaigns:read 権限で retry_map_leads_enrichment に token を渡します。トークンは接続したワークスペース専用で、有効期間15分、1回限りです。インポート前に placeId で結果を統合してください。emailOnly は現在の応答を絞り込むため、再試行後にリードが増える場合があります。

​
下書きの編集と対応範囲

既存の下書きは update_campaign で編集し、delete_campaign で削除できます。どちらも campaigns:write が必要で、メールの送信や予約は行いません。新しい製品機能には専用の OAuth 権限が必要です。要求された場合は再接続して権限を承認してください。 ツール一覧で利用可能なツールと引数を確認できます。ブラウザーへの案内だけでは操作は実行されません。支払い、プロバイダーの認可、招待の送信、ワークスペースの切り替え、機密性の高い支払い先設定はブラウザーで完了してください。MCP 接続は認可したワークスペースに固定されます。管理機能、認証情報、Webhook、追跡コールバック、内部アシスタントは対象外です。 get_api_capabilities で API の対応範囲を確認できます。テスト送信、lifetime の有効化、lifetime イベントには、まず prepare_campaign_action でブラウザー承認を取得し、同じ引数で send_test_email、activate_lifetime_campaign、trigger_lifetime_campaign を呼び出してください。承認の有効期限は10分で、1回のみ使用できます。