Context7 per Cursor e Claude Code: configurazione e verifica

Quando un agente ti propone un metodo che non conosci, chiedigli da dove l'ha preso. L'esempio può sembrare plausibile e appartenere a un'altra versione del pacchetto, o non esistere affatto nell'API. Per verificarlo serve la documentazione della libreria che il tuo progetto usa davvero.

Context7 cerca la documentazione delle librerie e passa all'agente i passaggi che servono. Si collega sia a Cursor sia a Claude Code. Fornisce fonti per lavorare con un'API; il codice che ne esce va comunque verificato nella tua applicazione.

• Panoramica

Questa guida spiega la configurazione per i client locali e propone una richiesta di controllo, utile per distinguere una ricerca reale da una risposta data a memoria. Abbiamo confrontato le istruzioni con la documentazione ufficiale. Non abbiamo avuto accesso al tuo account né provato la tua installazione.

Quando è utile

Parti da un compito che dipende da una libreria: la configurazione di un router, la gestione di un modulo, una query con un ORM, un caricamento di file tramite SDK. Qui devi sapere quali metodi esistono, che parametri accettano e quale comportamento descrive la documentazione.

Per un refuso o per una regola di business interna, la ricerca esterna con ogni probabilità non aggiunge nulla. Capisci prima quale informazione manca.

Non chiedere di «collegare tutta la documentazione». Fai la domanda precisa a cui la fonte deve rispondere.

Come funziona la ricerca

La connessione MCP ha due strumenti principali: `resolve-library-id` trova l'identificatore della libreria, `query-docs` recupera il materiale che risponde alla domanda. Se conosci già l'identificatore, puoi saltare il primo passaggio.

• Integrazione

Compito e versione del pacchetto
        ↓
Scegliere la libreria
        ↓
Cercare nella documentazione
        ↓
Confrontare con il codice
        ↓
Modificare e verificare

Ogni passaggio si verifica per conto suo. Se l'agente ha scelto la libreria sbagliata, riscrivere bene l'esempio non rimedia. E una fonte giusta non dimostra che il codice sia integrato correttamente nella tua applicazione.

Prima dell'installazione

Ti servono Cursor o Claude Code, una connessione a Internet e un Node.js funzionante con npm/npx per lanciare il comando di setup. L'installatore ctx7 richiede Node.js 18 o successivo; in un ambiente nuovo installa una LTS ancora supportata.

• Requisiti CLI

Nel terminale:

node --version
npx --version

Se uno dei due comandi manca, sistema Node.js nell'ambiente da cui lancerai l'installatore. Controlla il terminale che usi davvero: macOS, Windows o WSL.

Se Context7 è già collegato, guarda la configurazione esistente prima di reinstallare. Con due voci che si autenticano in modo diverso non saprai più quale sta usando l'agente.

Collegare Claude Code

Esegui:

npx ctx7 setup --claude

L'installatore ti accompagna nell'accesso OAuth e ti fa scegliere la modalità di collegamento. Segui le indicazioni e completa l'autorizzazione nel browser. È il percorso che la documentazione di Context7 indica per Claude Code.

• Claude Code

Le modalità sono due. Con MCP l'agente riceve gli strumenti del server. Con CLI + Skills usa i comandi ctx7, guidato da uno skill. Per la richiesta di controllo scegli MCP, così vedi le chiamate con il loro nome. La configurazione da CLI è globale per impostazione predefinita; `--project` la limita al progetto corrente.

• Modalità

Poi apri Claude Code ed esegui `/mcp`: il comando elenca i server disponibili e il loro stato.

• Gestione MCP

Se hai scelto CLI + Skills, cerca nella cronologia chiamate effettive a ctx7 e non un server MCP. Le due modalità arrivano alla documentazione per strade diverse.

Collegare Cursor

Cursor ha un comando suo:

npx ctx7 setup --cursor

Completa l'autorizzazione e scegli MCP se vuoi ripetere la richiesta di controllo di questa guida.

• Guida Cursor

