> ## 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="/docs/en/use-in-remote">
    Remotely access over the public internet via a tunnel. Suitable for online AI applications like ChatGPT and Claude.ai. **Pro only**.

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

This page covers configuration for local access and LAN access, both of which are free. For remote access (public internet), see the [Remote Access Guide](/docs/en/use-in-remote) — that one is Pro only. If all you want is for a cloud AI to read one particular set of material, the free [Cloud Library](/docs/en/use-cloud-library) is usually the better fit; the [Integration Overview](/docs/en/integration) compares all the paths.

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

### Reload after configuring

Once the MCP config is written, **the new tools will not show up in the conversation you already have open** — the vast majority of AI clients read the tool list once, at the moment the session starts. This is the client's loading mechanism, not a configuration error.

Two options; try the first one first:

1. **Start a new conversation** (for command-line tools, quit and open a new session). A conversation that is already running keeps the tool list it started with; a new one picks up the latest.
2. **Quit the client completely, then reopen it.** Use this when the first option doesn't help — and note that closing the window is not quitting: on macOS press `Cmd + Q` or choose Quit from the menu bar, on Windows check that it also exited from the tray.

Once you've reloaded, come back to the verification step below. If nothing is missing and only one particular tool won't work, see *When a newly shipped tool doesn't show up* further down.

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

### When a newly shipped tool doesn't show up

We ship new MCP tools from time to time. Most AI clients fetch the tool list once, at the moment the session starts, and never refresh it on their own, so a newly shipped tool simply will not appear until the client fetches the list again.

If a tool documented here is missing from your client:

1. Refresh the connection in your client — in ChatGPT: **Settings → Connectors → your connector → Refresh**.
2. If it still doesn't appear, remove the connection and add it again.
3. Start a new conversation. A conversation that is already running keeps the tool list it started with.

### 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 nine tools (eleven on the cloud gateway, which adds `library_search` and `library_link`), 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`
* `list` — list the entries inside a container: a disk directory (`folder`), a library (`library`), or your notes (`notes`)
* `note_save` — create or edit a note, **writes** (the only writer on a local connection)
* `library_search` — search the cloud library catalog, including libraries not linked yet (cloud gateway only)
* `library_link` — link a cloud library so it becomes searchable, or unlink one you named with `action: "unlink"` (cloud gateway only, **writes**)

Every tool except `note_save` (and `library_link` on the cloud gateway) is read-only and will never modify your documents.

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