> ## 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:
```
Set up https://linkly.ai/docs/en/library-setup.md, then connect this library and show me what I can ask: 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.
**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).
***
## 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:///"`;
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 `/` 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 `/` 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 — and, once you are on the cloud gateway, link the library the user asked for (`library_search` to confirm the `cloud://` reference, then `library_link`). 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, generate an API key in the dashboard, complete OAuth authorization in the browser, accept an owner's invitation, and decide which library to give up when their link slot is full. These are browser actions — you cannot do them. Unlinking itself you can do with `library_link` (`action: "unlink"`), but only for a library the user named — never one you picked.
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.
* **Once the MCP config is written, do not keep probing the current session to see whether the tools appeared.** New tools only arrive once the client reloads — that is the loading mechanism, not a fault. Writing the config successfully completes the step; leave the rest of the verification until after the user reloads.
* **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 |
**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 — including the browser **Link** in item 3, because on that path there is no gateway tool to do it for them.
***
## 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 | Link it yourself: Step 3, item 1 |
| 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 a credential
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. Linking the library itself is not on this list: once you are connected to the cloud gateway, you do that in Step 3.
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//`, so the account needs a unique username. Set it once in the **Dashboard** when prompted; you never have to think about it again.
### 3. (Optional) Link the library in the browser
Not needed when you will reach the cloud gateway: in Step 3 you link the library yourself with `library_link`. The browser route still works — 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**. Whichever route is used, the owner can always link their own library; anyone else needs an accepted invitation from the owner to link a Showcase or Private library.
**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.
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 confirms they are signed in and have a username. On the API key route, also confirm they have a key starting with `lkai_`; on the OAuth route, the authorization happens in Step 2. **Linked** is required only when the user took the browser route in item 3 — when you link the library yourself with `library_link`, the link and a real search are verified in Step 3.
***
## 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.**
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`.
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.
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** — the vast majority of clients read the tool list once, at the moment the session starts. This is the client's loading mechanism, not a configuration error, so **do not keep probing the current session to see whether the tools have appeared.**
**How to reload**: relay both options to the user, and have them 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.
***
## Step 3: End-to-end verification
**If the retrieval tools have not shown up in your session yet, close out here — don't push on.** It means the client hasn't reloaded the config, which is the loading mechanism, not a failure. Close out with "config written, pending user verification after the reload" (on Option A, add that the handshake came back healthy), **repeat the two reload options from Step 2**, hand the user the line below, then stop (this is not overstating progress):
> After reloading, send me this: "use linkly-ai-cloud to search `cloud://blueeon/linkly-init-example` for ``". If it returns document entries, the whole chain works.
Write the library identifier out **in full** in that handover line, and replace `` with a concrete term. After the reload it is a **brand-new session**, and the you on the other side has none of this context — it won't know which library the user connected, or how far you got.
Once the tools are available, 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, link it now — on the cloud gateway this is your job, not the user's: call `library_search` (pass `owner` when you know the username) to confirm the exact `cloud:///`, then `library_link` with that reference, and call `list_libraries` again. Three answers need the user; relay them plainly instead of retrying:
* `invite_required` — the library is Showcase or Private and the user has no invitation; the owner has to invite them.
* `slot_exhausted` — the link quota is full; the error's `data` carries `current`, `limit`, `is_pro` and `guidance`, so report those numbers instead of guessing the plan. If the user has already named the library to give up ("replace A with B"), call `library_link` with `action: "unlink"` on it and then `library_link` again; otherwise show them the linked libraries from `list_libraries` and ask which one to release — never choose one yourself. The website and, on the free plan (`is_pro: false`, 1 slot), the Pro upgrade remain the alternatives.
* `not_found` — the reference is wrong, or the library is Private and invisible to this account; search by `owner` and ask the user to confirm the address.
Only when you cannot reach the cloud gateway at all does the browser route apply — Step 1, item 3.
**2. Run one real search:**
```
search(query="…", library="cloud://blueeon/linkly-init-example")
```
**Success means**: real document entries came back.
The `library` parameter is required **every single time**, and it must be the
full two-part `cloud:///` 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.
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. Link it yourself as in Step 3, item 1 (`library_search` → `library_link`); the browser **Link** button is only for when you cannot reach the cloud gateway. The user's own libraries need linking too. |
| `library_link` answers `slot_exhausted`, or clicking **Link** says the quota is full | The link quota is full — read `current` / `limit` / `is_pro` from the error instead of assuming the plan. Ask which linked library to release (`list_libraries`), then `library_link` it with `action: "unlink"` and link again; never pick one yourself. Free (1 slot) can also upgrade to Pro (99 slots); the website works for both. |
| 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:///` form as described at the top; a single segment is rejected too. When unsure, take the exact value from `list_libraries`. |
| MCP configured but the tools never appear | The client hasn't reloaded yet. Have the user start a new conversation; if that doesn't help, quit the client completely and reopen it (closing the window doesn't count). This is the loading mechanism, 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 reload is needed for anything to take effect — and if so, spell out both options ("start a new conversation" / "quit the client completely and reopen");
* 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