Cursor e MCP: aggiungere la ricerca nella documentazione all'editor

Per far cercare a Cursor nella Sua documentazione basta dichiarare un server MCP nel file `.cursor/mcp.json` del progetto e inserire una chiave API in un'intestazione. Da quel momento l'agente di Cursor interroga una knowledge base mentre scrive codice e Le mostra i passaggi su cui si basa. In questa guida trova la configurazione esatta, gli strumenti disponibili, prompt collaudati e una tabella per risolvere i problemi più frequenti.

Perché collegare la documentazione a Cursor tramite MCP

Cursor conosce bene il codice del Suo repository, ma ignora tutto ciò che sta fuori: le convenzioni interne delle API, il manuale di integrazione di un fornitore, le regole di fatturazione che il modulo deve rispettare. Quando manca l'informazione, l'agente tira a indovinare, e un'ipotesi infilata nel codice generato è difficile da scovare in revisione.

Il Model Context Protocol (MCP) è uno standard aperto che consente a un client di IA come Cursor di chiamare strumenti esterni. Un server di documentazione espone uno strumento di ricerca: l'agente decide quando usarlo, riceve i passaggi pertinenti e costruisce la risposta o la modifica al codice a partire da quelli. I vantaggi sono concreti:

• Risposte fondate su una fonte scelta da Lei, non sui ricordi di addestramento del modello.
• Citazioni verificabili: ogni risposta arriva con passaggi numerati.
• Niente più copia e incolla di pagine intere nella chat, così la finestra di contesto resta libera per il codice.
• Un'unica fonte per tutto il team: lo stesso server funziona anche in Claude, ChatGPT e altri client MCP.

Cosa serve per iniziare

1. Una versione recente di Cursor con supporto MCP.
2. Una base da interrogare: una base pubblica del catalogo Kopik oppure la Sua documentazione caricata come base privata. Creare una base è gratuito: carica PDF, Word, testo o Markdown e Kopik estrae, suddivide e indicizza i contenuti per una ricerca ibrida.
3. Una chiave API Kopik, creata dalla dashboard, che inizia con `kpk_`. Solo lo strumento gratuito `list_bases` funziona senza chiave.
4. Il permesso di aggiungere un file nella radice del progetto.

Passo 1: creare il file .cursor/mcp.json

Nella radice del progetto crei una cartella `.cursor` e al suo interno un file `mcp.json`. Incolli questo contenuto sostituendo la chiave con la Sua: `{ "mcpServers": { "kopik": { "url": "https://kopik.fr/api/mcp", "headers": { "Authorization": "Bearer kpk_…" } } } }`. Se desidera il server in tutti i progetti, inserisca lo stesso contenuto nel `mcp.json` della cartella `.cursor` della Sua directory home.

Limitare il server a una sola base

L'URL precedente apre l'intero catalogo e l'agente indica la base a ogni chiamata. Se il progetto ha bisogno di una sola documentazione, usi l'indirizzo specifico della base, `https://kopik.fr/api/mcp?base=slug-della-sua-base`, riportato su ogni pagina di base. L'argomento `base` sparisce dagli strumenti, i prompt si accorciano e l'agente non può finire su altre basi. Funziona anche con le basi private, usando la chiave del proprietario.

Passo 2: verificare gli strumenti in Cursor

Apra le impostazioni MCP di Cursor: il server `kopik` deve risultare attivo con tre strumenti. Se ha modificato il file con Cursor aperto, disattivi e riattivi il server oppure ricarichi la finestra.

`maxPriceCents` è un tetto di spesa: se la base costa di più, la chiamata viene rifiutata senza addebito. Di default Cursor chiede di approvare ogni chiamata a uno strumento; all'inizio conviene lasciarlo così, per vedere quale base e quale domanda invia l'agente.

Prompt che funzionano dall'editor

L'agente sceglie da solo quando chiamare uno strumento, ma se nomina lo strumento e la base il comportamento diventa prevedibile:

• Trovare una base: «Usa list_bases con la query ‹AI Act› e dimmi quale base è adatta a domande sui sistemi ad alto rischio».
• Domandare con le fonti: «Chiedi alla base eu-ai-act-essentials quali obblighi hanno i fornitori di sistemi di IA ad alto rischio e cita i passaggi».
• Scrivere codice dalla propria documentazione: «Chiama ask_base su guida-api-interna: come funziona la paginazione dell'endpoint ordini? Poi adatta fetchOrders in questo file».
• Passaggi grezzi: «Usa search_base su guida-api-interna per ‹politica di retry e chiavi di idempotenza›, scrivi il wrapper di retry e indica i numeri dei passaggi in un commento».
• Limitare la spesa: «Fai la domanda con maxPriceCents 10».

Due abitudini fanno la differenza: chieda sempre i passaggi e non solo la conclusione, così può verificare prima del merge, e preferisca `search_base` quando l'agente deve comunque scrivere codice, perché riceve le prove grezze allo stesso prezzo.

Risoluzione dei problemi

Se automatizza le chiamate, tenga presente che i batch JSON-RPC accettano al massimo 10 richieste. Tutti i dettagli, compresa l'API REST equivalente, sono nella documentazione per sviluppatori.

Sicurezza e costi prima di estendere al team

Il testo recuperato è un dato, non un'istruzione. Kopik racchiude il contenuto delle basi tra tag kopik-untrusted, così il client lo distingue dal Suo prompt e si riduce il rischio di istruzioni nascoste in un documento. Tenga attiva l'approvazione delle chiamate nelle sessioni in cui l'agente può anche modificare file o eseguire comandi.

Quanto al budget, le chiamate via API e MCP sono sempre addebitate al prezzo della base, su crediti prepagati; le domande gratuite del sito non valgono qui. Le Sue basi restano gratuite entro un uso ragionevole.