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

# Integrate with AI Assistants via MCP

> Learn how to use Linkly AI MCP for greater flexibility and a more technical experience.

## Introduction to MCP

MCP (Model Context Protocol) is an open protocol that enables AI assistants to call external tools to obtain contextual information. Linkly AI Desktop has a built-in MCP service that starts automatically upon installation — no additional configuration required.

You only need to add Linkly AI's MCP endpoint to your AI assistant, and the AI can directly search, browse, and read your local documents.

## Three Access Modes

Linkly AI provides three MCP access modes for different scenarios:

<CardGroup cols={3}>
  <Card title="Local Access" icon="computer" iconType="duotone">
    Use directly in local AI tools on your machine — no extra configuration needed. Suitable for Claude Code, Cursor, and other local applications.

    Endpoint: `http://127.0.0.1:60606/mcp`
  </Card>

  <Card title="LAN Access" icon="wifi" iconType="duotone">
    Other devices on the same network can also connect. Requires enabling LAN access and using an access token.

    Endpoint: `http://{LAN IP}:60606/mcp`
  </Card>

  <Card title="Remote Access (Public)" icon="globe" iconType="duotone" href="/en/use-in-remote">
    Remotely access over the public internet via a tunnel. Suitable for online AI applications like ChatGPT and Claude.ai.

    Endpoint: `https://mcp.linkly.ai/mcp`
  </Card>
</CardGroup>

This page covers configuration for local access and LAN access. For remote access (public internet), see the [Remote Access Guide](/en/use-in-remote).

<CardGroup cols={2}>
  <Card title="HTTP MCP (Recommended)" icon="globe" iconType="duotone">
    Most AI assistants support the HTTP transport protocol. Connect directly to
    Linkly AI's MCP endpoint without installing the CLI
  </Card>

  <Card title="Stdio MCP" icon="terminal" iconType="duotone">
    Some AI assistants only support the stdio transport protocol and require
    Linkly AI CLI as a bridge
  </Card>
</CardGroup>

<Tip>
  If you're not sure which method to choose, go with HTTP MCP. You only need the
  Stdio method when your AI assistant explicitly does not support HTTP
  transport.
</Tip>

## Prerequisites

