Agent 向けクラウドライブラリ接続ガイド

このページは人間ではなく、主に AI Agent に向けて書かれています。任意のクラウドライブラリのページで「AI で使う」をクリックし、ダイアログに表示される一文をコピーして AI アシスタントに送ってください。手動で始めることもできます — 以下の一文の中のライブラリ URL を、あなたが使いたいものに置き換えてください：

https://linkly.ai/docs/ja/library-setup.md を読んで、このクラウドライブラリへの接続を案内してください：https://linkly.ai/blueeon/linkly-init-example

もちろん、ご自身で読み進めていただいても構いません。これは人間が読んでも完結する接続ガイドです。ただし通常のガイドより率直な書き方をしており、各ステップが本当に成功したかをどう見極めるかに重点を置いています。AI アシスタントがウェブにアクセスできない場合は、右上の Copy page からこのページを生の Markdown として取得し、そのまま貼り付けてください。

**この方法では Linkly AI デスクトップアプリのインストールは不要です。**クラウドライブラリはサーバー側でホストされ 24 時間オンラインなので、MCP に対応した AI ツールならそのまま検索できます。自分のパソコン上のファイルをインデックスしたい場合は別の話になります。Agent 向けインストールガイドをご覧ください。

AI Agent へ

以下はすべてあなたに向けた実行指示です。作業を始める前に、最後まで読んでください。

あなたのタスク

ユーザーが指定したクラウドライブラリで質問できる状態にします。次の状態になったら完了です：

あなたが動作しているクライアントが Linkly AI のクラウドゲートウェイ（mcp.linkly.ai）に接続されていること
library="cloud://<owner>/<slug>" を指定して、そのライブラリの中身を実際に検索できること
ユーザーと一緒に最初の実際の質問を行い、実在のドキュメントに基づいた回答を返せていること

最初にすること：URL をライブラリ識別子に変換する

ユーザーから渡されるのは、そのライブラリのウェブページのアドレスで、次のような形をしています：

https://linkly.ai/blueeon/linkly-init-example

一方、検索ツールの library パラメータが求めるのはライブラリ識別子です。両者は同じものの 2 つの書き方にすぎません — ドメイン部分の https://linkly.ai/ を cloud:// に置き換え、後ろの <owner>/<slug> の 2 つのセグメントはそのまま残します：

ユーザーから渡されるもの（ウェブアドレス）	ツールに渡すもの（ライブラリ識別子）
`https://linkly.ai/blueeon/linkly-init-example`	`cloud://blueeon/linkly-init-example`
`linkly.ai/7running/basedge`	`cloud://7running/basedge`

ウェブアドレスをそのまま library パラメータに渡さないでください — 拒否されます。このページの以降の例に出てくる cloud://… は、すべて変換したあとの値です。ユーザーが渡した URL に別のパスセグメント（/settings など）やクエリパラメータが付いている場合は、<owner>/<slug> の 2 つだけを取り出してください。判断に迷ったら、MCP に接続してから list_libraries を 1 回呼んでください。返ってくる結果に正確なライブラリ識別子が入っています。

あなたの権限範囲とルール

自分で実行してよいことと、ユーザーに委ねなければならないことがあります。越権行為をせず、ユーザーの代わりに結果を決めつけないでください：

自分で実行してよいこと：現在の接続状態の確認、MCP 設定の書き込み、ハンドシェイクリクエストの送信、検索ツールの呼び出し、エラーの解釈、結果の報告。設定を書き込むコマンドについては、先にコマンドを提示し、同意を得てください。
ユーザーが行う必要があること：linkly.ai への登録 / ログイン、ユーザー名の設定、ライブラリページでの「リンク」のクリック、ダッシュボードでの API キーの生成、ブラウザでの OAuth 認可。これらはすべてブラウザ内の操作であり、あなたが代わりに行うことはできません。

そして、いくつかの厳守ルール。どれも実際に失敗する場面に対応しています：

