Conectar tu asistente de IA

La plataforma publica un servidor MCP: una vez configurado, tu asistente de IA puede consultar las bases de conocimiento de tu organización desde donde ya trabajas. No hay que copiar documentos ni abrir el panel para buscar algo.

El asistente obtiene tres herramientas, todas de solo lectura: listar las bases de conocimiento, buscar dentro de ellas y pedir el enlace de descarga de un documento original.

Lo que necesitas

La dirección del servidor es siempre la misma:

https://mcp-kb-rag.navidev.dev/mcp

Además tienes que identificarte, y hay dos formas. Cuál te toca la decide tu herramienta, no tú:

Iniciar sesión no tiene misterio: pegas la dirección, se abre el navegador y entras con tu cuenta del panel. API key significa crear una clave en Configuración → API keys y pegarla en la configuración de la herramienta.

Si tu herramienta admite las dos, usa la de iniciar sesión: no hay ninguna credencial que guardar ni que se te pueda escapar.

Claude Code

claude mcp add --scope user --transport http kb-rag https://mcp-kb-rag.navidev.dev/mcp \
  --header "x-api-key: TU_API_KEY"

Para comprobarlo, claude mcp list debe mostrar el servidor como conectado.

Usa --scope user. El ámbito por defecto es local, que solo vale en la carpeta desde la que lo añadiste. Una base de conocimiento de la empresa no es algo de un proyecto concreto: la querrás en todas tus sesiones.

Para quitarlo o cambiar la clave: claude mcp remove kb-rag --scope user y vuelve a añadirlo.

Cursor

Edita ~/.cursor/mcp.json (en Windows, %USERPROFILE%\.cursor\mcp.json) para tenerlo en todos los proyectos, o .cursor/mcp.json dentro de uno para limitarlo a ese:

{
  "mcpServers": {
    "kb-rag": {
      "url": "https://mcp-kb-rag.navidev.dev/mcp",
      "headers": {
        "x-api-key": "${env:KB_RAG_API_KEY}"
      }
    }
  }
}

Fíjate en ${env:KB_RAG_API_KEY}: define la clave como variable de entorno en lugar de escribirla en el fichero. Es importante si usas .cursor/mcp.json dentro de un proyecto, porque ese fichero acaba en el repositorio con facilidad.

VS Code (GitHub Copilot)

Necesitas VS Code 1.101 o posterior. En el mcp.json del workspace o del usuario:

{
  "inputs": [
    {
      "id": "kb_rag_api_key",
      "type": "promptString",
      "description": "API key de la base de conocimiento",
      "password": true
    }
  ],
  "servers": {
    "kb-rag": {
      "type": "http",
      "url": "https://mcp-kb-rag.navidev.dev/mcp",
      "headers": {
        "x-api-key": "${input:kb_rag_api_key}"
      }
    }
  }
}

El bloque inputs hace que VS Code te pida la clave la primera vez y la guarde de forma segura, en vez de dejarla escrita en el fichero.

Claude Desktop

Sin API key. Aquí te identificas con tu cuenta del panel, igual que cuando entras a la web.

1. Configuración → Conectores → Agregar conector personalizado.
2. Nombre: el que quieras (kb-rag, por ejemplo).
3. URL: https://mcp-kb-rag.navidev.dev/mcp.
4. Deja vacíos el Client ID y el secreto. No hacen falta: el conector se da de alta solo.
5. Al guardar se abre el navegador. Inicia sesión con tu cuenta del panel —si tienes la verificación en dos pasos activada te pedirá además el código de seis dígitos—, elige la organización si perteneces a más de una, y acepta los permisos que te pide.

Al volver, el conector aparece conectado y con sus tres herramientas. Puedes decidir en esa misma pantalla si cada una se ejecuta sola o te pide aprobación; dejarlo en «Requiere aprobación» es además la forma más simple de ver cuándo está usando de verdad la base de conocimiento.

Esa autorización caduca y se renueva sola mientras la conexión siga viva. Puedes retirarla cuando quieras desde Conexiones.

Otras herramientas

Cualquier cliente que hable Streamable HTTP sirve, por cualquiera de las dos vías:

