Guía de conexión a bibliotecas en la nube para Agentes

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.

Por favor, lee https://linkly.ai/docs/es/library-setup.md y guíame para conectar esta biblioteca: https://linkly.ai/blueeon/linkly-init-example

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:

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:

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

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

Lo que te da el usuario (dirección web)	Lo que pasas a la herramienta (identificador)
`https://linkly.ai/blueeon/linkly-init-example`	`cloud://blueeon/linkly-init-example`
`linkly.ai/7running/basedge`	`cloud://7running/basedge`

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. 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, pulsar Vincular en la página de la biblioteca, generar una clave API en el panel y completar la autorización OAuth en el navegador. Son acciones del navegador: tú no puedes hacerlas.

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

Si eres	Sigue
Un cliente con terminal o capaz de editar archivos de configuración (Claude Code, Codex, Cursor, Gemini CLI…)	La vía de la clave API (Paso 2, opción A)
Una aplicación en línea sin terminal (ChatGPT, Claude.ai…)	La vía OAuth (Paso 2, opción B): solo hay que rellenar una URL
El Chat que trae la aplicación de escritorio de Linkly AI	No hace falta configurar nada; mira el atajo de abajo

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.

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:

claude mcp list        # Claude Code
codex mcp list         # Codex

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:

Resultado del sondeo	Significado	Empieza en
Ya existe `linkly-ai-cloud` y puedes listar bibliotecas	La cadena en la nube ya funciona	Ve directo a la verificación del Paso 3
Ya existe `linkly-ai-cloud`, pero la biblioteca objetivo no sale	La cadena funciona, falta vincular la biblioteca	Paso 1 (solo el punto de vincular la biblioteca)
Solo existe `linkly-ai` (local)	Tiene la aplicación de escritorio, pero no la nube	Paso 1. Ojo: conserva la entrada local, no la sobrescribas
No hay ningún server de Linkly	Usuario nuevo	Paso 1

Paso 1: Pide al usuario que prepare su cuenta y vincule la biblioteca

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. 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 forma linkly.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. Abre la página de la biblioteca y pulsa Vincular

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.

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. 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 el botón de la página de la biblioteca ya muestra Vinculada. Si va por la vía de la clave API, confirma además que tiene una clave que empieza por lkai_.

Paso 2: Conectar el MCP en la nube

El endpoint es fijo:

https://mcp.linkly.ai/mcp

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

claude mcp add --transport http linkly-ai-cloud https://mcp.linkly.ai/mcp \
  --header "Authorization: Bearer lkai_tu_clave"

Otros clientes compatibles con HTTP MCP: añade un bloque en su propio archivo de configuración (en Cursor es mcp.json, en Gemini CLI es ~/.gemini/settings.json; los nombres de campo dependen de la documentación de cada uno):

{
  "mcpServers": {
    "linkly-ai-cloud": {
      "url": "https://mcp.linkly.ai/mcp",
      "headers": {
        "Authorization": "Bearer lkai_tu_clave"
      }
    }
  }
}

