Connexion d’un client MCP

hs-sql-agent expose un point de terminaison MCP Streamable HTTP à l’adresse /mcp. Avec l’interface d’administration intégrée, le parcours normal ne consiste pas à reconstruire manuellement l’endpoint et l’en-tête : hs-sql-agent génère la configuration à copier juste après la création de la clé.

Parcours recommandé

1. Créer la clé MCP

   Ouvrez Runtime → MCP Keys, créez une clé pour la base de données cible et n’autorisez que les outils et tables nécessaires au client.

2. Utiliser la boîte Save and connect affichée une seule fois

   Après Issue Key, hs-sql-agent affiche immédiatement la clé en clair et les configurations client générées. C’est le seul moment où l’interface d’administration peut fournir cette valeur en clair.

3. Choisir le client et copier sa configuration

   Sélectionnez Claude Desktop, Cursor, Visual Studio Code ou Generic HTTP, puis cliquez sur le bouton Copy … config correspondant. Le JSON copié contient déjà le point de terminaison MCP et l’en-tête X-MCP-Server-Key.

4. Coller, connecter et vérifier DML si nécessaire

   Collez le JSON dans la configuration du client MCP et connectez-le. Si la clé peut exécuter DML, testez les chemins de refus et d’acceptation de l’Elicitation par formulaire avant la production.

Point de terminaison public utilisé dans la configuration générée

L’URL intégrée à la configuration client provient du paramètre serveur suivant :

{
  "Mcp": {
    "PublicEndpoint": "https://sql-agent.example.com/mcp"
  }
}

La variable d’environnement équivalente est Mcp__PublicEndpoint. La configuration Compose fournie transmet MCP_PUBLIC_ENDPOINT vers ce paramètre.

Avant de créer une clé de production, configurez l’URL que le client MCP peut réellement joindre, avec /mcp. L’interface d’administration lit cette valeur via GET /api/runtime/client-config et l’insère directement dans la configuration copiée.

Configurations générées par la boîte de dialogue

Après Issue, Rotate ou Duplicate, l’interface actuelle propose quatre formats :

• Claude Desktop — entrée mcpServers en HTTP direct ;
• Cursor — entrée HTTP mcpServers ;
• Visual Studio Code — entrée servers ;
• Generic HTTP — objet de connexion Streamable HTTP.

Chaque format contient le point de terminaison configuré et la nouvelle clé MCP. Dans le parcours normal, il n’est pas nécessaire de reconstruire ce JSON manuellement.

Référence Generic / authentification manuelle

Si un client exige une enveloppe de configuration différente, utilisez la sortie Generic HTTP comme référence. Au niveau du protocole, l’authentification utilise :

X-MCP-Server-Key: <MCP key>

La compatibilité DML doit être vérifiée séparément

Le fait qu’un client se connecte correctement à /mcp ne prouve pas qu’il sait gérer l’approbation DML.

execute_dml_sql et les DML Custom Tools publiés exigent l’Elicitation par formulaire. Avant d’autoriser DML en production, testez la version exacte du client installée et vérifiez les deux scénarios :

1. Refuser une demande d’Elicitation et confirmer qu’aucune modification n’est validée.
2. Accepter une demande d’Elicitation et confirmer que seule la modification approuvée aboutit.

Pour continuer