Claude Code

La CLI claude mcp add di Claude Code modifica la configurazione al posto tuo e mantiene la registrazione limitata al progetto o all’utente. OAuth parte nel tuo browser la prima volta che chiami uno strumento di Engram. Per il contesto sul protocollo, vedi MCP.

Prerequisiti

Prima di iniziare, verifica che:

• Hai un account Engram su app.engram.page.
• Almeno un archivio è sincronizzato. Apri il plugin di Obsidian o l’app web e controlla che le note siano state sincronizzate nell’ultimo giorno.
• Puoi accedere tramite browser. Il flusso di autenticazione MCP apre una finestra del browser.
• Se prevedi di usare una chiave API invece di OAuth: le chiavi API richiedono Pro. L’accesso con OAuth funziona su ogni piano, Free compreso, ed è il percorso consigliato. Free e Starter non possono creare né usare chiavi API.

Endpoint

https://mcp.engram.page

Configurazione

1. Registra Engram con la CLI di Claude Code.

claude mcp add --transport http --scope user engram https://mcp.engram.page

--scope user rende Engram disponibile in ogni progetto. Usa invece --scope project per limitare Engram al file .mcp.json del repo corrente.

Preferisci modificare a mano? Aggiungi il blocco qui sotto a ~/.claude.json (a livello utente) o a .mcp.json nella radice del progetto:

{
  "mcpServers": {
    "engram": {
      "url": "https://mcp.engram.page"
    }
  }
}

2. Ricarica. Esci dalla sessione corrente di Claude Code ed esegui di nuovo claude. Esegui claude mcp list per confermare che Engram sia registrato. Dovrebbe comparire con lo stato △ needs authentication.

Autenticazione al primo avvio

Claude Code non propone OAuth da solo. In una sessione nuova, esegui /mcp, seleziona engram, poi scegli Authenticate. Il browser si apre per accedere a Engram e approvare la connessione. Claude Code salva il token e lo riutilizza da lì in poi. La concessione è l’intero ambito mcp. Gli ambiti granulari per singola azione sono nella roadmap.

Di’ a Claude come usarlo

Aggiungi in coda lo snippet qui sotto a ~/.claude/CLAUDE.md, il file di istruzioni a livello utente di Claude Code. Vale per ogni progetto. Le eccezioni per singolo repo vanno in un CLAUDE.md a livello di progetto nella radice del repo.

Engram holds my personal notes — treat it as your long-term memory of me. Search it when a question depends on context I might have shared before. Before saving or updating a note, ask first.

Provalo

Una volta registrato e autenticato, chiedi a Claude:

• Cerca nel mio archivio le note sul processo di colloquio per ingegneri e riassumi le prime tre.
• Trova tutto ciò che ho scritto sugli embedding nell'ultimo mese.

Claude chiama lo strumento search di Engram (oppure get_note, write_note, ecc.), recupera i risultati e risponde nel contesto. Se lo strumento parte, hai finito.

Chiave API al posto di OAuth

Per macchine headless, CI o un archivio condiviso, salta OAuth e lega la connessione a una chiave API di Engram. Generane una su app.engram.page/settings/api-keys e inviala come intestazione Bearer.

La versione rapida scrive la chiave direttamente nel file di configurazione:

claude mcp add --transport http --scope user engram https://mcp.engram.page \
  --header "Authorization: Bearer engram_YOUR_KEY_HERE"

Va bene per --scope user (~/.claude.json resta sulla tua macchina). Non va bene per --scope project, perché .mcp.json è fatto per essere sottoposto a commit. Carica invece la chiave dall’ambiente.

Carica la chiave da una variabile d’ambiente

Claude Code espande ${VAR} e ${VAR:-default} quando legge .mcp.json. Per i server HTTP l’espansione copre i campi url e headers, che è proprio dove sta una chiave API. Fai il commit di questo:

{
  "mcpServers": {
    "engram": {
      "type": "http",
      "url": "https://mcp.engram.page",
      "headers": {
        "Authorization": "Bearer ${ENGRAM_API_KEY}"
      }
    }
  }
}

Nel repo c’è solo il nome della variabile. Ogni collaboratore fornisce la propria chiave, ed Engram associa ciascuna al proprio account, quindi un .mcp.json condiviso non implica mai un archivio condiviso.

Claude Code legge l’ambiente con cui è stato avviato, quindi esporta la chiave prima di avviare claude:

export ENGRAM_API_KEY="engram_YOUR_KEY_HERE"

Per una chiave per singolo repo, usa direnv e tieni il valore in un .envrc ignorato da git:

export ENGRAM_API_KEY="engram_YOUR_KEY_HERE"

Esegui direnv allow una volta, poi avvia claude da quella cartella.

Attenzione

Se la variabile non è impostata, la configurazione si carica lo stesso e Claude Code invia la stringa letterale Bearer ${ENGRAM_API_KEY}, che Engram rifiuta con un 401. claude mcp list lo segnala:

[Warning] [engram] mcpServers.engram: Missing environment variables: ENGRAM_API_KEY

Controlla prima quella riga quando una configurazione con chiave non si connette.

Con una chiave in uso cambiano due cose. Alla prima connessione non si apre nessun browser e /mcp non offre più Authenticate: impostare un’intestazione Authorization disattiva del tutto il ripiego su OAuth. Vedi Configurazione MCP → Autenticazione con chiave API per cosa copre una chiave e come ruotarla.

Risoluzione dei problemi (specifica di Claude Code)

• claude mcp list non mostra engram. Il comando è stato eseguito in un ambito diverso da quello previsto. Controlla la voce sia in ~/.claude.json (utente) sia in .mcp.json (progetto), poi riesegui claude mcp add con il flag --scope giusto.
• /mcp non elenca engram nel selettore. Non sei uscito e non hai riavviato la CLI dopo claude mcp add. Riavvia claude.
• L’opzione Authenticate non fa nulla, o il browser non si apre mai. Una sessione headless o remota non può aprire un browser. Esegui Claude Code su un host con un browser desktop, oppure usa una chiave API.

Per i problemi comuni a tutti i client, vedi Risoluzione dei problemi.

Revoca

Per scollegare Claude Code da Engram:

1. In Claude Code, trova la voce del connettore o del server MCP e rimuovila.
2. In Engram, apri il tuo account → API Keys & Sessions e revoca la sessione corrispondente.
3. Il token OAuth viene invalidato lato server. Claude Code dovrà autenticarsi di nuovo per riconnettersi.

Puoi anche eliminare la registrazione in locale con claude mcp remove engram. Così rimuovi la voce di configurazione ma il token lato server resta attivo finché non lo revochi in Engram.

Passi successivi

MCPPanoramica del protocollo.

AmbitiCosa copre la concessione.

Tutte le integrazioniScegli un altro client.