Cursor y MCP: cómo buscar en su documentación desde el editor

Para que Cursor busque en su documentación, basta con declarar un servidor MCP en el archivo `.cursor/mcp.json` del proyecto y añadir una clave API en una cabecera. A partir de ahí, el agente de Cursor consulta una base de conocimiento mientras programa y le muestra los fragmentos en los que se apoya. En este tutorial encontrará la configuración exacta, las herramientas disponibles, prompts que funcionan y una tabla para resolver los fallos habituales.

¿Qué aporta conectar documentación a Cursor con MCP?

Cursor entiende bien el código de su repositorio, pero no sabe nada de lo que vive fuera de él: las convenciones internas de su API, el manual de integración de un proveedor o las normas de facturación que su módulo debe cumplir. Cuando le falta esa información, el agente supone, y una suposición dentro de código generado es difícil de detectar en la revisión.

El Model Context Protocol (MCP) es un estándar abierto que permite a un cliente de IA como Cursor llamar a herramientas externas. Un servidor de documentación expone una herramienta de búsqueda; el agente decide cuándo usarla, recibe fragmentos relevantes y construye su respuesta o su cambio de código a partir de ellos. Las ventajas son claras:

• Respuestas basadas en la fuente que usted elige, no en lo que el modelo recuerda de su entrenamiento.
• Citas verificables: cada respuesta llega con fragmentos numerados.
• Adiós al copiar y pegar páginas enteras en el chat, lo que deja la ventana de contexto libre para el código.
• Una única fuente de verdad para el equipo: el mismo servidor funciona en Claude, ChatGPT y otros clientes MCP.

Requisitos previos

1. Una versión reciente de Cursor con soporte para MCP.
2. Una base que consultar: una base pública del catálogo de Kopik o su propia documentación como base privada. Crear una base es gratis: sube PDF, Word, texto o Markdown y Kopik extrae, divide e indexa el contenido para una búsqueda híbrida.
3. Una clave API de Kopik, creada desde el panel, que empieza por `kpk_`. Solo la herramienta gratuita `list_bases` funciona sin clave.
4. Permiso para añadir un archivo en la raíz del proyecto.

Paso 1: crear el archivo .cursor/mcp.json

En la raíz del proyecto, cree una carpeta `.cursor` y, dentro, un archivo `mcp.json`. Pegue este contenido sustituyendo la clave por la suya: `{ "mcpServers": { "kopik": { "url": "https://kopik.io/api/mcp", "headers": { "Authorization": "Bearer kpk_…" } } } }`. Si quiere el servidor en todos sus proyectos, ponga el mismo contenido en el `mcp.json` de la carpeta `.cursor` de su directorio personal.

Limitar el servidor a una sola base

La URL anterior abre todo el catálogo y el agente indica la base en cada llamada. Si el proyecto solo necesita una documentación, use la dirección propia de la base, `https://kopik.io/api/mcp?base=slug-de-su-base`, que aparece en cada página de base. El argumento `base` desaparece de las herramientas, los prompts se acortan y el agente no puede desviarse a otras bases. También funciona con bases privadas, usando la clave de su propietario.

Paso 2: comprobar las herramientas en Cursor

Abra los ajustes MCP de Cursor: el servidor `kopik` debe aparecer activo con tres herramientas. Si modificó el archivo con Cursor abierto, desactive y vuelva a activar el servidor o recargue la ventana.

`maxPriceCents` funciona como tope: si la base cuesta más, la llamada se rechaza sin coste. Por defecto, Cursor le pide aprobar cada llamada a una herramienta; manténgalo así al principio para ver qué base y qué pregunta envía el agente.

Prompts que funcionan desde el editor

El agente decide por sí mismo cuándo llamar a una herramienta, pero si nombra la herramienta y la base, su comportamiento se vuelve predecible:

• Encontrar una base: «Usa list_bases con la consulta ‹transferencias RGPD› y dime qué base sirve para preguntas sobre cláusulas contractuales tipo».
• Preguntar con fuentes: «Pregunta a la base eu-gdpr-official-texts-data-transfers si necesitamos una evaluación de impacto de la transferencia para un subencargado en Estados Unidos y cita los fragmentos».
• Programar según su documentación: «Llama a ask_base en guia-api-interna: ¿cómo funciona la paginación del endpoint de pedidos? Después adapta fetchOrders en este archivo».
• Fragmentos en bruto: «Usa search_base en guia-api-interna para ‹política de reintentos y claves de idempotencia›, escribe el wrapper de reintentos e indica los números de fragmento en un comentario».
• Limitar el gasto: «Haz la pregunta con maxPriceCents 10».

Dos hábitos marcan la diferencia: pida los fragmentos y no solo la conclusión, para verificar antes de fusionar, y prefiera `search_base` cuando el agente vaya a escribir código, porque recibe las pruebas en bruto al mismo precio.

Solución de problemas

Si automatiza llamadas, tenga en cuenta que los lotes JSON-RPC admiten como máximo 10 peticiones. Todos los detalles, incluida la API REST equivalente, están en la documentación para desarrolladores.

Seguridad y costes antes de desplegar en el equipo

El texto recuperado es un dato, no una instrucción. Kopik envuelve el contenido de las bases en etiquetas kopik-untrusted para que el cliente lo distinga de su prompt, lo que limita la inyección de instrucciones ocultas en un documento. Mantenga activa la aprobación de llamadas en las sesiones en las que el agente también puede editar archivos o ejecutar comandos.

En cuanto al presupuesto, las llamadas por API y MCP se cobran siempre al precio de la base, con créditos prepagados; las preguntas gratuitas del sitio web no se aplican aquí. Sus propias bases siguen siendo gratuitas dentro de un uso razonable.