> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudgen.net/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP サーバー
> OAuth で AI アシスタントを Nudgen に接続し、マップリードを検索して、ブラウザーでキャンペーン開始を承認します
## 概要
Nudgen は、アプリのオリジンにある `/mcp` エンドポイントで MCP サーバーをホストしています。このサーバーは Streamable HTTP 経由の MCP `2026-07-28` に対応し、OAuth 2.1 を必要とします。このトランスポートに対応するクライアントを接続してください。ブラウザーで Nudgen にサインインし、ワークスペースを選択して、クライアントが要求する権限を承認します。後からダッシュボードでワークスペースを切り替えても、接続先は選択したワークスペースのままです。
## これが重要な理由
アシスタントは、ダッシュボード セッションやパーソナル アクセス トークンを扱うことなく、連絡先やキャンペーンの参照、近隣ビジネスの検索、コンテンツの下書き、キャンペーン開始の準備を行えます。実際に送信または予約する前に、毎回ブラウザーで内容を確認します。
## クライアントを接続する
本番環境のエンドポイントは次のとおりです。
```text theme={null}
https://app.nudgen.net/mcp
```
OAuth 対応クライアントに **リモート HTTP MCP サーバー**として追加します。クライアントはエンドポイントから Nudgen の認可サーバーを検出し、ブラウザーでのサインインと同意フローを開きます。クライアントにアクセスを許可するワークスペースを選択し、必要なスコープだけを承認してください。
ディスカバリー ドキュメント：
| ドキュメント | URL |
| - | - |
| 保護対象リソースのメタデータ | `https://app.nudgen.net/.well-known/oauth-protected-resource/mcp` |
| 認可サーバー | `https://app.nudgen.net/mcp-oauth` |
| サーバー カード | `https://app.nudgen.net/.well-known/mcp/server-card.json` |
認可サーバーは、PKCE S256、リソース バインディング、リフレッシュ トークンのローテーションを伴う認可コード フローを使用します。Client ID Metadata Documents と動的クライアント登録に対応しています。
Codex CLI では、次のコマンドを使用します。
```bash theme={null}
codex mcp add nudgen --url "https://app.nudgen.net/mcp" --oauth-resource "https://app.nudgen.net/mcp"
codex mcp login nudgen --scopes campaigns:read,campaigns:write,campaigns:send
```
`nudgen` という名前のクライアントがすでに設定されている場合は、そのエントリを `/mcp` URL で更新してください。
| スコープ | 許可される操作 |
| - | - |
| `campaigns:read` | ワークスペース、連絡先、キャンペーン、ブランド設定を確認し、マップリードを検索します。 |
| `campaigns:write` | 連絡先とキャンペーン下書きの作成、ブランド設定の更新、AI 下書きの生成、マップリードのインポートを行います。 |
| `campaigns:send` | キャンペーン開始をリクエストし、完了します。このスコープだけでメールが送信されることはありません。 |
データの参照だけが必要な場合は、`campaigns:read` を要求します。クライアントが連絡先、下書き、ブランド設定、またはインポートしたリードを変更する場合は、`campaigns:write` を追加します。開始承認をリクエストする必要がある場合に限り、`campaigns:send` を追加してください。
パーソナル アクセス トークンは[開発者 API](/jp/agents/api) の認証に使用できますが、`/mcp` の認証には使用できません。MCP クライアントは OAuth サインインを完了する必要があります。
## 利用できるツール
| タスク | ツール | スコープ |
| - | - | - |
| ワークスペースを確認する | `get_current_user`, `list_contacts`, `list_campaigns`, `get_campaign`, `get_campaign_stats`, `get_brand_settings` | `campaigns:read` |
| 近隣ビジネスを検索する | `search_map_leads` | `campaigns:read` |
| 作成と編集 | `create_contact`, `create_campaign`, `update_brand_settings`, `generate_email_draft`, `import_map_leads` | `campaigns:write` |
| キャンペーン開始をリクエストして完了する | `prepare_campaign_launch`, `launch_campaign` | `campaigns:send` |
`create_campaign` は、**ワンショット キャンペーンの下書き**を保存します。直接送信または予約することはできません。`get_campaign` を使うと、開始前に件名、内容、リンク、オーディエンス、送信者を確認できます。
サーバーは、`campaigns:read` で次の読み取り専用リソースも公開します。
| リソース | 内容 |
| - | - |
| `nudgen://api-catalog` | ホストされているツールの名前と説明。 |
| `nudgen://team/brand` | 接続先ワークスペースのブランド設定。 |
| `nudgen://campaigns/{id}/summary` | 1 件のキャンペーンの配信統計。`{id}` をキャンペーン ID に置き換えます。 |
### マップリードを検索してインポートする
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 日間有効です。ワークスペースへのアクセス権を失った場合も、クライアントはそのワークスペースの接続を使用できなくなります。
## トラブルシューティング
| 症状 | 対処方法 |
| - | - |
| サインインが始まらない | クライアントが OAuth 対応のリモート Streamable HTTP MCP をサポートし、`https://app.nudgen.net/mcp` を使用していることを確認します。 |
| ツールに追加の権限が必要 | 再接続し、そのワークスペースに必要なスコープを承認します。 |
| 連絡先検索で条件を絞るよう求められる | 検索は名前とメールアドレスに一致し、タグとステータスのフィルター適用後に最大 5,000 件の連絡先を調べます。フィルターを絞り込んでください。 |
| マップリードのインポートでビジネスがスキップされる | メールアドレスのあるリードだけが保存されます。`emailOnly` を true にして再検索するか、すでにメールアドレスが含まれるリードを選択します。 |
| 開始承認の期限が切れた、またはキャンペーンが変更された | 新しい承認をリクエストし、現在のキャンペーンと送信者を確認します。 |
| 開始がブロックされる | キャンペーンが下書きであること、送信者の準備状態、対象連絡先、プランのクォータ、[カスタム ドメイン](/jp/settings/sending-domains)を確認します。 |
Bearer トークンと直接 REST エンドポイントを使用するスクリプトについては、[開発者 API](/jp/agents/api) を参照してください。