Skip to main content

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

Local Access

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

LAN Access

Other devices on the same network can also connect. Requires enabling LAN access and using an access token.Endpoint: http://{LAN IP}:60606/mcp

Remote Access (Public)

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
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 — 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 is usually the better fit; the Integration Overview compares all the paths.

HTTP MCP (Recommended)

Most AI assistants support the HTTP transport protocol. Connect directly to Linkly AI’s MCP endpoint without installing the CLI

Stdio MCP

Some AI assistants only support the stdio transport protocol and require Linkly AI CLI as a bridge
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.

​
Prerequisites

1

Install and launch Linkly AI Desktop

Go to linkly.ai to download and install the desktop application. After the first launch, complete the initialization wizard, and the app will automatically begin indexing your documents.
2

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
If you choose the Stdio MCP method, you also need to install Linkly AI CLI.

​
Usage

For AI assistants that support HTTP/StreamableHTTP transport protocol. No CLI installation needed — connect directly.
Run in your terminal:
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.

​
Stdio MCP

For AI assistants that support the stdio transport protocol. You need to install Linkly AI CLI first, then configure linkly mcp as the stdio bridge command in your AI assistant.
Run in your terminal:

​
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.
1

Enable LAN access

In Linkly AI Desktop, go to Settings → MCP, find the “LAN Access” section, and toggle it on.
2

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

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:
If you are using Linkly AI CLI, you can connect like this:
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.

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

Search my documents for content about XX

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

Please install the Agent Skill linkly-ai-skills and complete the LinklyAI tool integration...

​
Parameter Reference

The MCP service exposes nine 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
  • 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, the only tool that writes
Every tool except note_save 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.