Using Linkly AI in ZCode

What You Can Do

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.

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.

Prerequisites

ZCode installed
Linkly AI Desktop running with the MCP service active

Configuration Steps

Local MCP HTTP (Recommended)
Remote MCP
CLI Stdio (Fallback)

Open the MCP Servers page

Open ZCode Settings, then go to the MCP Servers page and click New MCP Server.

Choose the scope

Pick User to make Linkly AI available in every workspace, or Workspace to limit it to the current project.

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.

Complete remote access configuration first, with the desktop tunnel showing ● Connected.

Open the MCP Servers page

Open ZCode Settings, then go to the MCP Servers page and click New MCP Server.

Fill in the remote configuration

Fill in the following:

Type: HTTP
Name: linkly-ai
URL: https://mcp.linkly.ai/mcp

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 and starts with lkai_. Click Add to finish.

Install Linkly AI CLI first, then edit ZCode’s configuration file directly:

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

{
  "mcp": {
    "servers": {
      "linkly-ai": {
        "command": "linkly",
        "args": ["mcp"],
        "env": {}
      }
    }
  }
}

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.

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.

Install Skills

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

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.

See Using Skills for more installation methods and how Skills work.

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

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.

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.

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.

Stdio method says it cannot find the linkly command

Make sure you have installed Linkly AI CLI and that the linkly command is available in your PATH. Verify with linkly --version.

AI Assistants

Coding AI Agents

AI Workflows

Other

Using Linkly AI in ZCode

What You Can Do

Prerequisites

Configuration Steps

Install Skills

Getting Started

FAQ

​What You Can Do

​Prerequisites

​Configuration Steps

​Install Skills

​Getting Started

​FAQ

What You Can Do

Prerequisites

Configuration Steps

Install Skills

Getting Started

FAQ