APIとMCP

独自のソフトウェア、AIアシスタント、ターミナルからPoint11を利用できます。

概要#

MCP サーバー、API、コマンドラインツールでは、ダッシュボードと同じ操作ができます。キャンペーンや結果を読み取り、同じ作業を開始できます。

  • MCP サーバー: Claude、ChatGPT、その他の AI アシスタントを接続します。
  • API: 独自のコードから https://point11.ai/api/v1 で Point11 を呼び出します。
  • CLI: ターミナルから API を使います。

サインインしてAPI リファレンスを開いてください。Point11 の組織のメンバーが閲覧できます。すべてのリクエストについて、受け取る値と返す値、そして MCP サーバー、API、CLI からどのダッシュボード操作を実行できるかが記載されています。広告などのクリエイティブを顧客のデジタルツインでテストする方法は、APIでクリエイティブをテストするをご覧ください。

AI アシスタントを接続する#

MCP サーバーの URL は https://point11.ai/api/mcp です。案内に従って Point11 にサインインし、アクセスを承認してください。複数の組織に所属している場合は、どの組織を使うかをアシスタントに伝えてください。代わりに API キーで接続するには、以下のクライアント別の手順に従ってください。

使っている製品だけをアシスタントに渡すには、API キーで接続し、製品名を小文字のカンマ区切りで URL に追加します（例: https://point11.ai/api/mcp?products=discovery,inspector）。ツールの一覧が短いほど、アシスタントが作業に使える余裕が増えます。サインインするには、上記の URL を正確にそのまま使い、/api/mcp の後には何も付けないでください。Point11 には各ツールの現行バージョンだけが一覧表示されます。古いバージョンをまだ使っているアシスタントも、引き続き動作します。

Business と Alpha はツールが特に多いため、どちらか一方の一部の領域だけを追加することもできます。製品名、ドット、領域名の順に書きます（例: business.customers）。Business には profiles、customers、crm、goals、products、measurement、google-ads があります。Alpha には chat、projects、files、workflows、ads、brand-kits、advisor、connectors があります。製品と領域は自由に組み合わせられます（例: https://point11.ai/api/mcp?products=discovery,business.customers）。必要なときにツールを検索するアシスタントなら、製品全体やサーバー全体を引き続き使えます。

レジストリやクライアントは、https://point11.ai/api/mcp/server-card でサーバーの説明を読み取れます。

ウェブ版とデスクトップ版の Claude#

  1. Customize > Connectors、続いて + > Add custom connector を開きます。
  2. 名前を Point11 とし、https://point11.ai/api/mcp を正確に入力して Add、続いて Connect を選択します。
  3. 会話内で + > Connectors を開き、Point11 を有効にします。

Team および Enterprise プランでは、まずオーナーが Organization settings > Connectors でコネクターを追加します。Claude のコネクターガイドをご覧ください。

Claude Code#

ターミナルで次を実行します。

bash
claude mcp add --transport http point11 https://point11.ai/api/mcp

続いて Claude Code を開き、/mcp を実行して Point11 を選択し、認証します。代わりに API キーを使うには、ヘッダーとして追加します。

bash
claude mcp add --transport http point11 https://point11.ai/api/mcp \
  --header "Authorization: Bearer $POINT11_API_KEY"

Claude Code の MCP ガイドをご覧ください。

ウェブ版 ChatGPT#

  1. Settings > Security and login を開き、Developer mode を有効にします。
  2. Plugins > + を開きます。Point11、短い説明、Connection にサーバー URL を入力し、接続を作成します。
  3. ツールを確認し、新しい会話を開始して、ツールメニューから Point11 を選択します。

利用できる機能は、アカウントとワークスペースの設定によって異なります。OpenAI の接続ガイドをご覧ください。

デスクトップ版 ChatGPT と Codex#

デスクトップアプリで Settings > MCP servers > Add server を開きます。名前を Point11 とし、Streamable HTTP を選択してサーバー URL を入力します。保存し、Restart、続いて Authenticate を選択します。

Codex CLI では次を実行します。

bash
codex mcp add point11 --url https://point11.ai/api/mcp
codex mcp login point11

代わりに API キーを使うには、キーを保存している環境変数を指定します。

bash
codex mcp add point11 --url https://point11.ai/api/mcp --bearer-token-env-var POINT11_API_KEY

デスクトップ、CLI、IDE の各クライアントは、コンピューター上の設定を共有します。OpenAI の MCP ガイドをご覧ください。

アシスタントでダッシュボードを表示する#

Brand share（ブランドシェア）、Brand win rate（ブランド勝率）、Competitors（競合）など、Discovery のダッシュボードビューをアシスタントに依頼してください。インタラクティブなアプリを表示できるアシスタントは、ダッシュボードで表示されるのと同じカードを、Point11 で開くためのリンクとともに描画します。その他のアシスタントには、同じ数値の短い要約とリンクが返されます。

サインインするか API キーを使う#

  • サインインすると、ご自身として操作します。Point11 からアクセスの承認を求められ、その後はアシスタントやツールが、所属する各組織でのご自身のロールで動作します。AI アシスタントやご自身の作業にはこちらを使います。
  • スクリプトや定期実行ジョブなど、ご自身が操作しなくても動くソフトウェアには API キーを使います。キーは 1 つの組織に対して動作し、付与したアクセス権しか使えません。

