Cloud Library Setup for Agents

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.

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.

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:

The client you are running in is connected to the Linkly AI cloud gateway (mcp.linkly.ai);
You can genuinely retrieve content from that library using library="cloud://<owner>/<slug>";
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

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.

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:

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): Go to 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. 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.

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

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

{
  "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. 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:

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.

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.

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.

For where these settings live in each application, see Using Linkly AI in ChatGPT and Using Linkly AI in Claude.

Option C: CLI (optional)

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

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.

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.

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

Getting Started

Core Features

Connect Your AI Tools

For AI Agents

Cloud Library Setup for Agents

To the AI agent

Your task

First: turn the web address into a library identifier

Your boundaries and rules

First, work out which kind of client you are

Step 0: Probe the current state

State table

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

3. Open the library page and click Link

4. Get a credential (pick one)

Step 2: Connect to the cloud MCP

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

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

Option C: CLI (optional)

Step 3: End-to-end verification

Troubleshooting

Report back when you are done

Finish with four example questions

Further reading

​To the AI agent

​Your task

​First: turn the web address into a library identifier

​Your boundaries and rules

​First, work out which kind of client you are

​Step 0: Probe the current state

​State table

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

​1. Sign up and sign in

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

​3. Open the library page and click Link

​4. Get a credential (pick one)

​Step 2: Connect to the cloud MCP

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

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

​Option C: CLI (optional)

​Step 3: End-to-end verification

​Troubleshooting

​Report back when you are done

​Finish with four example questions

​Further reading

To the AI agent

Your task

First: turn the web address into a library identifier

Your boundaries and rules

First, work out which kind of client you are

Step 0: Probe the current state

State table

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

1. Sign up and sign in

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

3. Open the library page and click Link

4. Get a credential (pick one)

Step 2: Connect to the cloud MCP

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

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

Option C: CLI (optional)

Step 3: End-to-end verification

Troubleshooting

Report back when you are done

Finish with four example questions

Further reading