Synapse et MCP (Cursor / VS Code)

Synapse s'utilise principalement via le protocole MCP (Model Context Protocol). Ton IA dans Cursor, VS Code ou Claude Desktop appelle des outils DockSky pour lister tes machines, lire les noms de secrets et exécuter des commandes, sans jamais recevoir les mots de passe.

Le protocole de session (docksky_boot / load / close, modes d'écriture) est décrit dans Session MCP. Cette page couvre le branchement et Synapse.

:::info ChatGPT n'est pas un client MCP en V1 ChatGPT Free ne permet pas d'ajouter un serveur MCP custom (limite OpenAI). Chemin V1 : copier-coller le JSON. MCP live : Claude Desktop, Cursor, VS Code, Zed. Directory ChatGPT : plus tard, si assez d'utilisateurs. :::

Étape 1: Générer un token IA

Menu Vue → Paramètres
Section Accès IA (🤖)
Clique Générer un token
Copie le token immédiatement, il commence par dk_ai_ et ne sera plus affiché

Caractéristiques du token généré par l'app :

Quota journalier : plafond selon ton plan (Free 100 · Plus 300 · Pro 1000 appels/jour)
Validité : 30 jours par défaut (configurable à la création via l'API)
Un seul token actif à la fois (un nouveau token révoque l'ancien)

:::warning Ne partage jamais ton token Quiconque possède ton token peut agir sur tes données DockSky dans la limite de ses scopes. En cas de fuite, révoque-le dans Paramètres ou utilise le kill switch d'urgence (voir ci-dessous). :::

Étape 2: Configurer Cursor ou VS Code

Crée ou modifie le fichier de configuration MCP :

Cursor : .cursor/mcp.json à la racine du projet
VS Code : .vscode/mcp.json

{
  "servers": {
    "docksky": {
      "type": "http",
      "url": "https://api.docksky.fr/tda/mcp",
      "headers": {
        "X-AI-Token": "dk_ai_VOTRE_TOKEN_ICI"
      }
    }
  }
}

:::important Header d'authentification Utilise X-AI-Token, pas Authorization: Bearer. C'est le header attendu par l'API DockSky MCP. :::

Redémarre Cursor ou recharge la fenêtre VS Code pour que le serveur MCP soit détecté.

Étape 3: Préparer Synapse

Avant de demander à l'IA d'exécuter quoi que ce soit via synapse_exec (scope mcp:synapse, plan Pro):

Compte Bandeau avec Synapse activé (tous les plans, quotas selon Free/Pro)
Secrets enregistrés dans le Coffre Pilotage IA
Au moins une machine configurée

→ Voir Secrets et machines

Outils MCP Synapse disponibles

Endpoint : POST https://api.docksky.fr/tda/mcp (JSON-RPC : tools/list, tools/call)

Lecture (`mcp:read`)

Accessibles avec le token généré par défaut dans l'app :

Outil	Description
`synapse_list_machines`	Liste tes machines (slug, conteneurs, statut)
`synapse_get_machine`	Détail d'une machine par slug
`synapse_list_secrets`	Noms des secrets (sans valeurs)
`synapse_list_audit_logs`	Journal des exécutions (limit max 200)
`synapse_list_aliases`	Acronymes 3 lettres (GST, GLM…) + `hit_count`
`synapse_rtk_stats`	Observabilité unifiée : tokens RTK + hits acronymes (voir ci-dessous)

Écriture et exécution (`mcp:synapse`)

Requièrent le scope mcp:synapse, attribué aux comptes Pro / Équipage:

Outil	Description
`synapse_create_machine`	Crée une machine
`synapse_update_machine`	Met à jour label, conteneurs, statut…
`synapse_delete_machine`	Supprime une machine
`synapse_put_secret`	Enregistre ou met à jour un secret dans le coffre
`synapse_delete_secret`	Supprime un secret du coffre
`synapse_put_alias` / `synapse_delete_alias`	Gère un acronyme 3 lettres
`synapse_rename_alias`	Change le code sans perdre l'historique d'usage
`synapse_seed_default_aliases`	Installe les raccourcis de départ (GST, GLM, GDS…)
`synapse_mine_aliases` / `synapse_list_alias_suggestions`	Mine l'usage réel → suggestions
`synapse_accept_alias_suggestion` / `synapse_reject_alias_suggestion`	Valide ou refuse une suggestion
`synapse_exec`	Exécute une commande shell (ou un acronyme)

Paramètres de `synapse_exec`

Paramètre	Requis	Description
`machine`	Oui	Slug de la machine (ex. `mon-vps`)
`command`	Non*	Commande shell avec `{{SECRET}}` si besoin, ou un acronyme éventuellement suivi d'arguments (`@GLM --stat`) (*ou `alias`)
`alias`	Non*	Acronyme 3 lettres (ex. `GST`) — alternative à `command`
`container`	Non	Conteneur (défaut : `default_container` de la machine)
`timeout_seconds`	Non	1–300 s, défaut 30
`cwd`	Oui sur un agent	Répertoire POSIX absolu (obligatoire pour git sur `pc-fixe`, `pc-lenovo`, `vps-host`)

Exemple minimal :

{
  "name": "synapse_exec",
  "arguments": {
    "machine": "mon-vps",
    "command": "echo synapse_ok && hostname",
    "timeout_seconds": 15
  }
}

Le stdout est compacté côté API (RTK). Tu n'as pas à préfixer rtk dans la commande. Si le filtre ne s'applique pas, tu reçois le stdout brut.

RTK et acronymes (observabilité)

Deux économies complémentaires — une seule vérité côté doc et MCP :

Mécanisme	Ce que ça fait	Où on le voit
RTK (Rust Token Killer)	Compacte le stdout après l'exec (moins de tokens renvoyés à l'IA)	Transparent ; ne jamais préfixer `rtk`
Acronymes (GST, GLM, GDS…)	Raccourcissent le prompt (3 lettres au lieu de la commande longue)	`synapse_exec(alias="GST")` ou `command="GST"`

Acronymes : ce qu'il faut savoir

Passer des arguments. Un acronyme n'est pas figé : @GLM --stat exécute git log -5 --oneline --stat. Les arguments sont ajoutés en fin de commande.

Si la commande de l'alias enchaîne des étapes (|, &&, ;), un ajout en fin changerait son sens : Synapse refuse plutôt que de produire une commande fausse. Pour ces cas, place {} dans la commande de l'alias pour choisir où les arguments atterrissent :

synapse_put_alias(code="DBU", command="dotnet build {} -v q | tail -20")
synapse_exec(machine="mon-vps", command="@DBU App.csproj")
→ dotnet build App.csproj -v q | tail -20

Sans argument à l'appel, l'emplacement {} disparaît proprement.

Préfixe @ ou pas. Les deux marchent pour un code seul (GST ou @GST). Avec des arguments, la nuance compte : @XYZ foo sur un code inconnu est une erreur franche, alors que XYZ foo est traité comme une commande shell littérale. Le @ est donc la forme à privilégier quand tu veux être sûr de viser un acronyme.

Les acronymes ne s'enchaînent pas. La commande d'un alias ne peut pas commencer par un autre code : synapse_put_alias(code="XYZ", command="GST") est refusé, car GST serait exécuté tel quel par le shell.

Renommer plutôt que recréer. synapse_rename_alias(code="GPO", new_code="GPM") conserve hit_count et last_used_at. Supprimer puis recréer repart de zéro et fausse les statistiques.

Codes suggérés. Le mineur suit la convention des raccourcis de départ : initiales des mots utiles, complétées par une consonne du dernier mot — git status → GST, git diff → GDF, docker ps → DPS. Flags, chemins et valeurs de flags sont ignorés. En cas de collision, seule la dernière lettre change (GST pris → GSA), pour que le code reste lisible.

Deux garde-fous complètent la suggestion : les codes des raccourcis de départ restent réservés même si tu ne les as pas encore installés, et une courte liste de codes malheureux n'est jamais proposée.

Comptage des hits. Un hit est enregistré une fois la commande réellement exécutée. Un appel refusé en amont (quota dépassé, machine inconnue, cwd invalide) ne gonfle pas les statistiques d'adoption.

`synapse_rtk_stats` — lecture unifiée

L'outil renvoie dans la même réponse :

totals — commandes, RTK appliqué, saved_tokens (stdout)
aliases — total_hits, hot_code, top codes, tokens_saved_estimate (heuristique prompt : chars économisés ÷ 4)
combined — résumé d'un coup d'œil : rtk_saved_tokens + alias_total_hits + alias_prompt_tokens_estimate

Paramètres : group_by=user|day, days=N, filter_user_id (admin).

Dans DockSky App : Paramètres → section Synapse / tokens RTK (ligne totale + hits acronymes) ; la console Pilotage IA affiche aussi le tableau de bord session.

Règles à retenir

Deploy API VPS (git pull / restart) : SSH, pas synapse_exec sur l'hôte
Fail-open RTK : pas de filtre match → stdout brut (normal)
docker ps --format '{{.Names}}' : {{.Names}} n'est pas un secret Vault

Exemple concret : lister les bases MySQL

Cas réel testé en production : l'IA interroge MySQL sur ton VPS sans jamais voir le mot de passe root.

Prérequis

Élément	Exemple
Secret dans le coffre	`MYSQL_ROOT`
Machine (slug)	`mon-vps`
Conteneur autorisé	`ma_base_mysql`

La commande s'exécute dans le conteneur (docker exec est géré par Synapse côté serveur). Tu n'as pas à préfixer docker exec … dans command.

Appel MCP (JSON-RPC)

POST https://api.docksky.fr/tda/mcp avec header X-AI-Token: dk_ai_…

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "synapse_exec",
    "arguments": {
      "machine": "mon-vps",
      "container": "ma_base_mysql",
      "command": "mysql -uroot -p\"{{MYSQL_ROOT}}\" -e \"SHOW DATABASES\""
    }
  }
}

