Synapse et MCP (Cursor / VS Code)

Synapse s'utilise principalement via le protocole MCP (Model Context Protocol). Ton IA dans Cursor ou VS Code 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.

É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 : 500 appels par jour
Validité : 90 jours
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 :

Plan Pro actif
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)

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

Requièrent le scope mcp:synapse en plus du plan Pro :

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_exec`	Exécute une commande shell

Paramètres de `synapse_exec`

Paramètre	Requis	Description
`machine`	Oui	Slug de la machine (ex. `docksky-vps`)
`command`	Oui	Commande shell avec `{{SECRET}}` si besoin
`container`	Non	Conteneur (défaut : `default_container` de la machine)
`timeout_seconds`	Non	1–300 s, défaut 30

Exemple minimal :

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

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)	`docksky-vps`
Conteneur autorisé	`ctn_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": "docksky-vps",
      "container": "ctn_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": "docksky-vps",
  "container": "ctn_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": "docksky-vps",
    "container": "ctn_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 / Plus	`mcp:read`
Pro	`mcp:read`, `mcp:write`, `mcp:synapse`

Scope	Outils débloqués
`mcp:read`	Contexte TDA, facettes, `synapse_list_*`
`mcp:write`	`update_`, `add_` sur la base TDA
`mcp:synapse`	`synapse_exec`, machines, secrets (`synapse_put/delete_secret`…)

:::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 docksky-vps, liste les bases MySQL du conteneur ctn_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	500 / jour par défaut (configurable à la création)

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`	Plan gratuit — passe au Pro
`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`	500 appels MCP/jour dépassés — attends le lendemain

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 TDA 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​

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​