ユーザーの既存のローカル MCP 設定を上書きしないこと。 デスクトップアプリを使っているユーザーのクライアントには、通常すでに linkly-ai という名前のサーバーがあり、http://127.0.0.1:60606/mcp を指しています。クラウドはそれに加えてもう 1 本追加するものであり、名前は必ず linkly-ai-cloud を使ってください。同じ名前で書き込むとローカルのほうを黙って置き換えてしまい、ユーザーは突然自分のパソコン上のドキュメントを検索できなくなります。しかもエラーは一切表示されません。
ローカル接続からクラウドライブラリにはアクセスできません。 linkly-ai（ローカル / LAN）の経路では、cloud:// の参照は毎回拒否されます。ローカル接続でクラウドライブラリを再試行しないでください。これは経路の境界であり、たまたま起きた不具合ではありません。
検索のたびに library を明示的に渡すこと。 library パラメータを省略すると、ゲートウェイはデフォルトでユーザーのローカルマシンにルーティングします（デスクトップトンネル経由）。トンネルは Pro 機能なので、無料ユーザーはそのままエラーを受け取ります。クラウドライブラリが暗黙的に含まれることは決してありません。
1 回の呼び出しにつき 1 つのライブラリ。 クラウドライブラリ同士が自動的にまとめて検索されることはありません。2 つのライブラリを調べるなら 2 回呼び出してください。
行動する前に確認すること。 ユーザーはすでに途中まで設定済みかもしれません。頭から機械的に全ステップを実行しないでください。
ユーザーの操作が必要な場面では、必要なことを一度にすべて伝え、そこで止まって 1 回の返信を待つこと。 1 つの作業を何往復もの確認に分割しないでください。
進捗を誇張しないこと。 検証できていないものは完了していません。どこで詰まり、何を試したかを正確に伝えてください。

まず、自分がどの種類のクライアントかを確認する

この先どの経路を進むかは、あなたが設定を書き込めるか、コマンドを実行できるかで決まります：

あなたが動作しているクライアント	進む経路
コマンドラインがある / 設定ファイルを編集できる（Claude Code、Codex、Cursor、Gemini CLI…）	API キー経路（ステップ 2 の方法 A）
コマンドラインのないオンラインアプリケーション（ChatGPT、Claude.ai…）	OAuth 経路（ステップ 2 の方法 B）。URL を 1 つ入力するだけです
Linkly AI デスクトップアプリ内蔵の Chat	何も設定する必要はありません。下の近道をご覧ください

近道：ユーザーがすでに Linkly AI デスクトップアプリをインストールしている場合は、アプリ内の Chat で @ を使ってリンク済みのクラウドライブラリに言及するだけで利用できます。MCP の設定は一切不要です。この経路ではステップ 1 だけを完了すれば十分です。

ステップ 0：現在の状態を確認する

まず接続がどこまで進んでいるかを見極めてから、どこから始めるかを決めます。確認するのは 3 点です。 1. 現在のセッションに Linkly の検索ツールがあるか？どのサーバー由来か？ クラウドゲートウェイは自分の名前を linkly-ai-cloud と名乗り、ローカルのデスクトップアプリは linkly-ai と名乗ります。多くのクライアントではサーバー名がツール名に反映されます（例：mcp__linkly-ai-cloud__search）。 2. コマンドラインが使えるなら、設定済みのサーバーをそのまま一覧表示します：

claude mcp list        # Claude Code
codex mcp list         # Codex

各行の URL を見てください。127.0.0.1 で始まるものはローカル、mcp.linkly.ai はクラウドです。 3. ユーザーは linkly.ai のアカウントを持っているか、このライブラリをリンク済みか？ これはあなたには調べられません。ユーザーに直接尋ねてください。

状態対応表

上から順に照合し、最初に一致した行に従ってください：

確認結果	意味	開始位置
`linkly-ai-cloud` があり、ライブラリを一覧表示できる	クラウド経路は開通済み	ステップ 3 の検証へ直行
`linkly-ai-cloud` はあるが、目的のライブラリが一覧に出ない	経路は開通、ライブラリが未リンク	ステップ 1（「ライブラリをリンクする」の項目だけ）
`linkly-ai`（ローカル）しかない	デスクトップは導入済み、クラウドは未設定	ステップ 1。ローカルの設定は必ず残し、上書きしないこと
Linkly 関連のサーバーが 1 つもない	まったくの新規ユーザー	ステップ 1

ステップ 1：アカウントの準備とライブラリのリンクをユーザーに依頼する

このステップはすべてブラウザ内で完結し、あなたが代わりに実行することはできません。以下の内容をひとつのメッセージでユーザーにまとめて伝え、そこで止まって 1 回の返信を待ってください。 項目ごとに何往復もやり取りしないでください。ユーザーに伝える内容は次のとおりです（言い回しは変えて構いませんが、4 つのパートをすべて含めてください）：

1. 登録してログインする

https://linkly.ai にアクセスして登録またはログインします。Google / GitHub / Notion アカウントに対応しています。接続は無料アカウントのままで最後まで完了できます。

