Claude Code

La CLI claude mcp add de Claude Code modifie la configuration à ta place et garde l’enregistrement limité à un projet ou à un utilisateur. OAuth s’exécute dans ton navigateur la première fois que tu appelles un outil Engram. Pour le contexte du protocole, voir MCP.

Prérequis

Avant de commencer, vérifie que :

• Tu as un compte Engram sur app.engram.page.
• Au moins un coffre est synchronisé. Ouvre le plugin Obsidian ou l’application web et vérifie que des notes ont été synchronisées au cours du dernier jour.
• Tu peux te connecter via le navigateur. Le flux d’authentification MCP ouvre une fenêtre de navigateur.
• Si tu comptes utiliser une clé d’API plutôt qu’OAuth : les clés d’API demandent l’offre Pro. La connexion OAuth fonctionne sur toutes les offres, y compris Free, et c’est la méthode recommandée. Free et Starter ne peuvent ni créer ni utiliser de clés d’API.

Point de terminaison

https://mcp.engram.page

Configuration

1. Enregistre Engram avec la CLI de Claude Code.

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

--scope user rend Engram disponible dans tous les projets. Utilise plutôt --scope project pour limiter Engram au .mcp.json du dépôt courant.

Tu préfères éditer à la main ? Ajoute le bloc ci-dessous à ~/.claude.json (portée utilisateur) ou à .mcp.json à la racine du projet :

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

2. Recharge. Quitte ta session Claude Code actuelle et relance claude. Lance claude mcp list pour confirmer qu’Engram est enregistré. Il devrait apparaître avec le statut △ needs authentication.

Première authentification

Claude Code ne propose pas OAuth automatiquement. Dans une nouvelle session, lance /mcp, sélectionne engram, puis choisis Authenticate. Ton navigateur s’ouvre pour te connecter à Engram et approuver la connexion. Claude Code stocke le jeton et le réutilise ensuite. L’autorisation accordée est la portée complète mcp. Des portées granulaires par action figurent sur la feuille de route.

Dis à Claude comment l’utiliser

Ajoute l’extrait ci-dessous à ~/.claude/CLAUDE.md, le fichier d’instructions au niveau utilisateur de Claude Code. Il s’applique à tous les projets. Les surcharges par dépôt vont dans un CLAUDE.md au niveau du projet, à la racine du dépôt.

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.

Essaie

Une fois enregistré et authentifié, demande à Claude :

• Cherche dans mon coffre les notes sur le processus d'entretien d'ingénieur et résume les trois principales.
• Trouve tout ce que j'ai écrit sur les embeddings le mois dernier.

Claude appelle l’outil search d’Engram (ou get_note, write_note, etc.), ramène les résultats et répond en contexte. Si l’outil se déclenche, tout est en place.

Clé d’API au lieu d’OAuth

Pour les machines sans interface, la CI ou un coffre partagé, saute OAuth et lie la connexion à une clé d’API Engram. Génère-en une sur app.engram.page/settings/api-keys et envoie-la dans un en-tête Bearer.

La version rapide écrit la clé directement dans le fichier de configuration :

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

C’est acceptable pour --scope user (~/.claude.json reste sur ta machine). Ce ne l’est pas pour --scope project, car .mcp.json est fait pour être commité. Charge plutôt la clé depuis l’environnement.

Charger la clé depuis une variable d’environnement

Claude Code développe ${VAR} et ${VAR:-default} quand il lit .mcp.json. Pour les serveurs HTTP, l’expansion couvre les champs url et headers, ce qui est exactement l’endroit où se trouve une clé d’API. Commite ceci :

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

Seul le nom de la variable figure dans le dépôt. Chaque contributeur fournit sa propre clé, et Engram rattache chacune à son propre compte : un .mcp.json partagé n’implique donc jamais un coffre partagé.

Claude Code lit l’environnement avec lequel il a été lancé ; exporte donc la clé avant de démarrer claude :

export ENGRAM_API_KEY="engram_YOUR_KEY_HERE"

Pour une clé par dépôt, utilise direnv et garde la valeur dans un .envrc ignoré par git :

export ENGRAM_API_KEY="engram_YOUR_KEY_HERE"

Lance direnv allow une fois, puis démarre claude depuis ce répertoire.

Attention

Si la variable n’est pas définie, la configuration se charge quand même et Claude Code envoie la chaîne littérale Bearer ${ENGRAM_API_KEY}, qu’Engram rejette avec une 401. claude mcp list le signale :

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

Cherche d’abord cette ligne quand une configuration avec clé ne se connecte pas.

Deux choses changent dès qu’une clé est utilisée. Aucun navigateur ne s’ouvre à la première connexion, et /mcp ne propose plus Authenticate : définir un en-tête Authorization désactive entièrement le repli sur OAuth. Voir Configuration MCP → Authentification par clé d’API pour ce qu’une clé couvre et comment la renouveler.

Dépannage (spécifique à Claude Code)

• claude mcp list n’affiche pas engram. La commande a été exécutée dans une autre portée que prévu. Vérifie la présence de l’entrée dans ~/.claude.json (utilisateur) et .mcp.json (projet), puis relance claude mcp add avec le bon indicateur --scope.
• /mcp ne liste pas engram dans le sélecteur. Tu n’as pas quitté puis relancé la CLI après claude mcp add. Redémarre claude.
• L’option Authenticate ne fait rien, ou le navigateur ne s’ouvre jamais. Une session sans interface ou distante ne peut pas ouvrir de navigateur. Lance Claude Code sur une machine avec un navigateur de bureau, ou utilise plutôt une clé d’API.

Pour les échecs communs à tous les clients, voir Dépannage.

Révocation

Pour déconnecter Claude Code d’Engram :

1. Dans Claude Code, trouve l’entrée du connecteur ou du serveur MCP et supprime-la.
2. Dans Engram, ouvre ton compte → API Keys & Sessions et révoque la session correspondante.
3. Le jeton OAuth est invalidé côté serveur. Claude Code devra se réauthentifier pour se reconnecter.

Tu peux aussi retirer l’enregistrement localement avec claude mcp remove engram. Cela supprime l’entrée de configuration mais laisse le jeton côté serveur actif tant que tu ne le révoques pas dans Engram.

Prochaines étapes

MCPVue d'ensemble du protocole.

PortéesCe que couvre l'autorisation.

Toutes les intégrationsChoisis un autre client.