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

Le serveur MCP (SQL Model Context Protocol) expose sept 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, agrégation de données, 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, agrégation de données, 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 sept 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
• aggregate_records - Effectue des requêtes d’agrégation

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" },
    { "name": "aggregate_records" }
  ]
}

décrire_les_entités

Retourne les entités disponibles pour le rôle actuel. Chaque entrée inclut des noms de champs, des descriptions et des 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.

Paramètres

Exemple de requête

{
  "method": "tools/call",
  "params": {
    "name": "describe_entities",
    "arguments": {
      "entities": ["Products"]
    }
  }
}

Exemple de réponse

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

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.

Paramètres

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.

Paramètres

Réponse de pagination

Lorsque d’autres résultats sont disponibles, la réponse inclut un after curseur. Transmettez cette valeur en tant que after paramètre dans la requête suivante pour extraire la page suivante.

{
  "value": [ ... ],
  "after": "W3siRW50aXR5TmFtZ..."
}

La présence du champ indique que d’autres after pages existent. En l'absence de after, vous avez atteint la dernière page.

Opérations JOIN

L’outil read_records est conçu pour une seule table ou vue. Par conséquent, les opérations JOIN ne sont pas prises en charge dans cet outil. Cette conception permet d’isoler la responsabilité, d’améliorer les performances et de limiter l’impact sur la fenêtre de contexte de votre session.

Toutefois, les opérations JOIN ne sont pas un cas de périphérie, et le générateur d’API de données (DAB) prend déjà en charge les requêtes sophistiquées via le point de terminaison GraphQL. Pour les requêtes plus complexes, nous vous recommandons d’utiliser une vue au lieu d’une table. Vous pouvez également utiliser l’outil execute_entity pour exécuter des procédures stockées pour encapsuler des requêtes paramétrables.

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.

Paramètres

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.

Paramètres

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é.

Paramètres

agréger_enregistrements

Effectue des requêtes d’agrégation sur des tables et des vues. Prend en charge les fonctions d’agrégation courantes telles que le nombre, la somme, la moyenne, le minimum et le maximum. 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.

Paramètres

Exemple : COUNT avec GROUP BY et HAVING

{
  "method": "tools/call",
  "params": {
    "name": "aggregate_records",
    "arguments": {
      "entity": "Todo",
      "function": "count",
      "field": "*",
      "groupby": ["UserId"],
      "having": { "gt": 2 }
    }
  }
}

L’outil aggregate-records peut être configuré en tant que booléen ou en tant qu’objet avec d’autres paramètres :

{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

La query-timeout propriété spécifie la durée d’exécution maximale en secondes (plage : 1 à 600). Ce paramètre permet d’empêcher les requêtes d’agrégation longues de consommer des ressources excessives.

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,
        "aggregate-records": true
      }
    }
  }
}

Chaque propriété outil sous runtime.mcp.dml-tools accepte true ou false. L’outil aggregate-records prend également en charge un format d’objet avec enabled et query-timeout:

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

Pour activer ou désactiver tous les outils DML à la fois, définis "dml-tools" sur true ou false.

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
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true
dab configure --runtime.mcp.dml-tools.aggregate-records.query-timeout 30

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
• Désactiver aggregate-records lorsque les requêtes d’agrégation ne sont pas nécessaires

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 mcp propriété d’une entité contrôle sa participation MCP. Utilisez le format d’objet pour le contrôle explicite.

Format d’objet

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

Si vous ne spécifiez mcp pas d’entité, les outils DML sont activés par défaut lorsque MCP est activé globalement.

Outils personnalisés pour les procédures stockées

Pour les entités de procédure stockée, utilisez la custom-tool propriété pour inscrire la procédure en tant qu’outil MCP nommé :

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id"
      },
      "mcp": {
        "custom-tool": true
      }
    }
  }
}

Étendue du contrôle par outil

Les bascules par outil sont configurées uniquement au niveau du runtime global sous runtime.mcp.dml-tools.

Au niveau de l’entité, mcp est une porte booléenne ou un objet avec les propriétés dml-tools et custom-tool.

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

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

Un outil est disponible uniquement si activé globalement et si l’entité autorise les outils DML.

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": [
            {
              "action": "*"
            }
          ]
        }
      ]
    }
  }
}

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)
• Configuration MCP au niveau de l’entité
• Configuration MCP du runtime
• Deploy SQL MCP Server sur Azure Container Apps
• Nouveautés du Générateur d’API de données version 2.0