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

# Cloud Library Setup for Agents

> Hand this page to your AI agent and let it connect you to a Linkly AI cloud library so you can start asking questions right away

This page is written primarily for **AI agents**, not for people.

On any cloud library page, click **Use in AI** and copy the line from the dialog over to your AI assistant. You can also kick it off yourself — take the line below and swap in the address of the library you want:

```
Please read https://linkly.ai/docs/en/library-setup.md and help me connect to this library: https://linkly.ai/blueeon/linkly-init-example
```

You are welcome to read on yourself — this is also a complete connection guide. It is just written more bluntly than most, with a heavy emphasis on how to tell whether each step actually worked. If your AI assistant cannot access the web, use **Copy page** in the top-right corner to grab this page as raw Markdown and paste it in directly.

<Note>
  **This route does not require the Linkly AI desktop app.** Cloud libraries are
  hosted on our servers and stay online around the clock, so any MCP-capable AI
  tool can search them directly. If what you want to index are the files on your
  own computer, that is a different job — see [Setup Guide for
  Agents](/docs/en/agent-setup).
</Note>

***

## To the AI agent

Everything below is addressed to you. Read all of it before you start.

### Your task

Get the user asking questions against a specific cloud library. You are done when:

1. The client you are running in is connected to the Linkly AI cloud gateway (`mcp.linkly.ai`);
2. You can genuinely retrieve content from that library using `library="cloud://<owner>/<slug>"`;
3. You have walked the user through their first real question and answered it from real documents.

### First: turn the web address into a library identifier

What the user hands you is the library's **web address**, in this form:

```
https://linkly.ai/blueeon/linkly-init-example
```

But the `library` parameter on the retrieval tools wants a **library identifier**. The two are the same thing spelled differently — replace the `https://linkly.ai/` prefix with `cloud://` and keep the `<owner>/<slug>` segments exactly as they are:

| What the user gives you (web address)           | What you pass to the tools (library identifier) |
| ----------------------------------------------- | ----------------------------------------------- |
| `https://linkly.ai/blueeon/linkly-init-example` | `cloud://blueeon/linkly-init-example`           |
| `linkly.ai/7running/basedge`                    | `cloud://7running/basedge`                      |

**Do not pass the web address straight into the `library` parameter** — it will be rejected. Every `cloud://…` in the examples below is already the converted form.

If the address carries extra path segments (such as `/settings`) or query parameters, keep only the `<owner>/<slug>` pair. When in doubt, connect MCP first and call `list_libraries` once — the response carries the exact identifiers.

### Your boundaries and rules

Some things you can do yourself; others must be handed to the user. **Do not overstep, and do not assume an outcome on the user's behalf:**

* **You can do yourself**: probe the current connection state, write the MCP configuration, send handshake requests, call the retrieval tools, interpret errors, report back. For anything that writes configuration, **show the command and get consent first**.
* **The user must do**: sign up for or sign in to linkly.ai, set a username, click **Link** on the library page, generate an API key in the dashboard, complete OAuth authorization in the browser. These are browser actions — you cannot do them.

And a few hard rules. **Every one of them maps to a failure that really happens:**

* **Do not overwrite the user's existing local MCP configuration.** Users who have installed the desktop app usually already have a server named `linkly-ai` pointing at `http://127.0.0.1:60606/mcp`. The cloud gateway is an **additional** entry, and it must be named `linkly-ai-cloud`. Writing under the same name silently replaces the local one — the user suddenly can't find documents on their own computer, and no error is raised anywhere.
* **The local connection cannot reach cloud libraries.** A `cloud://` reference on the `linkly-ai` path (local / LAN) **is rejected every time**. Don't retry a cloud library over the local connection; that is a boundary of the link, not an intermittent fault.
* **Every search must pass `library` explicitly.** Omit the `library` parameter and the gateway routes to the user's own machine by default (through the desktop tunnel), and the tunnel is a Pro feature — free users get an error straight away. Cloud libraries are **never** pulled in implicitly.
* **One library per call.** Cloud libraries are not merged across a single search; to query two libraries, call twice.
* **Probe before you act.** The user may be half set up already — do not blindly run through every step from the top.
* **When the user must act, say everything at once, then stop and wait for a single reply.** Do not split one task into several rounds of back-and-forth confirmation.
* **Never overstate progress.** If it is not verified, it is not done. Say exactly where you are stuck and what you tried.