<Steps>
  <Step title="Install and launch Linkly AI Desktop">
    Go to [linkly.ai](https://linkly.ai/#download) to download and install the desktop application. After the first launch, complete the initialization wizard, and the app will automatically begin indexing your documents.
  </Step>

  <Step title="Confirm MCP service is running">
    Linkly AI Desktop automatically runs the MCP service upon startup. You can check the MCP service status and port number in the app settings.

    Default MCP endpoint: `http://127.0.0.1:60606/mcp`
  </Step>
</Steps>

<Note>
  If you choose the Stdio MCP method, you also need to [install Linkly AI
  CLI](./use-cli).
</Note>

## Usage

### HTTP MCP (Recommended)

For AI assistants that support HTTP/StreamableHTTP transport protocol. No CLI installation needed — connect directly.

<Tabs>
  <Tab title="Claude Code" icon="terminal">
    Run in your terminal:

    ```bash theme={null}
    claude mcp add --transport http linkly-ai http://127.0.0.1:60606/mcp
    ```
  </Tab>

  <Tab title="Cursor" icon="code">
    1. Open Settings → MCP Servers → Add Server
    2. Name: `linkly-ai`
    3. Type: `StreamableHTTP`
    4. URL: `http://127.0.0.1:60606/mcp`
  </Tab>

  <Tab title="Codex" icon="robot">
    Run in your terminal:

    ```bash theme={null}
    codex mcp add linkly-ai --url http://127.0.0.1:60606/mcp
    ```
  </Tab>

  <Tab title="Cherry Studio" icon="star">
    1. Open Settings → MCP Servers → Add
    2. Name: `linkly-ai`
    3. Type: `StreamableHTTP`
    4. URL: `http://127.0.0.1:60606/mcp`
  </Tab>
</Tabs>

<Tip>
  `60606` is the default port number for Linkly AI's MCP service. If you cannot
  connect, check the actual port number in the app settings.
</Tip>

### Stdio MCP

For AI assistants that support the stdio transport protocol. You need to [install Linkly AI CLI](./use-cli#installation) first, then configure `linkly mcp` as the stdio bridge command in your AI assistant.

<Tabs>
  <Tab title="Claude Code" icon="terminal">
    Run in your terminal:

    ```bash theme={null}
    claude mcp add linkly-ai -- linkly mcp
    ```
  </Tab>

  <Tab title="Codex" icon="robot">
    Run in your terminal:

    ```bash theme={null}
    codex mcp add linkly-ai -- linkly mcp
    ```
  </Tab>

  <Tab title="Cherry Studio" icon="star">
    1. Open Settings → MCP Servers → Add
    2. Name: `linkly-ai`
    3. Type: `stdio`
    4. Command: `linkly`
    5. Args: `mcp`
  </Tab>

  <Tab title="Other AI Assistants" icon="puzzle-piece">
    For other AI assistants that support stdio MCP, configure the following as the MCP server:

    * Command: `linkly`
    * Args: `mcp`

    The CLI will automatically discover the locally running Linkly AI Desktop and establish a connection.
  </Tab>
</Tabs>

### LAN Access

If you need to access Linkly AI from another device on the same network (such as another computer or n8n running on a NAS), you can enable LAN access mode.

<Steps>
  <Step title="Enable LAN access">
    In Linkly AI Desktop, go to **Settings → MCP**, find the "LAN Access" section, and toggle it on.
  </Step>

  <Step title="Get the LAN URL and access token">
    Once enabled, the interface will display:

    * **LAN URL**: similar to `http://192.168.x.x:60606/mcp`
    * **Access Token**: a random string

    Copy both pieces of information to the device you want to connect from.
  </Step>

  <Step title="Configure on other devices">
    When adding an MCP server in the AI tool on the other device, use the LAN URL as the endpoint and include the access token in the request header:

    ```
    Authorization: Bearer <your access token>
    ```

    If you are using Linkly AI CLI, you can connect like this:

    ```bash theme={null}
    linkly search "keyword" --endpoint http://192.168.x.x:60606/mcp --token <your access token>
    ```
  </Step>
</Steps>

<Warning>
  LAN access uses plaintext HTTP transmission and is only recommended on trusted
  networks such as your home network. Do not enable this feature on public Wi-Fi
  or untrusted network environments.
</Warning>

### Verify Integration

After configuration, you can send the following prompt in your AI assistant to verify:

<Prompt description="Search my documents for content about XX">
  Search my documents for content about project management
</Prompt>

If the integration is successful, the AI assistant will call Linkly AI's `search` tool and return relevant results from your local documents.

### Use with Skills

We strongly recommend [installing Linkly AI Skills](./use-skills) alongside MCP configuration. Skills teach the AI assistant how to efficiently use Linkly AI's tools, including when to search, when to browse outlines, when to read full text, and how to handle paginated reading of long documents.

<Prompt description="Please install the Agent Skill linkly-ai-skills and complete the LinklyAI tool integration...">
  Please install the Agent Skill linkly-ai-skills and complete the LinklyAI tool
  integration, refer to: [https://linkly.ai/docs/en/use-skills](https://linkly.ai/docs/en/use-skills)
</Prompt>

## Parameter Reference

The MCP service exposes seven tools, forming a progressive document access workflow:

* `search` — hybrid retrieval (BM25 + vector), the main entry point
* `outline` — document outlines
* `grep` — regex matching within a single document
* `read` — line-based document reading
* `list_libraries` — list available knowledge libraries
* `explore` — bird's-eye overview of a document collection
* `find_paths` — locate folder paths by keyword to feed `search`'s `path_glob`

Every successful response carries a UTC timestamp: a trailing `[meta] now=...` line in Markdown output, or a top-level `_meta.now` field in JSON output, useful for computing relative dates such as "last month". Error responses do not include this metadata.

For full parameter tables, response fields, response metadata format, and usage examples, see [Linkly AI MCP Tools Introduction](./tools-intro).