> ## 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.

# ZCode で Linkly AI を使う

> Linkly AI のローカルナレッジベースを ZCode に接続して、GLM 搭載のコーディングエージェントがあなたのプライベートドキュメントを検索・閲覧できるようにします

## 何ができるか

<AccordionGroup>
  <Accordion title="コードを書く前にエージェントに仕様を読ませる">
    Linkly AI の `search`
    ツールでアーキテクチャ決定記録や要件ドキュメントを探し、`read`
    で該当箇所を読み込みます。ZCode Agent
    は推測ではなく、あなたのプロジェクトの規約を踏まえてコードを書けるようになります。
  </Accordion>

  <Accordion title="Goal Mode と Subagents を実際の資料に基づかせる">
    ZCode は Goal Mode と Subagents
    によって長時間のタスクを自律的に実行します。Linkly AI
    を接続しておけば、その実行中に必要なローカル資料を随時取得できるため、複数ステップのリファクタリングや移行作業も実際のドキュメントに沿った内容になります。
  </Accordion>

  <Accordion title="すべてのワークスペースで 1 つのナレッジベースを共有">
    Linkly AI をユーザースコープで一度設定すれば、すべての ZCode
    ワークスペースから同じローカルドキュメントにアクセスできます。添付ファイルの再アップロードも、プロジェクトごとの設定も不要です。
  </Accordion>
</AccordionGroup>

## 前提条件

* [ZCode](https://zcode.z.ai) がインストール済みであること
* Linkly AI Desktop が起動しており、MCP サービスが実行中であること

## 設定手順

<Tabs>
  <Tab title="ローカル MCP HTTP（推奨）" icon="globe">
    <Steps>
      <Step title="MCP Servers ページを開く">
        ZCode の **Settings** を開き、**MCP Servers** ページに移動して **New MCP
        Server** をクリックします。
      </Step>

      <Step title="スコープを選択">
        すべてのワークスペースで Linkly AI を使うには **User**
        を、現在のプロジェクトだけに限定するには **Workspace** を選択します。
      </Step>

      <Step title="設定を入力して追加">
        以下の情報を入力します：

        * **Type**: `HTTP`
        * **Name**: `linkly-ai`
        * **URL**: `http://127.0.0.1:60606/mcp`

        **Add** をクリックして追加を完了し、サーバー一覧で `linkly-ai`
        の横のトグルがオンになっていることを確認してください。
      </Step>
    </Steps>
  </Tab>

  <Tab title="リモート MCP" icon="cloud">
    先に[リモートアクセス設定](/docs/ja/use-in-remote)を完了し、デスクトップトンネルが
    <Badge stroke color="green">● 接続済み</Badge> と表示されていることを確認してください。

    <Steps>
      <Step title="MCP Servers ページを開く">
        ZCode の **Settings** を開き、**MCP Servers** ページに移動して **New MCP
        Server** をクリックします。
      </Step>

      <Step title="リモート設定を入力">
        以下の情報を入力します：

        * **Type**: `HTTP`
        * **Name**: `linkly-ai`
        * **URL**: `https://mcp.linkly.ai/mcp`
      </Step>

      <Step title="認証ヘッダーを追加">
        **Request headers (optional)** を展開して、以下を追加します：

        * **Key**: `Authorization`
        * **Value**: `Bearer <あなたの API Key>`

        API Key は [Linkly AI
        ダッシュボード](https://linkly.ai/dashboard/integrations)
        で作成でき、`lkai_` で始まります。**Add** をクリックして追加を完了します。
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI Stdio（代替手段）" icon="terminal">
    先に [Linkly AI CLI をインストール](/docs/ja/use-cli)してから、ZCode
    の設定ファイルを直接編集します：

    * ユーザースコープ: `~/.zcode/cli/config.json`
    * ワークスペーススコープ: `<プロジェクトルート>/.zcode/config.json`

    ```json theme={null}
    {
      "mcp": {
        "servers": {
          "linkly-ai": {
            "command": "linkly",
            "args": ["mcp"],
            "env": {}
          }
        }
      }
    }
    ```

    <Note>
      2 つのファイルは同じ名前ですが、階層が異なります。ユーザー設定は
      `.zcode/cli/` 配下に、ワークスペース設定は `.zcode/`
      直下にあります。間違ったほうを編集してしまうのが最もよくあるミスです。
    </Note>

    同じ設定は UI からも行えます。**MCP Servers** ページで **New MCP Server**
    をクリックし、**Type** を `stdio` のままにして、**Command** に `linkly`、**Args**
    に `mcp` を設定します。
  </Tab>
</Tabs>

## Skills のインストール

ZCode は Agent Skills に対応しているため、Linkly AI Skills
をインストールしてエージェントにこれらのツールの効率的な使い方を教えることもできます：

```bash theme={null}
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.zcode/skills/linkly-ai
```

**Settings → Skills** に戻って **Refresh** をクリックし、入力欄に `$` を入力して
`linkly-ai` を選択すると呼び出せます。

<Tip>
  その他のインストール方法や Skills の仕組みについては [Skills
  の使い方](/docs/ja/use-skills)をご覧ください。
</Tip>

## 使い始める

設定が完了したら、ZCode
で直接質問するだけで、エージェントが自動的に Linkly AI
のツールを呼び出します。例：

* 「このモジュールのアーキテクチャ決定についてドキュメントを検索して」
* 「API 仕様書を読んで、この実装が仕様と合っているか確認して」

## よくある質問

<AccordionGroup>
  <Accordion title=".agents/mcp.json に設定したサーバーが消えた">
    同じスコープ内では `.zcode` の設定が優先されます。ZCode が `.zcode`
    設定ファイルから MCP サーバーを 1 つでも読み込むと、そのスコープの
    `.agents/mcp.json` はマージされずに完全に無視されます。該当のサーバーを
    `.zcode` 設定ファイルに移動してください。
  </Accordion>

  <Accordion title="HTTP 方式で接続に失敗する">
    Linkly AI Desktop が起動しており、MCP
    サービスが実行中かどうかを確認してください。ターミナルで `curl
            http://127.0.0.1:60606/mcp` を実行して接続をテストできます。
  </Accordion>

  <Accordion title="サーバーは一覧にあるがツールが使えない">
    無効化されたサーバーは設定オブジェクト内で `"enable": false`
    と記録されます。**MCP Servers**
    ページからトグルをオンに戻すか、設定ファイルからそのフィールドを削除してください。
  </Accordion>

  <Accordion title="Stdio 方式で linkly コマンドが見つからないと表示される">
    [Linkly AI CLI をインストール](/docs/ja/use-cli)済みで、`linkly` コマンドが PATH
    から利用できることを確認してください。`linkly --version` で検証できます。
  </Accordion>
</AccordionGroup>