Connexion aux serveurs MCP d'Encore

Instructions

Choisir les serveurs

La plupart des agents bénéficient des deux : local lors de la construction, Encore Cloud pour les déploiements et la production. Configure ceux demandés par l'utilisateur. S'il n'a rien dit, demande.

La plupart des outils chargent les serveurs MCP au démarrage. Après en ajouter un, demande à l'utilisateur de redémarrer ou recharger son outil, puis vérifi que c'est connecté.

Serveur local

1. Depuis le répertoire racine de l'app, récupère l'ID de l'app :

   encore mcp start

   Il affiche MCP stdio Command: encore mcp run --app=<app-id> et une URL SSE. Utilise cet ID, pas l'id dans encore.app : les apps non sur Encore Cloud ont un id vide là et un ID local ici.

2. Ajoute le serveur à l'outil de l'utilisateur :

   • Claude Code : exécute depuis le répertoire racine de l'app :

     claude mcp add --transport stdio encore-local -- encore mcp run --app=<app-id>

     Cela l'ajoute pour ce projet, pour cet utilisateur. Ajoute --scope project pour le partager avec l'équipe via .mcp.json.

   • Cursor : ajoute à .cursor/mcp.json :

     {
       "mcpServers": {
         "encore-local": {
           "command": "encore",
           "args": ["mcp", "run", "--app=<app-id>"]
         }
       }
     }

   • VS Code : ajoute à .vscode/mcp.json. VS Code utilise servers, pas mcpServers :

     {
       "servers": {
         "encore-local": {
           "command": "encore",
           "args": ["mcp", "run", "--app=<app-id>"]
         }
       }
     }

   • Autres outils : un serveur stdio avec la commande encore mcp run --app=<app-id>, ou un serveur SSE à http://localhost:9900/sse?app=<app-id>.

   Si encore n'est pas sur le PATH de l'outil, ce qui est courant pour les éditeurs lancés depuis le dock ou le menu démarrage, utilise le chemin complet de which encore comme commande. Écris-le en entier, comme /Users/<user>/.encore/bin/encore : les fichiers de config n'étendent pas ~.

3. Vérifie : claude mcp list dans Claude Code, ou les paramètres MCP de l'outil, devrait afficher encore-local comme connecté. Puis appelle son outil get_services.

L'app n'a pas besoin de tourner. call_endpoint la démarre, et les outils de base de données démarrent les bases locales, ce qui nécessite Docker. Les traces n'existent que pour les requêtes que l'app locale a servies.

Serveur Encore Cloud

Le serveur est à https://api.encore.dev/mcp, en HTTP. Il n'est pas lié à une seule app : avec OAuth, il voit chaque app que l'utilisateur peut accéder.

1. Ajoute le serveur à l'outil de l'utilisateur :

   • Claude Code :

     claude mcp add --transport http --scope user encore-cloud https://api.encore.dev/mcp

     --scope user le rend disponible dans chaque projet. Omets-le pour l'ajouter à ce projet seulement.

   • Cursor : ajoute à ~/.cursor/mcp.json pour chaque projet, ou .cursor/mcp.json pour un :

     {
       "mcpServers": {
         "encore-cloud": {
           "url": "https://api.encore.dev/mcp"
         }
       }
     }

   • VS Code : ajoute à .vscode/mcp.json :

     {
       "servers": {
         "encore-cloud": {
           "type": "http",
           "url": "https://api.encore.dev/mcp"
         }
       }
     }

   • Autres outils : un serveur HTTP (streamable HTTP) à https://api.encore.dev/mcp.

2. Demande à l'utilisateur de s'authentifier. L'agent ne peut pas faire cette étape, car une personne approuve l'accès dans un navigateur :

   • Claude Code : l'utilisateur exécute /mcp, sélectionne encore-cloud, et choisit Authenticate.
   • Cursor, VS Code, et autres outils : l'utilisateur démarre la connexion pour encore-cloud depuis les paramètres MCP de l'outil, ou depuis l'invite que l'outil affiche.

3. Vérifie : appelle l'outil app_list. Il liste les apps de l'utilisateur.

Encore Cloud sans personne : clé API

Pour CI ou quand personne ne peut approuver l'accès dans un navigateur, utilise une clé API.

1. Demande à l'utilisateur d'en créer une dans le Cloud Dashboard : Settings de l'app > Access > API Keys. Les clés API commencent par enpk_. Elles sont différentes des auth keys sous Auth Keys, qui connectent le CLI (encore-login). Une clé appartient à une app, et le serveur ne liste que les outils que ses scopes permettent, alors choisis des scopes pour les outils dont l'agent a besoin.

2. Fais mettre la clé par l'utilisateur dans une variable d'environnement, comme ENCORE_API_KEY, et ajoute le serveur avec un en-tête Authorization :

   claude mcp add --transport http encore-cloud https://api.encore.dev/mcp \
     --header "Authorization: Bearer $ENCORE_API_KEY"

   Dans les autres outils, ajoute "headers": {"Authorization": "Bearer <api-key>"} à l'entrée du serveur, dans un fichier de config non commité, comme un au niveau utilisateur.

3. Vérifie avec un outil que les scopes de la clé permettent.

Dépannage

• Le serveur n'apparaît pas : l'outil n'a pas rechargé sa config MCP. Demande à l'utilisateur de le redémarrer.
• encore-local échoue au démarrage : exécute encore mcp run --app=<app-id> dans un terminal pour voir l'erreur. Généralement encore n'est pas sur le PATH de l'outil (utilise le chemin complet), ou l'ID de l'app est mauvais (exécute encore mcp start à nouveau).
• encore-cloud dit que l'authentification est requise : l'utilisateur n'a pas fini OAuth (étape 2), ou la clé API est mauvaise, expirée, ou supprimée.
• encore-cloud liste peu ou pas d'outils avec une clé API : les scopes de la clé ne les couvrent pas. Demande à l'utilisateur d'ajouter des scopes ou de créer une nouvelle clé.

Directives

• Ne demande jamais à l'utilisateur de coller une clé API dans le chat, et ne l'ajoute jamais. Garde-la dans une variable d'environnement ou un fichier de config hors du repository.
• Les outils MCP peuvent interroger des bases de données et appeler des endpoints. L'outil de l'utilisateur demande avant de les exécuter, selon ses paramètres d'approbation.
• encore llm-rules init --llm-rules=<tool> configure le serveur local avec les règles de codage d'Encore pour cursor, claudecode, vscode, ou zed, pour les apps sur Encore Cloud. Utilise-le quand l'utilisateur veut aussi les fichiers de règles.
• Docs : https://encore.dev/docs/mcp et https://encore.dev/docs/platform/cloud-mcp