Skip to main content
Esta página está escrita principalmente para agentes de IA, no para personas. En la página de cualquier biblioteca en la nube, pulsa Usar en IA y copia a tu asistente de IA la frase del diálogo. También puedes lanzarlo a mano: sustituye la dirección de la línea de abajo por la de la biblioteca que quieras usar.
También puedes seguir leyendo por tu cuenta: esta es igualmente una guía de conexión completa. Simplemente está redactada de forma más directa que la mayoría, con especial énfasis en cómo saber si cada paso funcionó realmente. Si tu asistente de IA no puede acceder a internet, usa Copy page en la esquina superior derecha para obtener esta página como Markdown en bruto y pégasela directamente.
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:
  1. El cliente en el que te ejecutas esté conectado a la pasarela en la nube de Linkly AI (mcp.linkly.ai);
  2. Puedas recuperar contenido real de esa biblioteca usando library="cloud://<owner>/<slug>";
  3. 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:
Pero el parámetro 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, 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_search para confirmar la referencia cloud:// y luego library_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, completar la autorización OAuth en el navegador, escribir él mismo una clave API en la configuración cuando el cliente no admite OAuth, 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.
Y unas cuantas reglas estrictas; cada una corresponde a un escenario que falla de verdad:
  • 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-ai apuntando a http://127.0.0.1:60606/mcp. La nube es una entrada adicional y su nombre debe ser linkly-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 referencias cloud:// 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 library explícitamente en cada búsqueda. Si omites el parámetro library, 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.
  • No pidas al usuario su clave API (la que empieza por lkai_), ni ejecutes linkly auth set-key o escribas una clave en una configuración por él. La clave puede leer sus bibliotecas en la nube y, con el acceso remoto activado, los archivos de su propio ordenador. Todo lo que pasa por una conversación se envía al proveedor del modelo y queda guardado en el historial. Conéctate mediante OAuth o linkly auth login: el usuario solo autoriza en el navegador. Si el usuario te envía igualmente una clave, no la uses; dile que la revoque y cree una nueva en el panel (https://linkly.ai/dashboard/security).
  • 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:
Atajo: si el usuario ya tiene instalada la aplicación de escritorio de Linkly AI, puede mencionar con @ cualquier biblioteca en la nube ya vinculada dentro del Chat de la aplicación, sin configurar ningún MCP. Por esta vía solo hace falta completar el Paso 1, incluido el botón Vincular del navegador (punto 3), porque en ese camino no hay herramienta de pasarela que lo haga por él.

​
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 como linkly-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:
Fíjate en la URL de cada uno: si empieza por 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

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, y código de verificación por correo electrónico. 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 forma linkly.ai/<username>/<slug>, así que la cuenta necesita un nombre de usuario único. La primera vez que una cuenta nueva inicia sesión pasa por la página «Completa tu perfil»: basta con rellenar el nombre para mostrar y el nombre de usuario. El nombre de usuario no se puede cambiar después; a partir de ahí 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 con library_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.
Incluso las bibliotecas creadas por el propio usuario hay que vincularlas una vez. El alcance de búsqueda de MCP se basa en la relación de vinculación, no en la propiedad: una biblioteca sin vincular no aparece en list_libraries, ni siendo suya.
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. No hace falta preparar una clave API

Al conectar se abre la página de autorización de linkly.ai: basta con autorizar una vez en el navegador, sin copiar ninguna clave. No envíes tu clave API (la que empieza por lkai_) a un asistente de IA: el contenido de las conversaciones se envía al proveedor del modelo y queda guardado en el historial. Solo si tu herramienta de IA no admite este tipo de autorización necesitas una clave: la creas en el panel y la escribes tú mismo en el archivo de configuración, siguiendo el Paso 2.
Criterio de aceptación: el usuario confirma que ha iniciado sesión y tiene nombre de usuario. 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:
Usa siempre 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: Añadir la URL y autorizar en el navegador (clientes con terminal, recomendado)

Añade solo el endpoint, sin ninguna clave. Muestra primero el comando al usuario y obtén su consentimiento antes de ejecutarlo: Claude Code:
Después pide al usuario que escriba /mcp en Claude Code, seleccione linkly-ai-cloud y complete la autorización. Codex:
Otros clientes compatibles con HTTP MCP (Cursor, Gemini CLI, etc.): añade solo el endpoint en su configuración (los nombres de los campos siguen la documentación de cada fabricante; consulta la guía de integración de clientes de IA):
El cliente abre la página de autorización de linkly.ai; cuando el usuario inicia sesión y autoriza, el cliente guarda la credencial por sí mismo. Criterio de aceptación: la configuración está escrita y el usuario confirma que ha terminado la autorización en el navegador. La búsqueda real se comprueba en el Paso 3. Si el cliente no admite este tipo de autorización (solo puede enviar una cabecera Authorization: Bearer <clave> desde su configuración): esta parte la hace el usuario, solo, sin ti. Dile que cree una clave en la sección Claves API del panel y que la escriba él mismo en la cabecera de la petición del archivo de configuración; el formato está en la guía de integración de clientes de IA, y algunos clientes admiten la sintaxis ${env:LINKLY_API_KEY} para leerla de una variable de entorno. Pide al usuario que no te envíe la clave ni el contenido del archivo de configuración terminado, y no leas ni muestres tú ese archivo.

​
Opción B: OAuth (aplicaciones en línea como ChatGPT o Claude.ai)

Estas aplicaciones añaden un conector desde su propia interfaz y también van por autorización OAuth: 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.
Dónde está exactamente esa opción en cada aplicación: Usar Linkly AI en ChatGPT y Usar Linkly AI en Claude.

​
Opción C: CLI (opcional)

Si el usuario tiene instalada la CLI de Linkly AI, también puede hacerlo desde la terminal. El inicio de sesión tiene dos pasos; la CLI guarda la clave por sí misma, así que nunca pasa por la conversación:
Ejecuta ambos pasos en el mismo entorno; los detalles están en R2–R4 de la rama remota de la guía de instalación para agentes. --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.
  1. 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.
  2. 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 + Q o 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», 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, busca <algún tema> en la biblioteca cloud://blueeon/linkly-init-example». Si devuelve entradas de documentos, toda la cadena funciona.
En esa frase de relevo escribe el identificador de la biblioteca completo, y sustituye <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:
Si no aparece, vincúlala ahora: en la pasarela en la nube es tarea tuya, no del usuario. Llama a 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; el data del error trae current, limit, is_pro y guidance, 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 a library_link con action: "unlink" sobre ella y luego a library_link de nuevo; si no, muéstrale las bibliotecas vinculadas de list_libraries y 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 por owner y pide al usuario que confirme la dirección.
Solo si no puedes llegar a la pasarela en la nube en absoluto aplica la vía del navegador: Paso 1, punto 3. 2. Haz una búsqueda real:
Éxito significa: se devolvieron entradas de documentos reales.
El parámetro library hay que pasarlo siempre, y debe ser el cloud://<owner>/<slug> completo, en dos segmentos: escribir solo uno (por ejemplo, cloud://linkly-init-example) será rechazado. Si omites library, la pasarela consultará por defecto el ordenador del usuario, y por esa vía las cuentas gratuitas reciben un error directamente.
Si la primera búsqueda vuelve vacía, no lo atribuyas de inmediato a un error de configuración. Comprueba en orden: ¿es la consulta demasiado estrecha? → ¿el número de documentos de esa biblioteca en 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 (OAuth, inicio de sesión con la CLI o una clave API configurada a mano por el usuario) 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 library automáticamente.
Si algún paso no se pudo completar, dilo claramente: dónde te atascaste, qué intentaste y qué puede hacer el usuario a continuación.

​
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 primero explore 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