Outils de langage de manipulation des données (DML) dans SQL MCP Server

Important

SQL MCP Server est en préversion et cette documentation et l’implémentation du moteur est susceptible de changer pendant cette période d’évaluation.

SQL MCP Server expose six outils DML (Data Manipulation Language) aux agents IA. Ces outils fournissent une surface CRUD typée pour les opérations de base de données : création, lecture, mise à jour et suppression d’enregistrements, ainsi que l’exécution de procédures stockées. Tous les outils respectent le contrôle d’accès en fonction du rôle (RBAC), les autorisations d’entité et les stratégies définies dans votre configuration.

Qu’est-ce que les outils DML ?

Les outils DML (Data Manipulation Language) gèrent les opérations de données : création, lecture, mise à jour et suppression d’enregistrements, ainsi que l’exécution de procédures stockées. Contrairement à DDL (Data Definition Language) qui modifie le schéma, DML fonctionne exclusivement sur le plan de données dans les tables et vues existantes.

Les six outils DML sont les suivants :

• describe_entities - Découvre les entités et les opérations disponibles
• create_record - Insère de nouvelles lignes
• read_records - Requêtes des tables et des vues
• update_record - Modifie les lignes existantes
• delete_record - Supprime les lignes
• execute_entity - Exécute des procédures stockées

Lorsque les outils DML sont activés globalement et pour une entité, SQL MCP Server les expose via le protocole MCP. Les agents n’interagissent jamais directement avec votre schéma de base de données : ils fonctionnent via la couche d’abstraction du générateur d’API de données.

Les outils

réponse liste_outils

Lorsqu’un agent appelle list_tools, SQL MCP Server retourne :

{
  "tools": [
    { "name": "describe_entities" },
    { "name": "create_record" },
    { "name": "read_records" },
    { "name": "update_record" },
    { "name": "delete_record" },
    { "name": "execute_entity" }
  ]
}

décrire_les_entités

Retourne les entités disponibles pour le rôle actuel. Chaque entrée inclut les noms de champs, les types de données, les clés primaires et les opérations autorisées. Cet outil n’interroge pas la base de données. Au lieu de cela, il lit à partir de la configuration en mémoire générée à partir de votre fichier de configuration.

{
  "entities": [
    {
      "name": "Products",
      "description": "Product catalog with pricing and inventory",
      "fields": [
        {
          "name": "ProductId",
          "type": "int",
          "isKey": true,
          "description": "Unique product identifier"
        },
        {
          "name": "ProductName",
          "type": "string",
          "description": "Display name of the product"
        },
        {
          "name": "Price",
          "type": "decimal",
          "description": "Retail price in USD"
        }
      ],
      "operations": [
        "read_records",
        "update_record"
      ]
    }
  ]
}

Note

Les options d’entité utilisées par l’un des outils CRUD et d’exécution DML proviennent directement de describe_entities. La description sémantique interne attachée à chaque outil applique ce flux en deux étapes.

créer_enregistrement

Crée une ligne dans une table. Nécessite une autorisation de création sur l’entité pour le rôle actuel. L’outil valide les entrées par rapport au schéma d’entité, applique les autorisations au niveau du champ, applique des stratégies de création et retourne l’enregistrement créé avec toutes les valeurs générées.

lire_enregistrements

Interroge une table ou une vue. Prend en charge le filtrage, le tri, la pagination et la sélection de champs. L’outil génère un SQL déterministe à partir de paramètres structurés, applique des autorisations de lecture et des projections de champs et applique des stratégies de sécurité au niveau des lignes.

Les résultats de read_records sont automatiquement mis en cache à l’aide du système de mise en cache du générateur de l'API de données. Vous pouvez configurer la durée de vie (TTL) du cache globalement ou par entité pour réduire la charge de la base de données.

mise_à_jour_enregistrement

Modifie une ligne existante. Nécessite la présence de la clé primaire et des champs pour effectuer une mise à jour. L’outil valide la clé primaire, applique des autorisations et des stratégies de mise à jour et met à jour uniquement les champs que le rôle actuel peut modifier.

supprimer_enregistrement

Supprime une ligne existante. Nécessite la clé primaire. L’outil valide la clé primaire, applique des autorisations et des stratégies de suppression et effectue une suppression sécurisée avec prise en charge des transactions.

Avertissement

Certains scénarios de production désactivent cet outil globalement pour limiter largement les modèles.

exécuter_entité

Exécute une procédure stockée. Prend en charge les paramètres d’entrée et les résultats de sortie. L’outil valide les paramètres d’entrée par rapport à la signature de procédure, applique les autorisations d’exécution et transmet les paramètres en toute sécurité.

Configuration du runtime

Configurez globalement les outils DML dans la section runtime de votre dab-config.json:

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "path": "/mcp",
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true
      }
    }
  }
}

Utilisation de l’CLI

Définissez des propriétés individuellement à l’aide de l’interface CLI du générateur d’API de données :

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true

Désactivation des outils

Lorsque vous désactivez un outil au niveau du runtime, il n’apparaît jamais aux agents, quelles que soient les autorisations d’entité ou la configuration du rôle. Ce paramètre est utile lorsque vous avez besoin de limites opérationnelles strictes.

Scénarios courants

• Désactiver delete-record pour empêcher la perte de données en production
• Désactiver create-record pour les points de terminaison de rapports en lecture seule
• Désactiver execute-entity lorsque les procédures stockées ne sont pas utilisées

Lorsqu’un outil est désactivé globalement, l’outil est masqué de la list_tools réponse et ne peut pas être appelé.

Paramètres de l’entité

Les entités participent automatiquement à MCP, sauf si vous les limitez explicitement. La dml-tools propriété existe afin que vous puissiez exclure une entité de MCP ou limiter ses fonctionnalités, mais vous n’avez pas besoin de définir quoi que ce soit pour une utilisation normale.

{
  "entities": {
    "Products": {
      "mcp": {
        "dml-tools": true
      }
    },
    "SensitiveData": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

Si vous ne spécifiez pas mcp.dml-tools pour une entité, elle utilise true par défaut lorsque MCP est activé globalement.

Contrôle affiné

Vous pouvez désactiver des outils spécifiques pour des entités individuelles :

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": {
          "create-record": true,
          "read-records": true,
          "update-record": false,
          "delete-record": false
        }
      }
    }
  }
}

Cette configuration permet aux agents de créer et lire des journaux d’audit, mais empêche la modification ou la suppression.

Intégration de RBAC

Chaque opération d’outil DML applique vos règles de contrôle d’accès en fonction du rôle. Le rôle d’un agent détermine quelles entités sont visibles, quelles opérations sont autorisées, quels champs sont inclus et si les stratégies au niveau des lignes s’appliquent.

Si le rôle n'autorise que le droit anonymous de lecture sur Products:

• describe_entities ne montre que read_records dans les opérations
• create_record, update_recordet delete_record ne sont pas disponibles
• Seuls les champs autorisés pour anonymous apparaissent dans le schéma

Configurez les rôles dans votre dab-config.json:

{
  "entities": {
    "Products": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["ProductId", "ProductName", "Price"],
                "exclude": ["Cost"]
              }
            }
          ]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Contenu connexe

• Vue d’ensemble de SQL MCP Server
• Ajout de descriptions sémantiques à SQL MCP Server
• Informations de référence sur la configuration du générateur d’API de données (DAB)
• Déployer SQL MCP Server sur Azure Container Apps