2. ユーザー名を設定する（初回ログイン時のみ）

クラウドライブラリのアドレスは linkly.ai/<username>/<slug> という形なので、アカウントには一意のユーザー名が必要です。Dashboard で案内に従って一度設定すれば、以降は気にする必要はありません。

3. 目的のライブラリのページを開き、「リンク」をクリックする

そのライブラリのウェブアドレス（例：https://linkly.ai/blueeon/linkly-init-example）にアクセスし、ページ右上の「リンク」ボタン（英語表示では Link）をクリックします。ボタンが「リンク済み」に変わり、ステータスバッジが「接続済み」になれば成功です。

**ユーザー自身が作成したライブラリでも、必ず一度「リンク」をクリックする必要があります。**MCP の検索対象は「所有権」ではなく「リンク関係」で決まります — リンクしていないライブラリは、たとえ自分のものでも list_libraries には表示されません。

無料アカウントのリンク枠（Slot）は 1 つです。すでに別のライブラリをリンクしている場合は、そちらを先に解除するか、Pro（99 枠）にアップグレードする必要があります。アップグレードの入口は、ライブラリページに表示される上限案内のダイアログの中にあります。

4. 認証情報を用意する（どちらか一方）

AI アシスタントにコマンドラインがある / 設定ファイルを編集できる場合：https://linkly.ai/dashboard/integrations にアクセスし、「APIキー」エリアで新規作成をクリックして、生成されたキー（lkai_ で始まります）をコピーします。このキーはアカウントの認証情報に相当します。自分の AI ツールだけで使い、他人と共有しないでください。
ChatGPT や Claude.ai のようなオンラインアプリケーションを使う場合：API キーは不要です。この項目はスキップしてください。後ほどブラウザで一度だけ認可を行います。

合格判定：ライブラリページのボタンが「リンク済み」に変わったとユーザーが回答すること。API キー経路を進む場合は、lkai_ で始まるキーを取得できたことも併せて確認してください。

ステップ 2：クラウド MCP に接続する

エンドポイントは固定です：

https://mcp.linkly.ai/mcp

サーバー名には必ず linkly-ai-cloud を使ってください。 linkly-ai は使わないでください — こちらはローカルのデスクトップアプリの名前で、同じ名前を使うとユーザーの既存のローカル設定を上書きしてしまいます。さらに、Linkly Skills を入れている Agent はこの接続をローカル接続だと誤認し、すべての cloud:// リクエストを拒否するようになります。

方法 A：API キー（コマンドラインのあるクライアント、推奨）

まずコマンドをユーザーに提示し、ローカルの設定ファイルにキーを書き込むものであることを説明したうえで、同意を得てから実行してください。 Claude Code：

claude mcp add --transport http linkly-ai-cloud https://mcp.linkly.ai/mcp \
  --header "Authorization: Bearer lkai_あなたのキー"

HTTP MCP に対応したその他のクライアントでは、それぞれの設定ファイルに次のような記述を追加します（Cursor は mcp.json、Gemini CLI は ~/.gemini/settings.json。フィールド名は各社のドキュメントに従ってください）：

{
  "mcpServers": {
    "linkly-ai-cloud": {
      "url": "https://mcp.linkly.ai/mcp",
      "headers": {
        "Authorization": "Bearer lkai_あなたのキー"
      }
    }
  }
}

クライアントごとのフィールドの違い（url / httpUrl / serverUrl）については各 AI クライアント統合ガイドをご覧ください。一部のクライアントは ${env:LINKLY_API_KEY} 構文で環境変数から読み取れるため、キーを設定ファイルに平文で書かずに済みます。 合格判定：ハンドシェイクリクエストを直接送信して、サーバー側が正常であることを確認します：

curl -sf --max-time 10 -X POST https://mcp.linkly.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer lkai_あなたのキー" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'

