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

# Using Linkly AI in ZCode

> Connect your Linkly AI local knowledge base to ZCode, letting the GLM-powered coding agent search and read your private documents

## What You Can Do

<AccordionGroup>
  <Accordion title="Let the agent read the specs before it writes code">
    Use Linkly AI's `search` tool to find architecture decision records and
    requirement documents, then `read` the relevant sections. ZCode Agent writes
    code with your project conventions in hand instead of guessing at them.
  </Accordion>

  <Accordion title="Ground Goal Mode and Subagents in real materials">
    ZCode runs long-horizon tasks autonomously through Goal Mode and Subagents.
    With Linkly AI connected, those runs can retrieve local materials on demand
    — so a multi-step refactor or migration stays anchored to your actual
    documentation.
  </Accordion>

  <Accordion title="Share one knowledge base across every workspace">
    Configure Linkly AI at the user scope once, and every ZCode workspace can
    reach the same local documents. No re-uploading attachments, no per-project
    setup.
  </Accordion>
</AccordionGroup>

## Prerequisites

* [ZCode](https://zcode.z.ai) installed
* Linkly AI Desktop running with the MCP service active

## Configuration Steps

<Tabs>
  <Tab title="Local MCP HTTP (Recommended)" icon="globe">
    <Steps>
      <Step title="Open the MCP Servers page">
        Open ZCode **Settings**, then go to the **MCP Servers** page and click
        **New MCP Server**.
      </Step>

      <Step title="Choose the scope">
        Pick **User** to make Linkly AI available in every workspace, or
        **Workspace** to limit it to the current project.
      </Step>

      <Step title="Fill in the configuration and add">
        Fill in the following:

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

        Click **Add** to finish, then confirm the toggle next to `linkly-ai` is
        on in the server list.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Remote MCP" icon="cloud">
    Complete [remote access configuration](/docs/en/use-in-remote) first, with the
    desktop tunnel showing <Badge stroke color="green">● Connected</Badge>.

    <Steps>
      <Step title="Open the MCP Servers page">
        Open ZCode **Settings**, then go to the **MCP Servers** page and click
        **New MCP Server**.
      </Step>

      <Step title="Fill in the remote configuration">
        Fill in the following:

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

      <Step title="Add the authentication header">
        Expand **Request headers (optional)** and add:

        * **Key**: `Authorization`
        * **Value**: `Bearer <your API Key>`

        Your API Key is created on the
        [Linkly AI dashboard](https://linkly.ai/dashboard/integrations) and
        starts with `lkai_`. Click **Add** to finish.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI Stdio (Fallback)" icon="terminal">
    [Install Linkly AI CLI](/docs/en/use-cli) first, then edit ZCode's configuration
    file directly:

    * User scope: `~/.zcode/cli/config.json`
    * Workspace scope: `<project root>/.zcode/config.json`

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

    <Note>
      The two files share the same name but sit at different levels — the user
      config lives under `.zcode/cli/`, while the workspace config sits directly
      under `.zcode/`. Editing the wrong one is the most common mistake here.
    </Note>

    You can achieve the same result from the UI: on the **MCP Servers** page
    click **New MCP Server**, keep **Type** as `stdio`, set **Command** to
    `linkly` and **Args** to `mcp`.
  </Tab>
</Tabs>

## Install Skills

ZCode supports Agent Skills, so you can also install Linkly AI Skills to teach
the agent how to use these tools efficiently:

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

Go back to **Settings → Skills** and click **Refresh**, then type `$` in the
input box and select `linkly-ai` to invoke it.

<Tip>
  See [Using Skills](/docs/en/use-skills) for more installation methods and how
  Skills work.
</Tip>

## Getting Started

Once configured, ask questions directly in ZCode and the agent will call Linkly
AI tools on its own. For example:

* "Search my documents for the architecture decisions on this module"
* "Read my API specification and check whether this implementation matches it"

## FAQ

<AccordionGroup>
  <Accordion title="Servers configured in .agents/mcp.json disappeared">
    Within the same scope, `.zcode` configuration takes priority: as soon as
    ZCode reads any MCP server from the `.zcode` config file, the
    `.agents/mcp.json` in that scope is skipped entirely rather than merged.
    Move those servers into the `.zcode` config file.
  </Accordion>

  <Accordion title="HTTP method connection failed">
    Check whether Linkly AI Desktop is running and whether the MCP service is
    active. You can run `curl http://127.0.0.1:60606/mcp` in a terminal to test
    connectivity.
  </Accordion>

  <Accordion title="The server is listed but its tools are unavailable">
    A disabled server is marked with `"enable": false` in the configuration
    object. Toggle it back on from the **MCP Servers** page, or remove that
    field from the config file.
  </Accordion>

  <Accordion title="Stdio method says it cannot find the linkly command">
    Make sure you have [installed Linkly AI CLI](/docs/en/use-cli) and that the
    `linkly` command is available in your PATH. Verify with `linkly --version`.
  </Accordion>
</AccordionGroup>