La commande shell (placeholders)

mysql -uroot -p"{{MYSQL_ROOT}}" -e "SHOW DATABASES"

:::tip Guillemets autour du secret Si ton mot de passe contient des caractères spéciaux shell (&, !, espaces…), entoure le placeholder de guillemets doubles : -p"{{MYSQL_ROOT}}". Sans guillemets, sh peut interpréter une partie du MDP comme une commande séparée. :::

Réponse typique (extrait)

{
  "success": true,
  "exit_code": 0,
  "stdout": "Database\napollo\ndocksky_api\ntda_assistant\n…",
  "machine": "mon-vps",
  "container": "ma_base_mysql",
  "command_template": "mysql -uroot -p\"{{MYSQL_ROOT}}\" -e \"SHOW DATABASES\""
}

Le champ command_template est ce qui est journalisé: jamais la valeur résolue de MYSQL_ROOT.

Équivalent API REST (hors MCP)

curl -sS -X POST 'https://api.docksky.fr/synapse/exec' \
  -H "Authorization: Bearer $TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": "mon-vps",
    "container": "ma_base_mysql",
    "command": "mysql -uroot -p\"{{MYSQL_ROOT}}\" -e \"SHOW DATABASES\""
  }'

Scopes du token IA

À la génération dans Paramètres → Accès IA, les scopes sont calculés selon ton plan et affichés dans l'app :

