▮▮ 6. AIアプリ連携

1. 対応状況（先に結論）
2. 共通の準備
3. Claude 接続手順
4. ChatGPT で使う
5. Gemini で使う（現状）
6. 会話でできること（ツール一覧）
7. うまくいかないとき

6.1 対応状況（先に結論）

本マニュアル更新時点の接続可否です。ポイントは 「ネイティブ MCP コネクタ」 と 「REST API を使う方式」 の2方式があること。kwtool の API キー（kwk_）は、Claude のコネクタ、ChatGPT デスクトップアプリ（Codex）のネイティブ MCP コネクタ、ChatGPT のカスタム GPT の Actions にそのまま使えます。ChatGPT デスクトップアプリ（Codex）では、URL 末尾に ?key= を付ける方式での接続を実機で確認しています。kwtool は現在 API キー方式のみを提供しているため、OAuth での接続が前提の Gemini のネイティブ接続には対応していません。

MCP コネクタ（6.3 / 6.4 方法1）とカスタム GPT の Actions（6.4 方法3）は、発行済み API キー（kwk_）を接続設定に入れる仕組みです。MCP コネクタでは発行時に表示される AI アプリ連携用 URL（キー入り）を接続画面に貼るのが標準、Actions はキーそのものをヘッダーに入れます。6.4 方法2 は AI アプリにキーを渡しません（方式の選び方とキーの取り扱い → 6.2）。

6.2 共通の準備

どのアプリでも、事前に AI アプリ接続用の API キーを1つ用意します。やることは「発行 → キーまたは URL を控える → お使いのサービスの手順へ」の3つです。

1. ダッシュボードの API キー 画面を開く（→ 2. ログインと API キー）
2. ラベル (用途名・任意) に用途（例: ai-app）を入れ、有効期限 を接続を使い続ける期間に合わせて選び、新しいキーを発行 を押す
   • 注意: 期限が来ると 401 api key expired になり、新しいキーへの差し替えが必要です。ご契約区分やスコープ（使える機能）は選べず、管理者が登録した利用許可の内容がそのまま付きます。用途ごとにキーを分けておくと、1つを失効させても他の連携に影響しません
3. 発行された kwk_ で始まるキーを控える（再表示できません。安全な場所に保管）。同じ画面に AI アプリ連携用 URL（キー入りの /mcp?key=…）も表示されるので、MCP コネクタに URL 方式で接続する場合は URL をコピー でこちらを控えます。REST API を使う Actions（→ 6.4 方法3）は、URL ではなくキーそのものをヘッダーに入れます

MCP コネクタへのキーの渡し方は2方式です。標準は URL 方式（発行時に表示される AI アプリ連携用 URL をそのまま貼る）で、接続画面にヘッダーの入力欄があるアプリではヘッダー方式も使えます。

キーはヘッダーか URL のどちらか一方に入れ、両方には入れないでください（別々のキーだと 400 credential_conflict になります）。

次はお使いのサービスの手順へ進みます: 6.3 / 6.4 / 6.5（どれに当たるかは 6.1 の表）。

6.3 Claude 接続手順

Claude のカスタムコネクタに kwtool を追加します。Pro / Max / Free（1個まで）の個人プランで利用できます。

1. Claude（デスクトップアプリまたは claude.ai）を開く
2. 設定 →「コネクタ（Connectors）」→「カスタムコネクタを追加」
3. 名前は任意（例: kwtool）
4. 「リモート MCP サーバー URL」に、発行時に表示された AI アプリ連携用 URL（https://api.kwtool-ai.com/mcp?key=kwk_あなたのキー。key= を省かない）を貼る
   • ヘッダー方式にする場合: URL は https://api.kwtool-ai.com/mcp（キー無し）、「リクエストヘッダー」にヘッダー名 Authorization ／ 値 Bearer kwk_あなたのキー
5. 「追加」で保存。会話画面の「＋」→「コネクタ」で kwtool を オンにする

接続できたら、こう話しかけるだけでデータが返ります。

「脱毛」市場の経済規模順位と、流入している上位サイトを教えて
「DX」に関連する検索市場を10個挙げて、狙い目を提案して
example.com がリーチしている市場を逆引きして

データの読み方や作法は接続時にサーバーから AI へ自動で伝わります（伝わる内容と、手引き /llms-chat.txt ↗ を Claude のプロジェクトの指示に貼ると加わる内容 → 6.6。キーは貼りません）。