• Si admite cabeceras personalizadas: la dirección y x-api-key con tu clave.
• Si implementa la autorización de MCP: solo la dirección. Al no encontrar credencial, el servidor le dice dónde autenticarse y el cliente abre el navegador él solo, como Claude Desktop.

Dos detalles por si el cliente es especial:

• Si solo ofrece un campo genérico de «token» o «bearer», también se acepta Authorization: Bearer TU_API_KEY. Se prefiere x-api-key porque algunos servicios reescriben la cabecera Authorization.
• Si el cliente exige elegir tipo de transporte, es Streamable HTTP (o «HTTP»), no SSE ni stdio.

Comprobar que funciona

No hay que invocar nada: una vez conectado, el asistente decide cuándo usar las herramientas. Prueba en este orden:

¿qué bases de conocimiento tengo?
busca en mi base de conocimiento qué dice sobre <un tema de tus documentos>
pásame el enlace de descarga de ese documento

Lo que deberías ver:

• Para buscar necesita saber en qué base, así que primero listará las bases y luego buscará, sin que se lo pidas.
• Te devuelve fragmentos de los documentos, no una respuesta ya elaborada: el asistente los lee y te contesta él, citando de dónde sale cada cosa. Es a propósito.
• Cada fragmento lleva una puntuación de parecido. Una puntuación baja es normal, no un fallo: la búsqueda siempre devuelve lo más cercano que encuentra, así que los últimos resultados suelen ser poco relevantes.
• El enlace de descarga es para ti: el asistente no puede abrirlo. Y caduca en unos minutos, así que úsalo en el momento; si lo necesitas más tarde, pídele otro.

Problemas frecuentes

• El servidor no aparece al listarlo. En Claude Code, se añadió con ámbito local desde otra carpeta. Reañádelo con --scope user.
• No conecta, error 401. Falta la cabecera o el nombre está mal escrito: tiene que ser exactamente x-api-key.
• Conecta, pero todo falla con «la API key no es válida». La clave es incorrecta o está revocada. Crea otra en el panel.
• «Esta base de conocimiento no existe en tu organización». Tu clave es de otra organización.
• «Demasiadas peticiones». Has hecho muchas búsquedas seguidas. Espera medio minuto.
• «Este documento no conserva el fichero original». Ese documento se indexó sin guardar el original: su texto sí se puede buscar, pero el fichero no existe para descargar.
• Se abre una ventana del navegador pidiendo autorización. Es el otro modo de conectarse, y es normal si tu cliente lo prefiere: inicias sesión y autorizas, sin copiar ninguna clave.
• Conectaste por el navegador y al rato deja de funcionar. La autorización caducó o se retiró desde el panel. Vuelve a autorizar cuando tu cliente te lo ofrezca.
• «Esta conexión no tiene permiso para esa operación». Autorizaste el servidor con menos permisos de los que la herramienta necesita. Vuelve a autorizarlo y concédelos.
• Al conectar te pide un código de seis dígitos. Tienes la verificación en dos pasos activada: es el mismo código que usas para entrar al panel. Si no tienes la aplicación a mano, usa uno de tus códigos de respaldo.
• «El código no es válido» y estás seguro de que lo es. Lo más frecuente es que la hora de tu dispositivo esté desajustada: los códigos se calculan con el reloj. Si está bien, o el código ya caducó (cambian cada 30 segundos: espera al siguiente) o es un código de respaldo ya usado.
• La pantalla del código caduca antes de teclearlo. Tiene 10 minutos de margen. Vuelve a lanzar la conexión desde tu herramienta y repite el inicio de sesión.
• «Demasiados intentos fallidos» al escribir la contraseña. La cuenta se bloquea 30 minutos tras cinco fallos seguidos. Para entrar ya, restablece la contraseña desde el panel: eso levanta el bloqueo al instante. Ver Seguridad.

Límites que conviene conocer

• Ves todas las bases de conocimiento de tu organización, tanto con API key como iniciando sesión. No hay permisos por base: si necesitas que alguien vea solo una parte, la vía es una organización aparte.
• El asistente no descarga ficheros. Te da el enlace y descargas tú.
• Se buscan los documentos ya procesados. Uno recién subido puede tardar en aparecer, y uno que falló al procesarse no aparecerá aunque se cuente en el total.

Actualizado el 19 ago 2026