Las diferencias de campo entre clientes (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:

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_tu_clave" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'

Una respuesta que contenga "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.

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.

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:

linkly auth set-key lkai_tu_clave
linkly search "palabra clave" --remote --library "cloud://blueeon/linkly-init-example"

--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 mayoría de clientes necesitan recargar la configuración o iniciar una nueva sesión. Dile al usuario con claridad: «la configuración está escrita, recarga y vuelve a intentarlo». No sigas sondeando la sesión actual para ver si han aparecido las herramientas.

Paso 3: Verificación de extremo a extremo

Cuando las herramientas estén disponibles (puede que el usuario tenga que reiniciar la sesión), 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:

- **cloud://blueeon/linkly-init-example** (305 docs) [yours]: Documentos de inicialización del instalador de Linkly AI

Si no aparece, es que no se ha vinculado: vuelve al punto 3 del Paso 1. 2. Haz una búsqueda real:

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

É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

Síntoma	Causa y solución
El saludo inicial devuelve 401	Clave no válida o revocada. Pide al usuario que genere una nueva desde el panel y que la copie entera (empieza por `lkai_`).
El saludo inicial devuelve 403	A la credencial le falta el permiso `mcp`. Basta con generar una clave API nueva.
La biblioteca objetivo no está en `list_libraries`	Todavía no se ha vinculado. Pide al usuario que pulse Vincular en la página de la biblioteca; las bibliotecas propias también hay que pulsarlas.
Al pulsar Vincular avisa de que la cuota está llena	Las cuentas gratuitas solo tienen 1 espacio de conexión. Hay que desvincular otra biblioteca o pasar a Pro (99).
Un error menciona que Desktop no es accesible o que hace falta Pro	Te has dejado el parámetro `library` y la petición se enrutó por defecto al ordenador del usuario. Añade `library="cloud://owner/slug"` y reinténtalo.
`cloud://` se rechaza con un mensaje de «no compatible»	Estás conectado al server local (`linkly-ai`), no a la pasarela en la nube. Por esa ruta las bibliotecas en la nube son inalcanzables: hay que añadir una conexión `linkly-ai-cloud`.
Sale `library must be in 'owner/slug' format`	Lo más probable es que hayas pasado la dirección web tal cual a `library`. Conviértela según la regla del principio a `cloud://<owner>/<slug>`, en dos segmentos; un solo segmento también se rechaza. Ante la duda, usa `list_libraries` para el valor exacto.
Configurado, pero las herramientas no aparecen	Hay que recargar la configuración o iniciar una nueva sesión. Es el comportamiento de carga del cliente, no un error de configuración.
La búsqueda local del usuario ha dejado de encontrar cosas	La configuración de la nube usó el nombre `linkly-ai` y sobrescribió la entrada local. Cámbiala a `linkly-ai-cloud` y vuelve a añadir la entrada que apunta al ordenador.
La biblioteca tiene 0 documentos	El propietario aún no ha subido el contenido a la nube. Eso no lo puedes arreglar tú: díselo al usuario tal cual.

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 necesario reiniciar la sesión para que surta efecto;
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

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

Inicio rápido

Funciones principales

Conecta tus herramientas de IA

Para Agentes de IA

Guía de conexión a bibliotecas en la nube para Agentes

Para el agente de IA

Tu tarea

Lo primero: convertir la dirección web en identificador de biblioteca

Tus límites y reglas

Primero, averigua qué tipo de cliente eres

Paso 0: Sondear el estado actual

Tabla de estados

Paso 1: Pide al usuario que prepare su cuenta y vincule la biblioteca

1. Regístrate e inicia sesión

2. Define tu nombre de usuario (solo la primera vez)

3. Abre la página de la biblioteca y pulsa Vincular

4. Consigue las credenciales (una de dos)

Paso 2: Conectar el MCP en la nube

Opción A: Clave API (clientes con terminal, recomendado)

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

Opción C: CLI (opcional)

Paso 3: Verificación de extremo a extremo

Resolución de problemas

Informa cuando hayas terminado

Termina con cuatro preguntas de ejemplo

Lecturas adicionales

​Para el agente de IA

​Tu tarea

​Lo primero: convertir la dirección web en identificador de biblioteca

​Tus límites y reglas

​Primero, averigua qué tipo de cliente eres

​Paso 0: Sondear el estado actual

​Tabla de estados

​Paso 1: Pide al usuario que prepare su cuenta y vincule la biblioteca

​1. Regístrate e inicia sesión

​2. Define tu nombre de usuario (solo la primera vez)

​3. Abre la página de la biblioteca y pulsa Vincular

​4. Consigue las credenciales (una de dos)

​Paso 2: Conectar el MCP en la nube

​Opción A: Clave API (clientes con terminal, recomendado)

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

​Opción C: CLI (opcional)

​Paso 3: Verificación de extremo a extremo

​Resolución de problemas

​Informa cuando hayas terminado

​Termina con cuatro preguntas de ejemplo

​Lecturas adicionales

Para el agente de IA

Tu tarea

Lo primero: convertir la dirección web en identificador de biblioteca

Tus límites y reglas

Primero, averigua qué tipo de cliente eres

Paso 0: Sondear el estado actual

Tabla de estados

Paso 1: Pide al usuario que prepare su cuenta y vincule la biblioteca

1. Regístrate e inicia sesión

2. Define tu nombre de usuario (solo la primera vez)

3. Abre la página de la biblioteca y pulsa Vincular

4. Consigue las credenciales (una de dos)

Paso 2: Conectar el MCP en la nube

Opción A: Clave API (clientes con terminal, recomendado)

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

Opción C: CLI (opcional)

Paso 3: Verificación de extremo a extremo

Resolución de problemas

Informa cuando hayas terminado

Termina con cuatro preguntas de ejemplo

Lecturas adicionales