> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> このページを AI Agent に渡せば、指定した Linkly AI クラウドライブラリへの接続を案内し、すぐに質問を始められる状態にしてくれます

このページは人間ではなく、主に **AI Agent** に向けて書かれています。

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

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

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

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

***

## AI Agent へ

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

### あなたのタスク

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

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

### 最初にすること：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                                     | 何も設定する必要はありません。下の近道をご覧ください                   |

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

***

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

まず接続がどこまで進んでいるかを見極めてから、どこから始めるかを決めます。確認するのは 3 点です。

**1. 現在のセッションに Linkly の検索ツールがあるか？どのサーバー由来か？**

クラウドゲートウェイは自分の名前を `linkly-ai-cloud` と名乗り、ローカルのデスクトップアプリは `linkly-ai` と名乗ります。多くのクライアントではサーバー名がツール名に反映されます（例：`mcp__linkly-ai-cloud__search`）。

**2. コマンドラインが使えるなら、設定済みのサーバーをそのまま一覧表示します：**

```bash theme={null}
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](https://linkly.ai)** にアクセスして登録またはログインします。Google / GitHub / Notion アカウントに対応しています。接続は無料アカウントのままで最後まで完了できます。

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

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

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

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

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

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

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

* **AI アシスタントにコマンドラインがある / 設定ファイルを編集できる場合**：**[https://linkly.ai/dashboard/integrations](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：**

```bash theme={null}
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`。フィールド名は各社のドキュメントに従ってください）：

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

クライアントごとのフィールドの違い（`url` / `httpUrl` / `serverUrl`）については[各 AI クライアント統合ガイド](/docs/ja/integration)をご覧ください。一部のクライアントは `${env:LINKLY_API_KEY}` 構文で環境変数から読み取れるため、キーを設定ファイルに平文で書かずに済みます。

**合格判定**：ハンドシェイクリクエストを直接送信して、サーバー側が正常であることを確認します：

```bash theme={null}
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 つ入力するだけです**：

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

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

アプリケーションごとの具体的な入口については [ChatGPT で使う](/docs/ja/integration/use-in-chatgpt) と [Claude で使う](/docs/ja/integration/use-in-claude) をご覧ください。

### 方法 C：CLI（任意）

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

```bash theme={null}
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")
```

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

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

最初の検索が空で返ってきても、すぐに設定ミスだと決めつけないでください。次の順で確認します：クエリが狭すぎないか → `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 つ書いてください。「このライブラリを要約して」のような、どこにでも当てはまる当たり障りのない内容は避けてください。良い質問は「これは確かにこのライブラリの話だ」と一目で伝わります。

***

## 関連ドキュメント

* [クラウドライブラリの使い方](/docs/ja/use-cloud-library) — 人間の読者に向けた完全な解説：作成、プッシュ、共有、上限
* [Agent 向けインストールガイド](/docs/ja/agent-setup) — 自分のパソコン上のファイルをインデックスしたい場合はこちら
* [ツール紹介](/docs/ja/tools-intro) — 7 つの検索ツールの全パラメータの説明
* [Skills の使い方](/docs/ja/use-skills) — AI アシスタントがこれらのツールをうまく組み合わせられるようにする