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

# Remote Access to Linkly AI

> Securely access your local knowledge base from online AI applications like ChatGPT and Claude.ai using a public tunnel plus OAuth authorization. This is a Pro-only feature.

## What Is Remote Access

Linkly AI runs on your local machine, while online AI applications like ChatGPT and Claude.ai run in the cloud — they cannot directly reach the MCP server for your local knowledge base.

**Remote Access** establishes a secure tunnel between your desktop app and the cloud, relaying requests over the public internet:

1. The desktop app opens a WebSocket tunnel connection to `mcp.linkly.ai`
2. After OAuth authorization, the online AI application sends MCP requests to `https://mcp.linkly.ai/mcp`
3. The cloud service forwards those requests through the tunnel to your desktop app, which executes them and returns the results

Your document data always stays on your local machine. The tunnel only forwards MCP requests and responses — no document content is stored.

<Warning>
  **Remote Access is a Pro-only feature.** Free accounts can see and click **Connect Tunnel**, but the connection is rejected by the server: the status becomes **Upgrade Required** with the message `Remote access requires a Pro subscription.`

  If all you want is for a cloud AI to read **one particular set** of material, you don't need to upgrade — a [Cloud Library](/docs/en/use-cloud-library) works on free accounts, and it doesn't require your computer to be on. See [Which one should I use](#which-one-should-i-use) below for the difference.
</Warning>

<Note>`mcp.linkly.ai` is a cloud MCP relay service maintained by Linkly AI. Data passes through it anonymously, and Linkly AI only records usage counts for display purposes.</Note>

## Which one should I use

Remote Access and Cloud Libraries both let a cloud-hosted AI read your material, but they solve problems in different directions:

| Aspect                  | Remote Access (tunnel)                          | [Cloud Library](/docs/en/use-cloud-library) |
| ----------------------- | ----------------------------------------------- | -------------------------------------- |
| What it can read        | **Every** indexed document on your computer     | Only the libraries you **push** up     |
| Computer must be on?    | Yes, and the tunnel must stay connected         | No — it works with your computer off   |
| Where the content lives | Only on your machine; the tunnel stores nothing | A copy lives in the cloud              |
| Can it be shared?       | No                                              | Yes (by invitation or publicly)        |
| Plan                    | **Pro**                                         | Free                                   |

You can use both at once; they don't conflict.

<Tip>There's a third case that often gets overlooked: if your AI client is **installed on the same computer** (Claude Code, Cursor, Cherry Studio and so on), you don't need a tunnel at all — connect directly to `http://127.0.0.1:60606/mcp` on your machine. It's free and faster. See [Using MCP](/docs/en/use-mcp).</Tip>

## Configuration Steps

<Steps>
  <Step title="Sign in to Linkly AI and upgrade to Pro">
    In the desktop app, go to **Settings → Account** and click **Sign In**. Once you authorize in the browser you're brought back to the app automatically. **Your API key is fetched automatically after you sign in** — no copying and pasting from the dashboard required.

    Remote Access requires a Pro subscription, which you can upgrade to on the [pricing page](https://linkly.ai/pricing).

    <Tip>
      If you have a special need — say you want to use a specific key — the escape hatch is still there: **Optional: connect your account by setting an API key manually** at the bottom of **Settings → Account**. Keys start with `lkai_` and are generated in the [dashboard](https://linkly.ai/dashboard).
    </Tip>
  </Step>

  <Step title="Connect the tunnel in the desktop app">
    Go to **Settings → MCP**, find the **Remote Access** section, and flip the switch on its right to expand it:

    1. If you're not signed in yet, it says `Sign in to your account first to enable remote access.` — click **Open Account settings** and finish the previous step
    2. Click the **Connect Tunnel** button
    3. Wait for the status to show <Badge stroke color="green">● Connected</Badge>; the **Public MCP Endpoint** appears below it
  </Step>

  <Step title="Add the MCP service in your AI application">
    In AI applications that support MCP (such as ChatGPT or Claude.ai), add the following MCP endpoint:

    ```
    https://mcp.linkly.ai/mcp
    ```

    The first time you add it, an OAuth authorization flow is triggered. Follow the prompts to sign in and authorize in your browser.

    For per-application setup instructions, see the [Integration Overview](/docs/en/integration).
  </Step>
</Steps>

## Connection statuses

The status label in the **Remote Access** section has these values. Reading it tells you where the problem is:

| Status                       | Meaning                                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Disconnected**             | You haven't connected yet, or you disconnected deliberately                                                        |
| **Connecting**               | The tunnel is being established                                                                                    |
| **Connected**                | Working normally; the public MCP endpoint is shown below                                                           |
| **Reconnecting (attempt N)** | Network instability dropped the connection; reconnecting automatically (exponential backoff, up to 10 attempts)    |
| **Auth Error**               | Something's wrong with the credentials — most likely you're not signed in, or the key was revoked in the dashboard |
| **Upgrade Required**         | The account isn't Pro. Tunnels are closed to free accounts; an upgrade link appears below                          |
| **Error**                    | Any other error; the specific reason is shown next to it                                                           |

## OAuth Authorization Explained

When online AI applications like ChatGPT and Claude.ai connect to a remote MCP service for the first time, an OAuth 2.1 authorization flow is automatically triggered:

1. The AI application detects that the MCP endpoint requires authorization
2. It automatically redirects to the linkly.ai sign-in page
3. After you sign in and confirm authorization, the AI application receives an access token
4. Subsequent requests carry the token automatically — no need to re-authorize

<Tip>If you are already signed in to linkly.ai in your browser, the authorization process will be faster.</Tip>

## Security Considerations

* **Protect your credentials**: Tunnel credentials are the key to your local knowledge base — don't share them. If you suspect they've been compromised, revoke and regenerate the API key in the [dashboard](https://linkly.ai/dashboard)
* **HTTPS transmission**: The remote tunnel uses HTTPS/WSS encryption end to end
* **Revoke anytime**: You can disconnect the tunnel from the desktop app at any time. Revoking the API key in the dashboard prevents new connections and reconnections, but won't immediately terminate an already-established tunnel session
* **Data never leaves your machine**: Your document data always stays on your local computer — the tunnel only forwards MCP tool call requests and responses

## FAQ

<AccordionGroup>
  <Accordion title="Status shows Upgrade Required">
    This means the current account isn't Pro — the server rejects the tunnel handshake outright (HTTP 402).

    There are two ways forward:

    * **Upgrade to Pro**: click **Upgrade to Pro →** below the status, or go straight to the [pricing page](https://linkly.ai/pricing)
    * **Switch to a Cloud Library**: [push](/docs/en/use-cloud-library) the material you need remote access to into the cloud. It works on free accounts, and it's searchable with your computer off

    <Note>
      One pitfall worth knowing: even when you're using a Cloud Library, **you must name the library explicitly at query time** (`library="cloud://owner/slug"`). If the library parameter is omitted, the request routes back to your own machine by default — that is, through the tunnel — and free accounts get the Pro prompt on that path.
    </Note>
  </Accordion>

  <Accordion title="Status shows Auth Error">
    Work through this in order:

    1. Confirm that **Settings → Account** shows **Connected to Linkly AI Cloud**. If you're not signed in, the Remote Access section says `Sign in to your account first to enable remote access.` outright
    2. If you entered an API key manually, check that it was pasted in full (it starts with `lkai_`) and that it hasn't been revoked in the dashboard
    3. Generate a new API key in the dashboard, or simply sign out and sign in again so the app fetches one automatically
  </Accordion>

  <Accordion title="Desktop is offline, remote calls return an error">
    The remote MCP service requires the desktop app to be running with the tunnel connected. If the desktop app is closed or the tunnel drops, remote calls immediately return a 503 error.

    Make sure:

    * Linkly AI Desktop is running
    * The MCP server is running (**Settings → MCP** shows **Running** at the top)
    * The tunnel status is <Badge stroke color="green">● Connected</Badge>

    If what you actually want is to search with your computer switched off, you need a [Cloud Library](/docs/en/use-cloud-library), not a tunnel.
  </Accordion>

  <Accordion title="The tunnel keeps dropping">
    The tunnel reconnects automatically (up to 10 retries with exponential backoff), showing **Reconnecting (attempt N)** while it does. If it drops frequently, check:

    * Whether your network connection is stable
    * Whether the credentials are still valid

    If it keeps dropping, try **Disconnect Tunnel** and then reconnect manually.
  </Accordion>

  <Accordion title="OAuth authorization failed">
    If authorization fails after adding MCP in ChatGPT or Claude.ai:

    1. Make sure the desktop tunnel is connected
    2. Try signing in to linkly.ai in your browser first
    3. Re-add the MCP server in the AI application

    If the issue persists, remove the already-added MCP server and add it again.
  </Accordion>
</AccordionGroup>

## Further reading

* [Integration Overview](/docs/en/integration) — the four connection paths and how to choose
* [Using Cloud Libraries](/docs/en/use-cloud-library) — the free path that doesn't need your computer on
* [Using MCP](/docs/en/use-mcp) — local and LAN modes
* [Linkly AI Account](/docs/en/linkly-account) — sign-in, Pro, and API keys