Esta vía no requiere instalar la aplicación de escritorio de Linkly AI. Las bibliotecas en la nube están alojadas en el servidor, disponibles las 24 horas, y cualquier herramienta de IA compatible con MCP puede consultarlas directamente. Si lo que quieres es indexar los archivos de tu propio ordenador, eso es otra cosa: consulta la Guía de instalación para Agentes.
Para el agente de IA
Todo lo que sigue va dirigido a ti. Léelo por completo antes de empezar.Tu tarea
Que el usuario pueda preguntar sobre una biblioteca en la nube concreta. Habrás terminado cuando:- El cliente en el que te ejecutas esté conectado a la pasarela en la nube de Linkly AI (
mcp.linkly.ai); - Puedas recuperar contenido real de esa biblioteca usando
library="cloud://<owner>/<slug>"; - Hayas acompañado al usuario en su primera pregunta real y le hayas dado una respuesta basada en documentos reales.
Lo primero: convertir la dirección web en identificador de biblioteca
Lo que el usuario te entrega es la dirección web de la biblioteca, con esta forma:library de las herramientas de recuperación espera un identificador de biblioteca. Son dos maneras de escribir lo mismo: sustituye el prefijo del dominio https://linkly.ai/ por cloud:// y conserva tal cual los dos segmentos <owner>/<slug>:
No pases la dirección web tal cual al parámetro
library: será rechazada. Todos los cloud://… de los ejemplos que siguen son ya el resultado de esa conversión.
Si la dirección que te dan lleva otros segmentos de ruta (como /settings) o parámetros de consulta, quédate solo con <owner>/<slug>. Ante la duda, conecta el MCP y llama una vez a list_libraries: la respuesta trae el identificador exacto.
Tus límites y reglas
Algunas cosas puedes hacerlas tú mismo; otras debes dejárselas al usuario. No te excedas ni des por hecho un resultado en nombre del usuario:- Puedes hacer tú mismo: sondear el estado actual de la conexión, escribir la configuración de MCP, enviar la petición de saludo inicial, invocar las herramientas de recuperación, interpretar errores e informar al usuario; y, una vez conectado a la pasarela en la nube, vincular la biblioteca que el usuario pide (
library_searchpara confirmar la referenciacloud://y luegolibrary_link). Para cualquier comando que escriba configuración, muéstraselo al usuario y obtén su consentimiento antes de ejecutarlo. - El usuario debe hacer: registrarse o iniciar sesión en linkly.ai, definir su nombre de usuario, generar una clave API en el panel, completar la autorización OAuth en el navegador, aceptar la invitación del propietario y decidir a qué biblioteca renuncia cuando su espacio de conexión está lleno. Son acciones del navegador: tú no puedes hacerlas. Desvincular sí puedes hacerlo con
library_link(action: "unlink"), pero solo con una biblioteca que el usuario haya nombrado, nunca una elegida por ti.
- No sobrescribas la configuración MCP local que el usuario ya tenga. Quien haya instalado la aplicación de escritorio suele tener ya en su cliente un server llamado
linkly-aiapuntando ahttp://127.0.0.1:60606/mcp. La nube es una entrada adicional y su nombre debe serlinkly-ai-cloud. Escribir con el mismo nombre reemplaza en silencio la entrada local: el usuario dejará de encontrar de golpe los documentos de su ordenador, y sin recibir ningún error. - Desde la conexión local no se llega a las bibliotecas en la nube. Por la vía
linkly-ai(local / red local), las referenciascloud://se rechazan siempre. No reintentes una biblioteca en la nube sobre la conexión local: es un límite de la ruta, no un fallo puntual. - Pasa
libraryexplícitamente en cada búsqueda. Si omites el parámetrolibrary, la pasarela enruta por defecto al ordenador del usuario (a través del túnel de escritorio), y el túnel es una función Pro: las cuentas gratuitas reciben un error directamente. Las bibliotecas en la nube nunca se incluyen de forma implícita. - Una biblioteca por llamada. Las bibliotecas en la nube no se combinan automáticamente en una misma búsqueda: para consultar dos, haz dos llamadas.
- Sondea antes de actuar. Puede que el usuario ya tenga parte de la configuración hecha: no recorras a ciegas todos los pasos desde el principio.
- Cuando el usuario deba actuar, dilo todo de una vez, luego detente y espera una única respuesta. No dividas una misma tarea en varias rondas de confirmación de ida y vuelta.
- Una vez escrita la configuración de MCP, no sigas sondeando la sesión actual para ver si han aparecido las herramientas. Las herramientas nuevas solo llegan cuando el cliente recarga: es el mecanismo de carga, no un fallo. Escribir la configuración correctamente ya completa el paso; deja el resto de la verificación para después de que el usuario recargue.
- Nunca exageres el progreso. Si no está verificado, no está hecho. Di exactamente dónde te has atascado y qué has intentado.
Primero, averigua qué tipo de cliente eres
La vía que debes seguir depende de si puedes escribir configuración y ejecutar comandos:Paso 0: Sondear el estado actual
Averigua primero hasta dónde llega ya la cadena y decide desde dónde empezar. Tres cosas: 1. ¿Tienes herramientas de recuperación de Linkly en la sesión actual? ¿De qué server vienen? La pasarela en la nube se identifica comolinkly-ai-cloud y la aplicación de escritorio local como linkly-ai. La mayoría de clientes reflejan el nombre del server en el nombre de la herramienta (por ejemplo, mcp__linkly-ai-cloud__search).
2. Si tienes terminal, lista directamente los servers configurados:
127.0.0.1 es local; mcp.linkly.ai es la nube.
3. ¿Tiene el usuario cuenta en linkly.ai? ¿Ha vinculado ya esta biblioteca?
Esto no lo puedes consultar: pregúntaselo directamente al usuario.
Tabla de estados
Coteja de arriba abajo y sigue la primera fila que coincida:Paso 1: Pide al usuario que prepare su cuenta y una credencial
Este paso ocurre entero en el navegador: tú no puedes hacerlo. Dale al usuario todo lo de abajo en un solo mensaje, luego detente y espera una única respuesta. No lo dividas en varias rondas de confirmación punto por punto. Vincular la biblioteca no está en esta lista: una vez conectado a la pasarela en la nube, lo haces tú en el Paso 3. Esto es lo que debes transmitirle al usuario (puedes reformularlo con tus propias palabras, pero cubre las cuatro partes):1. Regístrate e inicia sesión
Ve a https://linkly.ai y regístrate o inicia sesión; admite cuentas de Google, GitHub y Notion. Con una cuenta gratuita basta para completar todo el proceso.2. Define tu nombre de usuario (solo la primera vez)
La dirección de una biblioteca en la nube tiene la formalinkly.ai/<username>/<slug>, así que la cuenta necesita un nombre de usuario único. Se define una sola vez en el Dashboard, siguiendo las indicaciones; después ya no hay que tocarlo.
3. (Opcional) Vincular la biblioteca desde el navegador
No hace falta si vas a llegar a la pasarela en la nube: en el Paso 3 vinculas tú la biblioteca conlibrary_link. La vía del navegador sigue funcionando: entra en la dirección web de la biblioteca (por ejemplo, https://linkly.ai/blueeon/linkly-init-example) y pulsa el botón Vincular de la esquina superior derecha (en inglés: Link); cuando el botón pase a Vinculada y la insignia de estado muestre Conectada, está hecho. Por cualquiera de las dos vías, el propietario siempre puede vincular su propia biblioteca; cualquier otra persona necesita haber aceptado una invitación del propietario para vincular una biblioteca Showcase o Private.
Las cuentas gratuitas tienen 1 espacio de conexión (Slot). Si ya hay otra biblioteca vinculada, primero hay que desvincular esa o pasar a Pro (99 espacios). El diálogo de cuota de la página de la biblioteca incluye el acceso para mejorar el plan.
4. Consigue las credenciales (una de dos)
- Si tu asistente de IA tiene terminal o puede editar archivos de configuración: ve a https://linkly.ai/dashboard/integrations, pulsa el botón de crear en la sección Claves API y copia la clave generada (empieza por
lkai_). Esa clave equivale a las credenciales de la cuenta: úsala solo en tus propias herramientas de IA y no la compartas. - Si usas una aplicación en línea como ChatGPT o Claude.ai: no necesitas clave API. Sáltate este punto; más adelante completarás una autorización en el navegador.
Criterio de aceptación: el usuario confirma que ha iniciado sesión y tiene nombre de usuario. Si va por la vía de la clave API, confirma además que tiene una clave que empieza por
lkai_; si va por OAuth, la autorización se hace en el Paso 2. Vinculada solo se exige cuando el usuario ha seguido la vía del navegador en el punto 3: si vinculas tú la biblioteca con library_link, la vinculación y una búsqueda real se comprueban en el Paso 3.
Paso 2: Conectar el MCP en la nube
El endpoint es fijo:linkly-ai-cloud como nombre de server, nunca linkly-ai: ese es el nombre de la aplicación de escritorio local, y repetirlo sobrescribe la configuración local que el usuario ya tenga. Además, los agentes con Linkly Skills instalado tomarían esa conexión por una conexión local y rechazarían todas las peticiones cloud://.
Opción A: Clave API (clientes con terminal, recomendado)
Muestra primero el comando al usuario, explícale que escribirá la clave en un archivo de configuración local y obtén su consentimiento antes de ejecutarlo. Claude Code:mcp.json, en Gemini CLI es ~/.gemini/settings.json; los nombres de campo dependen de la documentación de cada uno):
url / httpUrl / serverUrl) están en la Guía de integración. Algunos clientes admiten la sintaxis ${env:LINKLY_API_KEY} para leer la clave de una variable de entorno, lo que evita escribirla en claro en el archivo de configuración.
Criterio de aceptación: envía un saludo inicial directamente para confirmar que el servidor responde correctamente:
"serverInfo":{"name":"linkly-ai-cloud" significa que la credencial es válida y la cadena está sana. Si devuelve 401, la clave es incorrecta o se ha revocado: pide al usuario que genere una nueva desde el panel.
Opción B: OAuth (aplicaciones en línea como ChatGPT o Claude.ai)
Estas aplicaciones no permiten añadir cabeceras personalizadas, así que van por autorización OAuth, que además resulta más sencillo: solo hay que rellenar una URL.1
Añadir el conector MCP
En los ajustes de conectores / MCP de la aplicación, añade un servidor nuevo con el nombre
linkly-ai-cloud y la URL https://mcp.linkly.ai/mcp.2
Completar la autorización en el navegador
Al guardar, la aplicación redirige automáticamente a la página de autorización de linkly.ai. Cuando el usuario inicie sesión y confirme, la aplicación obtiene un token de acceso que se enviará automáticamente en las peticiones siguientes, sin necesidad de volver a autorizar.
Opción C: CLI (opcional)
Si el usuario tiene instalada la CLI de Linkly AI, también puede hacerlo desde la terminal:--remote es el único modo de la CLI que llega a las bibliotecas en la nube; sin él solo consulta lo local.
Una vez configurado el MCP, las herramientas nuevas normalmente no quedan disponibles en la sesión actual: la inmensa mayoría de clientes leen la lista de herramientas una sola vez, en el momento en que arranca la sesión. Es el mecanismo de carga del cliente, no un error de configuración, así que no sigas sondeando la sesión actual para ver si han aparecido las herramientas. Cómo recargar: traslada las dos opciones al usuario y haz que pruebe primero la primera.
- Iniciar una conversación nueva (en herramientas de línea de comandos, sal y abre una sesión nueva). Una conversación que ya está en marcha conserva la lista de herramientas con la que arrancó; una nueva recoge la más reciente.
- Salir del cliente por completo y volver a abrirlo. Úsalo cuando la primera opción no sirva; y ten en cuenta que cerrar la ventana no es salir: en macOS pulsa
Cmd + Qo elige Salir en la barra de menús, y en Windows comprueba que también haya salido de la bandeja del sistema.
Paso 3: Verificación de extremo a extremo
Si las herramientas de búsqueda aún no han aparecido en tu sesión, cierra aquí; no fuerces. Significa que el cliente todavía no ha recargado la configuración: es el mecanismo de carga, no un fallo. Cierra con «configuración escrita, pendiente de verificación por el usuario tras la recarga» (en la Opción A, añade que el saludo inicial respondió correctamente), repite las dos formas de recargar del Paso 2, entrégale al usuario la línea de abajo y detente (esto no es exagerar el progreso):Tras recargar, mándame esta frase: «con linkly-ai-cloud, buscaEn esa frase de relevo escribe el identificador de la biblioteca completo, y sustituye<algún tema>en la bibliotecacloud://blueeon/linkly-init-example». Si devuelve entradas de documentos, toda la cadena funciona.
<algún tema> por un término concreto. Tras la recarga se trata de una sesión completamente nueva, y el tú del otro lado no tiene nada de este contexto: no sabrá a qué biblioteca se conectó el usuario ni hasta dónde llegaste.
Cuando las herramientas estén disponibles, haz dos comprobaciones para confirmar que toda la cadena funciona de verdad.
1. Confirma que la biblioteca sale en la lista:
Llama a list_libraries; la biblioteca objetivo debería aparecer en el listado, con esta forma:
library_search (pasa owner si conoces el nombre de usuario) para confirmar el cloud://<owner>/<slug> exacto, luego a library_link con esa referencia, y vuelve a llamar a list_libraries. Tres respuestas necesitan al usuario; transmítelas tal cual en lugar de reintentar:
invite_required: la biblioteca es Showcase o Private y el usuario no tiene invitación; tiene que invitarlo el propietario.slot_exhausted: la cuota de conexiones está llena; eldatadel error traecurrent,limit,is_proyguidance, así que transmite esas cifras en vez de adivinar el plan. Si el usuario ya ha nombrado la biblioteca a la que renuncia («sustituye A por B»), llama alibrary_linkconaction: "unlink"sobre ella y luego alibrary_linkde nuevo; si no, muéstrale las bibliotecas vinculadas delist_librariesy pregunta cuál liberar: nunca elijas una por tu cuenta. El sitio web y, en el plan gratuito (is_pro: false, 1 espacio), la mejora a Pro siguen siendo las alternativas.not_found: la referencia es incorrecta, o la biblioteca es Private e invisible para esta cuenta; busca porownery pide al usuario que confirme la dirección.
list_libraries es 0 (el propietario aún no ha subido contenido)? → usa explore para ver de qué va la biblioteca en conjunto y luego busca de forma más dirigida.
Resolución de problemas
Informa cuando hayas terminado
Cierra con un breve resumen para el usuario que cubra:- por qué vía se hizo la conexión (clave API u OAuth) y con qué nombre de server;
- si es necesaria una recarga para que surta efecto y, en tal caso, detalla las dos opciones («iniciar una conversación nueva» / «salir del cliente por completo y volver a abrirlo»);
- cuántos documentos tiene la biblioteca y de qué van a grandes rasgos;
- cómo usarlo a partir de ahora: recuérdale que basta con que diga claramente el nombre de la biblioteca cada vez que quiera consultarla, y que tú añadirás el parámetro
libraryautomáticamente.
Termina con cuatro preguntas de ejemplo
Cierra tu informe con cuatro preguntas que el usuario pueda copiar y probar de inmediato. Tienen que estar hechas a medida del contenido real de esta biblioteca: Usa primeroexplore para ver la composición general de la biblioteca y, si hace falta, search sobre algunos temas; después escribe cuatro preguntas que apunten de verdad a su contenido. Nada de «resume esta biblioteca» ni otras frases que valdrían para cualquier cosa: una buena pregunta hace que el usuario vea de un vistazo que trata justo de lo que hay en esta biblioteca.
Lecturas adicionales
- Usar bibliotecas en la nube — la explicación completa para lectores humanos: crear, subir, compartir y cuotas
- Guía de instalación para Agentes — la página adecuada cuando lo que quieres es indexar los archivos de tu propio ordenador
- Introducción a las herramientas — todos los parámetros de las siete herramientas de recuperación
- Usar Skills — para que tu asistente de IA sepa combinar mejor estas herramientas