Per la configurazione manuale, apri le impostazioni MCP di Cursor. Il file globale è `~/.cursor/mcp.json`, quello di progetto `.cursor/mcp.json`. Context7 documenta questa configurazione HTTP:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

`YOUR_API_KEY` sta al posto della chiave del tuo account. L'esempio corrisponde alla configurazione ufficiale per i client. Se il file esiste già, aggiungi context7 dentro mcpServers e lascia le altre connessioni come sono.

• configurazione ufficiale

Non mettere una chiave personale in un repository condiviso. Per una prima configurazione manuale è più comodo il file personale. OAuth usa un altro indirizzo, `https://mcp.context7.com/mcp/oauth`: non mescolare i due metodi di autenticazione.

• Autenticazione

Di solito la configurazione automatica basta. Passa a quella manuale quando devi esaminare le impostazioni o gestirle da te.

Verificare l'uso effettivo

Parti da una libreria che conosci bene, perché lì una fonte sbagliata si nota prima. In un progetto che usa Zod, chiedi:

Trova la versione installata di Zod. Usa Context7 per capire come quella versione valida email e restituisce risultati senza eccezioni. Prima scegli la libreria, poi consulta la documentazione. Mostra identificatore, fonti e un breve esempio. Se la versione non è confermabile, dichiaralo. Non modificare file.

È una richiesta di esercizio; qui non riportiamo nessuna risposta del servizio. Se Zod non è installato, prendi un pacchetto del progetto che conosci e fai una piccola domanda sulla sua API.

Se l'identificatore l'hai fornito tu, è normale che `resolve-library-id` non compaia. Quello che deve esserci è una query riuscita sulla libreria giusta. E se lo strumento ha restituito un errore, una risposta sicura subito dopo non prova nulla.

Perché conta la versione

Indicare la versione restringe la domanda, ma devi ancora confrontarla con il materiale restituito. La CLI di Context7 offre identificatori con versione quando compaiono nei risultati di ricerca: scegli dalla lista che è stata davvero restituita.

• Librerie e versioni

Mettiamo che il progetto usi una vecchia major e che l'esempio sia scritto per quella nuova. Non migrare tutto per adattarti all'esempio. Verifica prima se la versione installata supporta l'operazione. Aggiornare una dipendenza è una decisione a parte, con effetti che vanno oltre questo compito.

Un ordine che funziona:

1. Identifica la versione nei file del progetto.
2. Trova l'operazione documentata.
3. Verifica la compatibilità dell'esempio.
4. Apporta una modifica limitata e controllala.

Se la versione resta da confermare, apri direttamente la documentazione ufficiale di quella versione o la sua guida di migrazione. Uno strumento che non restituisce nulla non significa che la libreria non abbia una soluzione.

Serve sempre scrivere use context7?

Scrivere `use context7` in modo esplicito è comodo per provare il collegamento. Il setup automatico può installare anche uno skill di documentazione.

• Opzioni di invocazione

Per il lavoro di tutti i giorni conviene scrivere quando l'agente deve ricorrervi:

Se la soluzione dipende da un'API esterna, identifica prima
la versione installata e cerca documentazione adatta con Context7.
Se la fonte manca o la versione non è confermata, dichiaralo
e consulta direttamente la documentazione ufficiale.

Questa regola è una nostra proposta. Puoi metterla in CLAUDE.md o nelle regole di progetto di Cursor. Dice quando cercare la documentazione e come procedere se la ricerca fallisce, senza imporre una ricerca per ogni correzione di testo.

• CLAUDE.md

Se non funziona

Guarda in quale fase la richiesta si è fermata. Reinstallare l'intero client raramente ti dice dov'è la causa.

Le prime quattro righe riguardano l'accesso, le ultime due la ricerca e l'uso del risultato. Per i dettagli tecnici consulta la guida alla risoluzione dei problemi.

• Risoluzione dei problemi

I Cloud Agents di Cursor usano una configurazione MCP separata. Il fatto che Context7 funzioni in locale non dice nulla sulla sua disponibilità nel cloud. Segui la guida Cloud Agents.

• guida Cloud Agents