6.4 ChatGPT で使う

ChatGPT デスクトップアプリ（Codex 統合）ならネイティブ MCP コネクタで直結できます（方法1・推奨）。Web 版では仕様を貼って呼び出しコードを作らせる方法（方法2）、カスタム GPT では Actions（方法3）を使います。Web 版で会話だけで使う方法はありません（方法2 は生成されたコードをご自身で実行します）。コードを実行しない方はデスクトップアプリ（方法1）か、Claude のコネクタ（6.3）をお使いください。

方法1: デスクトップアプリ（Codex）にネイティブ MCP 接続（推奨）

ChatGPT デスクトップアプリの「プラグイン → MCP」に kwtool を登録します。

1. 設定 →「プラグイン」→「MCP」タブ →「追加」→「MCP サーバーを追加」
2. タイプで「ストリーミング可能な HTTP」を選ぶ（STDIO ではない）
3. 名前は任意（例 kwtool）
4. URL に、発行時に表示された AI アプリ連携用 URL（https://api.kwtool-ai.com/mcp?key=kwk_あなたのキー。key= を省かない）を貼って保存
   • ヘッダー方式にする場合: URL は https://api.kwtool-ai.com/mcp（キー無し）、「ヘッダー」欄にヘッダー名 Authorization／値 Bearer kwk_あなたのキー

接続できたら、Codex モードの会話でこう話しかけるだけでデータが返ります。

「脱毛」市場の経済規模順位と上位クエリを、測定週つきで教えて
「DX」に関連する検索市場を10個挙げて、狙い目を提案して

データの読み方や作法は接続時にサーバーから AI へ自動で伝わります（伝わる内容と、手引き /llms-chat.txt ↗ をプロジェクトの指示に貼ると加わる内容 → 6.6。内容が更新されたときの取り直し方 → 6.7。キーは貼りません）。

方法2: 仕様を貼って呼び出しコードを作らせる（キーは貼らない・Web でも可）

これは「AI アプリにコードを書かせる」使い方です。読ませる文書と指示文の例は → 4.6。ここでは会話用のアプリで行う場合の手順を示します。

1. ブラウザで https://api.kwtool-ai.com/llms.txt を開き、全文をコピー（AI 向けの API 仕様書です）
2. ChatGPT の新しいチャット（またはプロジェクト）に仕様全文を貼り、「この仕様で『脱毛』市場の上位サイトを取得する curl コマンド（または GAS / Python のコード）を書いて。API キーは環境変数 KW_API_KEY から読むこと」のように依頼する。キーそのものは貼りません
3. 生成されたコマンド・コードを、自分の PC やスプレッドシートで実行する（キーは環境変数やスクリプトプロパティに設定 → 4. 連携レシピ）。取得した結果を ChatGPT に貼れば、会話で分析を続けられます。その前に /llms-chat.txt ↗（AI アプリで会話して使うための手引き）の「ここから下」を貼っておくと、データの読み方（経済規模は順位、数値には測定週、など）を踏まえて分析します

この方法ではキーを渡さず、実行は自分の環境で行います（チャットに貼ったキーは AI サービス側の会話履歴に残ります → 6.2 キーの取り扱い）。取得結果を貼る場合は、社外に出してよいデータかを確認してください。

方法3: カスタム GPT の Actions（キーをヘッダーで・上級者向け）

カスタム GPT の Actions は API キー認証（ヘッダー）に対応し、キーが URL に出ません。MCP ではなく REST API（/v1/query）を直接呼ぶ形です。

1. ChatGPT で「GPT を作成」→「構成（Configure）」→「アクションを作成」
2. スキーマに GET https://api.kwtool-ai.com/v1/query の OpenAPI 定義を記述（resource パラメータでデータを切り替え。仕様は → 3. API リファレンス）
3. 認証（Authentication）で「API キー」を選択。ヘッダー名 X-API-Key、値に kwk_あなたのキー を設定
4. 「指示（Instructions）」に /llms-chat.txt ↗（AI アプリで会話して使うための手引き）の「ここから下」を貼る（データの読み方・制約・保存の作法。手引きにある操作を使うには、対応する resource をスキーマに含めてください → 3. API リファレンス）
5. 保存して、GPT との会話でデータを取得