### First, work out which kind of client you are

Which route you take depends on whether you can write configuration and run commands:

| You are                                                                                       | Route to take                                                       |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| A client with a shell, or able to edit config files (Claude Code, Codex, Cursor, Gemini CLI…) | **The API key route** (Step 2, Option A)                            |
| An online application with no shell (ChatGPT, Claude.ai…)                                     | **The OAuth route** (Step 2, Option B) — one URL is all you fill in |
| The Chat built into the Linkly AI desktop app                                                 | Nothing to configure — see the shortcut below                       |

<Tip>
  **Shortcut**: if the user already has the Linkly AI desktop app, they can
  mention a linked cloud library with `@` right inside the app's Chat, with no
  MCP configuration at all. That route only needs Step 1.
</Tip>

***

## Step 0: Probe the current state

Work out how far the chain already goes before deciding where to start. Three things:

**1. Does your current session have Linkly retrieval tools, and which server do they come from?**

The cloud gateway identifies itself as `linkly-ai-cloud`; the local desktop app identifies itself as `linkly-ai`. Most clients put the server name into the tool name (for example `mcp__linkly-ai-cloud__search`).

**2. If you have a shell, list the configured servers directly:**

```bash theme={null}
claude mcp list        # Claude Code
codex mcp list         # Codex
```

Look at each URL: one starting with `127.0.0.1` is local, `mcp.linkly.ai` is the cloud.

**3. Does the user have a linkly.ai account, and have they linked this library?**

You cannot check this — just ask the user.

### State table

**Match top to bottom and follow the first row that hits**:

| Probe result                                                   | Meaning                                     | Start at                                               |
| -------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------ |
| `linkly-ai-cloud` present and it can list libraries            | The cloud chain is up                       | Go straight to Step 3 verification                     |
| `linkly-ai-cloud` present, but the target library isn't listed | Chain is up, library not linked yet         | Step 1 (the "link the library" item only)              |
| Only `linkly-ai` (local)                                       | Desktop app installed, cloud not configured | Step 1. **Keep the local entry — do not overwrite it** |
| No Linkly server at all                                        | Brand-new user                              | Step 1                                                 |

***

## Step 1: Ask the user to prepare an account and link the library

This step happens entirely in the browser — you cannot do any of it. **Give the user the full sequence below in one message, then stop and wait for a single reply.** Do not walk through it item by item across multiple rounds.

Here is what to relay to the user (rephrase in your own voice if you like, but cover all four parts):

### 1. Sign up and sign in