一部の操作には、必ずご本人が必要です。ご自身の Alpha の会話とプロジェクト、コメント、Research の調査の下書きは個人に属するため、API キーからはアクセスできません。キャンペーンの一時停止や削除、メンバーの招待や削除には、事前にご本人の承認が必要です。対象の組織と、何がどう変更されるかが正確に表示され、その承認はそのリクエストに対してのみ有効です。請求、API キー、メンバーのロールはダッシュボードでのみ変更できます。

MCP サーバー、API、CLI から開始した作業も、ダッシュボードと同じようにプランの利用分として計上されます。

各アシスタントにできることを選ぶ#

ご自身に代わって操作したことのある AI アシスタントやアプリはすべて、Settings（設定）> Security（セキュリティ） の Connected apps（接続済みアプリ） に一覧表示されます。それぞれがその組織で何をできるかを、Full（フルアクセス）、Read-only（読み取り専用）、Blocked（ブロック） から選択します。オーナーと管理者は、組織全体でメンバーのアシスタントが何をできるかも、Settings（設定）> Security（セキュリティ）> Organization（組織） の AI clients (MCP)（AI クライアント） で Allowed（許可）、Read-only（読み取り専用）、Off（オフ） から選択し、Members' connected apps（メンバーの接続済みアプリ） でメンバーのアプリを取り消せます。変更は次のリクエストから適用され、API キーには影響しません。

API キーを作成する#

管理者とオーナーはキーを作成できます。

  1. Settings（設定）> API keys（API キー） を開き、Create key（キーを作成） を選択します。
  2. Name（名前） を入力し、製品ごとの Access（アクセス権）、有効期限を指定する Expires（有効期限）、キーの所属先を指定する Belongs to（所属先） を選択します。
  3. Create（作成） を選択し、キーをコピーします。キーが表示されるのはこの 1 回だけです。

キーはコードに書かず、シークレットマネージャーに保管してください。1 つの組織で有効にできるキーは最大 10 個です。キーを停止するには Revoke（取り消し） を選択します。Rotate（ローテーション） を選ぶと、キーに新しいシークレットが発行されます。所属先が Me（自分） のキーは、組織を離れるか、キーを管理できなくなった時点で取り消されます。所属先が The organization（組織） のキーは引き続き使えます。

最初のリクエストを送信する#

キーをベアラートークンとして送信します。

bash
curl https://point11.ai/api/v1/discovery/campaigns \
  -H "Authorization: Bearer $POINT11_API_KEY"

読み取りのリクエストには GET を使います。何かを変更するリクエストには POST を使い、JSON ボディと、新しい UUID を指定した Idempotency-Key ヘッダーを付けます。

bash
curl https://point11.ai/api/v1/inspector/scans/start \
  -H "Authorization: Bearer $POINT11_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

キーを使わずにサインインする場合は、組織 ID を指定した Point11-Organization も送信します。組織 ID は Settings（設定）> API keys（API キー） からコピーできます。

レスポンスを処理する#

  • 再試行: リクエストを安全に再試行するには、同じ Idempotency-Key で再送信します。作成や開始を再試行すると最初のレスポンスが返され、処理が二重に行われることはありません。それ以外の変更は再試行すると再度実行され、その結果の状態を返します。そのため、再試行した削除が 404 を返した場合は、その項目がすでに削除されていることを意味します。新しいリクエストごとに新しいキーを使ってください。MCP サーバー経由では、アシスタントがこのキーを idempotencyKey として送信します。作成や開始では必須です。それ以外の変更では省略可能で、キーのないリクエストは新しいリクエストとして実行されます。
  • 一覧: limit（最大 100）を指定します。次のページを取得するには、前のレスポンスの nextCursor を cursor として渡します。最後のページでは nextCursor は null です。
  • 時間のかかる処理: スキャンやキャンペーンを開始すると、すぐに 202 と runId が返されます。進行状況は GET /api/v1/platform/runs-v2/{runId}、MCP サーバーでは platform_runs_get_v2 で確認します。
  • エラー: すべてのエラーには code、message、request_id が含まれます。対応は code に基づいて判断し、サポートに問い合わせる際は request_id を添えてください。
  • 制限: 各キーにはリクエストの上限があり、サインインする各ユーザーにも、利用するすべての組織とアシスタントにまたがる上限があります。残りは RateLimit-Remaining と RateLimit-Reset ヘッダーで確認できます。上限に達すると 429 が返されます。Retry-After の秒数だけ待ってから、もう一度お試しください。

CLI を使う#

CLI には Restish を使います。Restish は API リファレンスを読み取り、各リクエストを同じ名前のコマンド（discovery-campaigns-list など）に変換します。API キーを使います。brew install restish などで Restish をインストールし、キーを POINT11_API_KEY に設定してから、Restish を Point11 に接続します。

bash
restish api connect p11 https://point11.ai --no-discover
restish api set p11 'profiles.default.auth: {type: bearer, params: {token: env:POINT11_API_KEY}}'
restish api set p11 'profiles.default.credentials.apiKey.auth: {type: bearer, params: {token: env:POINT11_API_KEY}}'
restish api sync p11

次に、コマンド名を指定して任意のリクエストを実行します。

bash
restish p11 discovery-campaigns-list

何かを変更するリクエストでは、Idempotency-Key を最初に指定します。

bash
restish p11 inspector-scans-start "$(uuidgen)" url: https://example.com

新しいリクエストを取り込むには、restish api sync p11 をもう一度実行します。