Actions は Custom GPT（Plus / Pro）で利用できます。REST API にも MCP と同じ上限・課金が適用されます（→ 5. 料金・トラブル）。デスクトップアプリなら 6.4 方法1（ネイティブ MCP）が最短で、Web / カスタム GPT のみ方法2・3 を使ってください。

6.5 Gemini で使う（現状）

Gemini アプリのカスタム MCP 接続は「Gemini Spark」機能でのみ提供され、しかも接続時の認証は OAuth 前提です。加えて対象は「US 在住・18 歳以上・個人 Google アカウント・アクティビティ ON」等に限られます。kwtool は現在 API キー方式のみを提供しているため、ネイティブ MCP 接続はできません。

• 会話利用は Claude（6.3）が確実です。
• 6.4 方法2（仕様を貼って呼び出しコードを作らせる。キーは貼らない）と同じ手順は、Gemini でも試せます。
• スプレッドシートや自作ツールから使うなら REST API を利用してください（→ 4. 連携レシピ）。

6.6 会話でできること（ツール一覧）

接続すると、AI は次の道具（ツール）を必要に応じて自動で使い分けます。市場名や市場 ID が分からなくても、「〇〇について調べて」と話せば AI が探索から始めます。

頼み方の例

よくある進め方は次の5つです。「AI が使う流れ」は手引き /llms-chat.txt ↗ の「よくある進め方」と同じで、あなたは「頼み方の例」の列のように話しかけるだけで構いません。市場名・ドメインは例です。

ツール一覧

使えるツールはキーのスコープ次第です。下の表の「必要スコープ」列は、API キー 画面の あなたが利用できる機能 に並ぶ項目（市場データの閲覧、コンテンツ分析の依頼 など）に対応します。ご契約区分が「KWTOOL 契約連動」「体験版」の通常のキーに付くのは、市場データの参照とコンテンツ分析（参照・依頼）のスコープだけです。

この表はサーバーのツール定義から自動生成しています (全 42 ツール)。キーのスコープに含まれないツールは、一覧に表示されても実行すると権限エラーになります。

ご契約区分が「KWTOOL 契約連動」「体験版」の場合、AI が市場の詳細データ（概要・クエリ・セグメントなど）を取得できるのは kwtool の注目市場に登録した市場だけです。市場の検索・関連市場の発見・ドメインの逆引きはすべての市場で使えます（→ データ範囲）。

サーバーが AI へ自動で伝えることと、手引きを貼ると加わること

MCP コネクタで接続すると、次の内容が接続時にサーバーから AI へ自動で伝わります（貼り付けは不要です）: データの読み方（経済規模は金額でなく順位、数値には測定週を添える、推計流入は実測ではない、市場名は完全一致）・制約とエラーの扱い（注目市場の制限に当たったときの案内、権限・上限・キーのエラーでは再試行しない）・書き込みの作法（明示的に頼んだときだけ、実行前に確認を取る）・非同期ジョブの扱い（完了を待ち続けない、依頼時の市場 ID で結果を見る）・キーを会話に貼らせないこと。手引き /llms-chat.txt ↗ を貼ったときだけ加わるのは、「よくある進め方」（上の表）、取得したデータを社外に出すときの確認、ポータル度・関連市場の読み方です。REST API を使う方式（6.4 方法3）ではサーバーから伝わらないため、手引きを指示欄に貼ってください。

日が経った会話の数値は古い可能性があるため、引用時は測定週を確認してください。コンテンツ分析は完了まで 10〜20 分かかる非同期処理です。依頼後はいったん会話を区切り、しばらくしてから状況を確認してください（AI が完了を待ち続けないよう設計されています）。

提供する機能・ツールは随時更新されます。AI アプリ側の動作がこの一覧やマニュアルと食い違うときは、接続の再設定で最新の定義を取り直してください（→ 6.7）。

6.7 うまくいかないとき

ツール実行時のエラーは、ツールの結果として「エラー: 認証/権限エラー (401): …」「エラー: レート/回数制限 (429): …」「エラー: kwtool API エラー (503): …」のような文言で返ります（AI が言い換えて伝えることもあります）。括弧内の HTTP ステータスと、続く文言で切り分けてください（各エラーの詳細は → 5.4 トラブルシューティング）。

解決しない場合は、使用アプリ名・接続 URL・エラー表示（キーは伏せる）を添えてサポートチームにお問い合わせください。

問い合わせ: サポートチームまで。 ← ダッシュボードへ戻る