レスポンスに "serverInfo":{"name":"linkly-ai-cloud" が含まれていれば、認証情報は有効で、接続は正常です。401 が返る場合はキーが誤っているか失効しています。ユーザーにダッシュボードで再生成してもらってください。

方法 B：OAuth（ChatGPT、Claude.ai などのオンラインアプリケーション）

この種のアプリケーションはカスタムリクエストヘッダーを設定できないため OAuth 認可を使いますが、むしろこちらのほうが簡単です — URL を 1 つ入力するだけです：

MCP コネクタを追加する

アプリケーションのコネクタ / MCP 設定で新しいサーバーを追加し、名前に linkly-ai-cloud、URL に https://mcp.linkly.ai/mcp を入力します。

ブラウザでの認可を完了する

保存するとアプリケーションが自動的に linkly.ai の認可ページに遷移します。ユーザーがログインして認可を確認すると、アプリケーションがアクセストークンを取得し、以降のリクエストには自動的に付与されます。再度の認可は不要です。

アプリケーションごとの具体的な入口については ChatGPT で使うと Claude で使うをご覧ください。

方法 C：CLI（任意）

ユーザーが Linkly AI CLI をインストールしている場合は、コマンドラインからも利用できます：

linkly auth set-key lkai_あなたのキー
linkly search "キーワード" --remote --library "cloud://blueeon/linkly-init-example"

--remote は、CLI からクラウドライブラリに到達できる唯一のモードです。省略するとローカルのみを検索します。

MCP を設定した直後は、通常その新しいツールは現在のセッションでは使えるようになりません — ほとんどのクライアントでは設定の再読み込みか新しいセッションの開始が必要です。ユーザーにはっきり伝えてください：「設定は書き込みました。再読み込みしてからもう一度試してください」。ツールが現れたかどうかを現在のセッションで何度も確認し続けないでください。

ステップ 3：エンドツーエンドの検証

ツールが使えるようになったら（ユーザーによるセッションの再起動が必要な場合があります）、2 つのことを行って接続全体が本当に通っているかを確認します。 1. ライブラリが一覧に出ることを確認する： list_libraries を呼び出すと、返ってきた一覧に目的のライブラリが次のような形で含まれているはずです：

- **cloud://blueeon/linkly-init-example** (305 docs) [yours]: Linkly AI インストーラーが初期化したドキュメント

表示されない場合はリンクが成功していないので、ステップ 1 の 3 番目に戻ってください。 2. 実際に検索を 1 回実行する：

search(query="…", library="cloud://blueeon/linkly-init-example")

成功の条件：実在のドキュメントのエントリが返ってくること。

library パラメータは毎回必ず付ける必要があり、cloud://<owner>/<slug> という完全な 2 セグメント形式でなければなりません — 1 セグメントだけ（例：cloud://linkly-init-example）は拒否されます。library を省略するとゲートウェイはユーザーのローカルマシンを検索しに行くため、無料アカウントはその時点でエラーになります。

最初の検索が空で返ってきても、すぐに設定ミスだと決めつけないでください。次の順で確認します：クエリが狭すぎないか → list_libraries に出るこのライブラリのドキュメント数が 0 ではないか（0 ならライブラリの所有者がまだコンテンツをプッシュしていません）→ explore でこのライブラリ全体に何が入っているかを一度眺め、そのうえで狙いを絞って検索する。

トラブルシューティング

症状	原因と対処
ハンドシェイクが 401 を返す	キーが無効か失効しています。ユーザーにダッシュボードで再生成してもらい、先頭の `lkai_` を含めて欠けなくコピーするよう伝えてください。
ハンドシェイクが 403 を返す	認証情報に `mcp` 権限がありません。API キーを作り直せば解決します。
`list_libraries` に目的のライブラリがない	ライブラリがまだリンクされていません。ユーザーにライブラリページで「リンク」をクリックしてもらってください。自分のライブラリでも同じくクリックが必要です。
「リンク」を押すと上限に達したと表示される	無料アカウントのリンク枠は 1 つだけです。別のライブラリのリンクを先に解除するか、Pro（99 枠）にアップグレードしてください。
Desktop に到達できない / Pro が必要というエラーが出る	`library` パラメータを渡し忘れており、リクエストがデフォルトでユーザーのローカルマシンにルーティングされています。`library="cloud://owner/slug"` を付けて再試行してください。
`cloud://` が拒否され、サポートされていないと表示される	接続先がクラウドゲートウェイではなくローカルサーバー（`linkly-ai`）です。この経路ではクラウドライブラリに到達できないため、`linkly-ai-cloud` の接続を別途追加する必要があります。
`library must be in 'owner/slug' format` と表示される	ウェブアドレスをそのまま `library` に渡している可能性が高いです。冒頭の変換ルールに従って `cloud://<owner>/<slug>` の 2 セグメント形式に直してください。1 セグメントだけでも拒否されます。判断に迷ったら `list_libraries` で正確な値を取得してください。
設定したのにツールが現れない	設定の再読み込みか新しいセッションが必要です。これはクライアント側の読み込み仕様であり、設定ミスではありません。
ユーザーのローカル検索が突然何もヒットしなくなった	クラウドの設定に `linkly-ai` という名前を使い、ローカルのほうを上書きしてしまっています。`linkly-ai-cloud` に変更したうえで、ローカルマシンを指す設定を追加し直してください。
ライブラリのドキュメント数が 0	所有者がまだコンテンツをクラウドにプッシュしていません。これはあなたには直せないので、ユーザーに正直に伝えてください。

完了したらユーザーに報告する

最後に、短い一段落で次のことをユーザーに伝えてください：

どの経路（API キーか OAuth か）で接続したか、サーバー名は何か
反映のためにセッションの再起動が必要か
このライブラリにドキュメントが何件あり、だいたいどんな内容か
今後の使い方 — このライブラリを調べたいときはライブラリ名をはっきり伝えるだけでよく、library パラメータはあなたが自動的に付けること

完了できなかったステップがある場合は、どこで詰まったか、何を試したかを率直に説明し、ユーザーが自分で対処できる次の一手を提示してください。

最後に 4 つの質問例を添える

レポートの最後に、ユーザーがそのままコピーして試せる質問を 4 つ提示してください。必ずこのライブラリの実際の内容に基づいてカスタマイズしてください：まず explore でこのライブラリ全体の構成を確認し、必要なら search でいくつかのテーマを抜き出します。そのうえで、確かにこのライブラリの中身を指す質問を 4 つ書いてください。「このライブラリを要約して」のような、どこにでも当てはまる当たり障りのない内容は避けてください。良い質問は「これは確かにこのライブラリの話だ」と一目で伝わります。

はじめに

主な機能

AI ツールと連携

AI Agent 向け

Agent 向けクラウドライブラリ接続ガイド

AI Agent へ

あなたのタスク

最初にすること：URL をライブラリ識別子に変換する

あなたの権限範囲とルール

まず、自分がどの種類のクライアントかを確認する

ステップ 0：現在の状態を確認する

状態対応表

ステップ 1：アカウントの準備とライブラリのリンクをユーザーに依頼する

1. 登録してログインする

2. ユーザー名を設定する（初回ログイン時のみ）

3. 目的のライブラリのページを開き、「リンク」をクリックする

4. 認証情報を用意する（どちらか一方）

ステップ 2：クラウド MCP に接続する

方法 A：API キー（コマンドラインのあるクライアント、推奨）

方法 B：OAuth（ChatGPT、Claude.ai などのオンラインアプリケーション）

方法 C：CLI（任意）

ステップ 3：エンドツーエンドの検証

トラブルシューティング

完了したらユーザーに報告する

最後に 4 つの質問例を添える

関連ドキュメント

​AI Agent へ

​あなたのタスク

​最初にすること：URL をライブラリ識別子に変換する

​あなたの権限範囲とルール

​まず、自分がどの種類のクライアントかを確認する

​ステップ 0：現在の状態を確認する

​状態対応表

​ステップ 1：アカウントの準備とライブラリのリンクをユーザーに依頼する

​1. 登録してログインする

​2. ユーザー名を設定する（初回ログイン時のみ）

​3. 目的のライブラリのページを開き、「リンク」をクリックする

​4. 認証情報を用意する（どちらか一方）

​ステップ 2：クラウド MCP に接続する

​方法 A：API キー（コマンドラインのあるクライアント、推奨）

​方法 B：OAuth（ChatGPT、Claude.ai などのオンラインアプリケーション）

​方法 C：CLI（任意）

​ステップ 3：エンドツーエンドの検証

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

​完了したらユーザーに報告する

​最後に 4 つの質問例を添える

​関連ドキュメント

AI Agent へ

あなたのタスク

最初にすること：URL をライブラリ識別子に変換する

あなたの権限範囲とルール

まず、自分がどの種類のクライアントかを確認する

ステップ 0：現在の状態を確認する

状態対応表

ステップ 1：アカウントの準備とライブラリのリンクをユーザーに依頼する

1. 登録してログインする

2. ユーザー名を設定する（初回ログイン時のみ）

3. 目的のライブラリのページを開き、「リンク」をクリックする

4. 認証情報を用意する（どちらか一方）

ステップ 2：クラウド MCP に接続する

方法 A：API キー（コマンドラインのあるクライアント、推奨）

方法 B：OAuth（ChatGPT、Claude.ai などのオンラインアプリケーション）

方法 C：CLI（任意）

ステップ 3：エンドツーエンドの検証

トラブルシューティング

完了したらユーザーに報告する

最後に 4 つの質問例を添える

関連ドキュメント