Go to **[https://linkly.ai](https://linkly.ai)** to sign up or sign in — Google, GitHub, and Notion accounts are supported. A free account is enough for the whole setup.

### 2. Set a username (first sign-in only)

A cloud library's address looks like `linkly.ai/<username>/<slug>`, so the account needs a unique username. Set it once in the **Dashboard** when prompted; you never have to think about it again.

### 3. Open the library page and click Link

Visit the library's web address (for example `https://linkly.ai/blueeon/linkly-init-example`) and click the **Link** button in the top-right corner. It worked when the button turns into **Linked** and the status badge reads **Connected**.

<Warning>
  **Even a library the user created themselves has to be linked once.** What MCP
  can search is decided by the link relationship, not by ownership — an unlinked
  library never shows up in `list_libraries`, not even your own.
</Warning>

A free account gets **one link slot**. If another library is already linked, the user has to unlink that one first, or upgrade to Pro (99 slots). The quota dialog on the library page has the upgrade link.

### 4. Get a credential (pick one)

* **Your AI assistant has a shell or can edit config files**: go to **[https://linkly.ai/dashboard/integrations](https://linkly.ai/dashboard/integrations)**, click to create a new key in the **API Keys** section, and copy it (it starts with `lkai_`). This key is equivalent to account credentials — it is for the user's own AI tools only and must not be shared.
* **You are running inside an online application such as ChatGPT or Claude.ai**: no API key needed. Skip this item; authorization happens in the browser later.

***

**Acceptance check**: the user replies that the button on the library page now reads **Linked**. If they are taking the API key route, also confirm they have a key starting with `lkai_`.

***

## Step 2: Connect to the cloud MCP

The endpoint is fixed:

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

**Always name the server `linkly-ai-cloud`**, never `linkly-ai` — that name belongs to the local desktop app. Reusing it overwrites the user's existing local configuration, and an agent with the Linkly Skills installed will mistake the connection for a local one and refuse every `cloud://` request.

### Option A: API key (clients with a shell, recommended)

Show the user the command first and explain that it writes the key into a local configuration file. **Get consent before running it.**

**Claude Code:**

```bash theme={null}
claude mcp add --transport http linkly-ai-cloud https://mcp.linkly.ai/mcp \
  --header "Authorization: Bearer lkai_YOUR_KEY"
```

**Other clients that support HTTP MCP** — add a block to their own configuration file (Cursor uses `mcp.json`, Gemini CLI uses `~/.gemini/settings.json`; field names follow each vendor's docs):

```json theme={null}
{
  "mcpServers": {
    "linkly-ai-cloud": {
      "url": "https://mcp.linkly.ai/mcp",
      "headers": {
        "Authorization": "Bearer lkai_YOUR_KEY"
      }
    }
  }
}
```

For how the field name varies per client (`url` / `httpUrl` / `serverUrl`), see the [Integration Guide](/docs/en/integration). Some clients support `${env:LINKLY_API_KEY}` syntax to read from an environment variable, which keeps the key out of the config file in plain text.

**Acceptance check**: send a handshake request directly to confirm the server is healthy:

```bash theme={null}
curl -sf --max-time 10 -X POST https://mcp.linkly.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer lkai_YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'
```

A response containing `"serverInfo":{"name":"linkly-ai-cloud"` means the credential is valid and the chain is healthy. A **401** means the key is wrong or has been revoked — have the user generate a new one in the dashboard.

### Option B: OAuth (ChatGPT, Claude.ai, and other online applications)

These applications can't send custom request headers, so they authorize over OAuth — which is actually simpler: **one URL is all you fill in.**

<Steps>
  <Step title="Add an MCP connector">
    In the application's connector / MCP settings, add a new server. Name it
    `linkly-ai-cloud` and set the URL to `https://mcp.linkly.ai/mcp`.
  </Step>

  <Step title="Complete authorization in the browser">
    After saving, the application redirects to the linkly.ai authorization page.
    Once the user signs in and approves, the application receives an access
    token and sends it automatically from then on — no repeat authorization
    needed.
  </Step>
</Steps>

For where these settings live in each application, see [Using Linkly AI in ChatGPT](/docs/en/integration/use-in-chatgpt) and [Using Linkly AI in Claude](/docs/en/integration/use-in-claude).

### Option C: CLI (optional)

If the user has the Linkly AI CLI installed, the command line works too:

```bash theme={null}
linkly auth set-key lkai_YOUR_KEY
linkly search "your query" --remote --library "cloud://blueeon/linkly-init-example"
```

`--remote` is the only CLI mode that can reach cloud libraries; leave it out and the search stays local.

***

**A newly configured MCP server usually does not become available in the current session** — most clients need to reload the config or start a new session. Tell the user plainly: "the configuration is written, reload and try again." **Do not keep probing the current session to see whether the tools have appeared.**

***

## Step 3: End-to-end verification

Once the tools are available (the user may need to restart the session), do two things to confirm the whole chain really works.

**1. Confirm the library is in the list:**

Call `list_libraries`. The target library should appear in the results, like this:

```
- **cloud://blueeon/linkly-init-example** (305 docs) [yours]: Documents from the Linkly AI starter pack
```

If it isn't there, the link didn't go through — go back to Step 1, item 3.

**2. Run one real search:**

```
search(query="…", library="cloud://blueeon/linkly-init-example")
```

**Success means**: real document entries came back.

<Warning>
  The `library` parameter is required **every single time**, and it must be the
  full two-part `cloud://<owner>/<slug>` form — a single segment (such as
  `cloud://linkly-init-example`) is rejected. Omit `library` and the gateway
  goes looking on the user's own machine, which errors out immediately for free
  accounts.
</Warning>

If the first search comes back empty, don't jump to blaming the configuration. Check in order: is the query too narrow → does `list_libraries` show 0 documents for this library (the owner hasn't pushed any content yet) → switch to `explore` to see what the library holds overall, then search again with that in mind.

***

## Troubleshooting

| Symptom                                                  | Cause and fix                                                                                                                                                                                                                            |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Handshake returns **401**                                | The key is invalid or revoked. Have the user generate a new one in the dashboard and copy it in full (it starts with `lkai_`).                                                                                                           |
| Handshake returns **403**                                | The credential lacks the `mcp` permission. Generating a new API key fixes it.                                                                                                                                                            |
| The target library is missing from `list_libraries`      | It hasn't been linked. Have the user click **Link** on the library page — their own libraries need it too.                                                                                                                               |
| Clicking **Link** says the quota is full                 | A free account has only one link slot. Unlink another library first, or upgrade to Pro (99 slots).                                                                                                                                       |
| Error mentions Desktop being unreachable, or needing Pro | You left out the `library` parameter, so the request was routed to the user's own machine by default. Add `library="cloud://owner/slug"` and retry.                                                                                      |
| `cloud://` is rejected as unsupported                    | You are connected to the local server (`linkly-ai`), not the cloud gateway. Cloud libraries are unreachable on that path — add a separate `linkly-ai-cloud` connection.                                                                  |
| Error says `library must be in 'owner/slug' format`      | Usually the web address was passed straight into `library`. Convert it to the two-part `cloud://<owner>/<slug>` form as described at the top; a single segment is rejected too. When unsure, take the exact value from `list_libraries`. |
| Configured, but the tools never appear                   | Needs a config reload or a new session. This is the client's loading behavior, not a configuration error.                                                                                                                                |
| The user's local search suddenly finds nothing           | The cloud configuration was written under the name `linkly-ai` and overwrote the local entry. Switch to `linkly-ai-cloud` and re-add the entry pointing at the local machine.                                                            |
| The library reports 0 documents                          | The owner hasn't pushed content to the cloud yet. That isn't something you can fix — tell the user plainly.                                                                                                                              |

***

## Report back when you are done

Close with a short paragraph for the user covering:

* which route the connection took (API key or OAuth) and what the server is named;
* whether a session restart is needed for anything to take effect;
* how many documents the library holds and roughly what is in it;
* how to actually use it — remind them that naming the library is all they need to do, and you will attach the `library` parameter automatically.

If any step could not be completed, say so plainly: where you got stuck, what you tried, and what the user can do next.

### Finish with four example questions

End your report with four questions the user can copy and try immediately. **They must be tailored to what is actually in this library**:

Start with `explore` to see the shape of the collection, `search` a few themes if you need more detail, then write four questions that genuinely point at this library's content. Don't write one-size-fits-all filler like "summarize this knowledge base" — a good question makes the user think "that is clearly about what's in this library."

***

## Further reading

* [Using Cloud Libraries](/docs/en/use-cloud-library) — the full guide for human readers: creating, pushing, sharing, quotas
* [Setup Guide for Agents](/docs/en/agent-setup) — the page to follow when you want to index files on your own computer
* [Tools Introduction](/docs/en/tools-intro) — full parameter reference for the seven retrieval tools
* [Using Skills](/docs/en/use-skills) — teach your AI assistant how to combine these tools well