Plan	Scopes typiques
Free	`mcp:read`, `mcp:write`
Plus (bientôt)	`mcp:read`, `mcp:write`
Pro / Équipage	`mcp:read`, `mcp:write`, `mcp:synapse`

Scope	Outils débloqués
`mcp:read`	Contexte projet, facettes, lecture roadmap, `synapse_list_*`, `synapse_rtk_stats`
`mcp:write`	`update_`, `add_`, Knowledge, idées, facettes, packs, `docksky_close`, `ui_present`
`mcp:synapse`	`synapse_exec`, création/suppression machines et secrets
`mcp:admin`	profil, settings, create/delete project, `delete_facet`, `today_dashboard`

:::info Token Pro = Synapse actif Avec un plan Pro, régénère ton token une fois si tu l'avais créé avant l'activation des scopes persistés. Tu dois voir mcp:synapse dans Paramètres → Accès IA, et synapse_exec dans tools/list côté Cursor. :::

Tu peux aussi passer des scopes explicites à la création via l'API POST /tda/ai/tokens (champ scopes).

Exemple de session avec Cursor

Une fois MCP configuré et le scope mcp:synapse actif :

Toi : Liste mes machines Synapse et les secrets disponibles.

IA  : [appelle synapse_list_machines et synapse_list_secrets]

Toi : Sur mon-vps, liste les bases MySQL du conteneur ma_base_mysql avec le secret MYSQL_ROOT.

IA  : [appelle synapse_exec avec mysql -uroot -p"{{MYSQL_ROOT}}" -e "SHOW DATABASES"]

Tu retrouves l'exécution dans Paramètres → Journal Synapse.

Rate limiting

Limite	Valeur
Exécutions Synapse	30 / minute par utilisateur
Appels MCP (IP normale)	200 / minute
Appels MCP (IP de confiance)	400 / minute, après un premier appel MCP valide avec ton token, ton IP est mémorisée 24 h dans Redis (whitelist temporaire, pas d'auto-ban sur le trafic MCP)
Quota token IA	Plafond plan (100 / 300 / 1000 par jour) — affiché dans Paramètres → Accès IA

Au-delà, l'API renvoie HTTP 429 avec Retry-After.

Révocation et urgence

Situation	Action
Révocation normale	Paramètres → Accès IA → Révoquer le token
Fuite de token, urgence	`POST https://api.docksky.fr/tda/ai/tokens/emergency-revoke?token=dk_ai_…` (sans login, le token lui-même suffit)

Erreurs fréquentes

Message	Cause probable
`Pilotage IA Synapse réservé au plan Pro`	Token sans scope `mcp:synapse` (passe Pro ou Équipage)
`Secret manquant pour le placeholder {{X}}`	Secret non enregistré dans le coffre
`Machine introuvable`	Slug incorrect ou machine supprimée
`Conteneur non autorisé`	Conteneur absent de la liste de la machine
`Synapse rate limit exceeded`	Trop d'exec en 1 minute, attends 60 s
Outil `synapse_exec` absent de `tools/list`	Scope `mcp:synapse` manquant sur le token
`Quota journalier IA atteint`	Plafond du plan dépassé — attends le lendemain ou passe Plus/Pro

Voir aussi

Vue d'ensemble Pilotage IA
Secrets et machines
Utiliser DockSky avec ton IA, méthodes copier-coller et contexte
Partage de contexte, contexte projet sans MCP

Étape 1: Générer un token IA​

Étape 2: Configurer Cursor ou VS Code​

Étape 3: Préparer Synapse​

Outils MCP Synapse disponibles​

Lecture (mcp:read)​

Écriture et exécution (mcp:synapse)​

Paramètres de synapse_exec​

RTK et acronymes (observabilité)​

Acronymes : ce qu'il faut savoir​

synapse_rtk_stats — lecture unifiée​

Règles à retenir​

Exemple concret : lister les bases MySQL​

Prérequis​

Appel MCP (JSON-RPC)​

La commande shell (placeholders)​

Réponse typique (extrait)​

Équivalent API REST (hors MCP)​

Scopes du token IA​

Exemple de session avec Cursor​

Rate limiting​

Révocation et urgence​

Erreurs fréquentes​

Voir aussi​