Requêtes MCP paramétrées personnalisées

La fonctionnalité la plus utile du MCP Toolbox for Databases n’est pas les outils préconstruits. C’est la capacité à définir exactement quelles requêtes un assistant IA peut exécuter, avec quels paramètres, via un fichier de configuration tools.yaml. Cela donne les bénéfices de l’exploration de données assistée par IA sans les risques de l’exécution SQL arbitraire.

Le problème du SQL arbitraire

Quand on donne à un assistant IA un accès execute_sql sans restriction, on accepte plusieurs risques :

• Coût : un IA curieux posant des questions générales sur de larges tables peut accumuler des frais. BigQuery facture par données scannées, et un seul SELECT * sur une grande table peut coûter plus que tout le budget mensuel pour les requêtes ad-hoc. Voir Contrôle des coûts de requêtes IA pour BigQuery MCP pour l’image complète des coûts.
• Sécurité : execute_sql peut techniquement exécuter des instructions INSERT, UPDATE, DELETE et DDL. L’IA pourrait modifier ou supprimer des données.
• Dérive de périmètre : l’IA pourrait explorer des tables auxquelles elle ne devrait pas accéder, même si elle en a la permission. Des données sensibles techniquement lisibles peuvent ne pas être appropriées pour l’exploration par IA.

Les requêtes paramétrées personnalisées adressent ces trois points en contraignant ce que l’IA peut demander et comment elle le demande.

La configuration tools.yaml

Le Toolbox lit les définitions d’outils depuis un fichier YAML. Chaque outil spécifie un template de requête avec des paramètres nommés que l’IA renseigne à l’exécution.

sources:
  my-bigquery-source:
    kind: bigquery
    project: your-project-id

tools:
  search_orders_by_date:
    kind: bigquery-sql
    source: my-bigquery-source
    description: Search orders within a date range
    statement: |
      SELECT
        order__id,
        order__customer_id,
        order__total_amount_usd,
        order__created_at
      FROM `your-project.ecommerce.mrt__sales__orders`
      WHERE order__created_at BETWEEN @start_date AND @end_date
      ORDER BY order__created_at DESC
      LIMIT 100
    parameters:
      - name: start_date
        type: string
        description: Start date (YYYY-MM-DD)
      - name: end_date
        type: string
        description: End date (YYYY-MM-DD)

  get_customer_metrics:
    kind: bigquery-sql
    source: my-bigquery-source
    description: Get aggregated metrics for a customer
    statement: |
      SELECT
        customer__id,
        customer__orders,
        customer__lifetime_value_usd,
        customer__last_ordered_at
      FROM `your-project.ecommerce.mrt__sales__customers`
      WHERE customer__id = @customer_id
    parameters:
      - name: customer_id
        type: string
        description: The customer ID to look up

Lancer le Toolbox avec la configuration personnalisée :

./toolbox --tools tools.yaml --stdio

Pourquoi ce pattern est important

Les descriptions des outils sont ce que l’IA lit pour décider quand et comment utiliser chaque outil. Quand un utilisateur demande « montre-moi les commandes de la semaine dernière », l’IA voit search_orders_by_date avec sa description et ses paramètres, construit la bonne plage de dates, et appelle l’outil. Elle n’écrit jamais de SQL — elle renseigne les paramètres du SQL qu’on a écrit.

Cela signifie :

On contrôle la forme de la requête. La clause LIMIT 100 est intégrée. L’IA ne peut pas accidentellement scanner des tables entières ou retourner des résultats non bornés. Les colonnes retournées sont celles qu’on a choisies, pas SELECT *.

On contrôle l’accès aux tables. L’IA ne peut interroger que les tables référencées dans les définitions d’outils. Si mrt__sales__orders et mrt__sales__customers sont les seules tables dans tools.yaml, ce sont les seules tables que l’IA touche — indépendamment des permissions BigQuery du compte de service.

On encode la logique métier. Les définitions de requêtes capturent la compréhension de l’équipe sur les données. Noms de colonnes, références de tables, patterns de jointures, conventions de filtres — tout encodé une fois, utilisé à chaque fois que l’IA a besoin de ces données.

On obtient un filet de sécurité sur les coûts. Chaque requête a une forme connue avec des patterns de scan connus. On peut estimer le coût maximum par appel d’outil et définir des attentes en conséquence.

Concevoir de bonnes définitions d’outils

Patterns qui fonctionnent bien :

Nommer les outils par ce que les utilisateurs demanderaient. search_orders_by_date est meilleur que query_orders_table. L’IA utilise le nom et la description pour faire correspondre l’intention de l’utilisateur au bon outil.

Toujours inclure des clauses LIMIT. Même si on fait confiance à la taille des données aujourd’hui, les tables grandissent. Un LIMIT protège contre les surprises de coûts futurs.

Exposer les tables de la couche mart, pas les données brutes. Pointer les outils vers les modèles mart où les données sont propres, agrégées et documentées — pas vers les tables sources brutes où les noms de colonnes sont cryptiques et la qualité des données incertaine.

Écrire les descriptions pour un lecteur IA. Le champ description est le seul guide de l’IA pour savoir quand utiliser l’outil. Être spécifique : « Obtenir les métriques agrégées pour un client » est meilleur que « Requête de données client ». Inclure ce que l’outil retourne, pas seulement ce qu’il fait.

Garder les types de paramètres simples. Des chaînes pour les dates, les IDs et les noms. Éviter les types complexes. L’IA génère les valeurs des paramètres à partir du langage naturel, donc plus l’interface est simple, moins il y a d’erreurs.

Pour les équipes

Un tools.yaml partagé commité dans le dépôt signifie que toute l’équipe bénéficie de la même interface de requête accessible par IA. Les nouveaux membres de l’équipe clonent le dépôt, configurent le Toolbox avec claude mcp add, et ont immédiatement accès au même ensemble de requêtes curatées.

C’est particulièrement précieux pour encoder les connaissances institutionnelles. « Comment calculons-nous la valeur à vie ? » est répondu par la requête dans get_customer_metrics. « Quelle est la bonne table pour les données de commandes ? » est répondu par la référence de table dans search_orders_by_date. Le tools.yaml devient une forme de documentation exécutable.

Pour les configurations multi-base de données (BigQuery plus Cloud SQL, ou BigQuery plus Spanner), on définit plusieurs sources dans le même fichier. L’IA obtient une interface unifiée sur toutes les bases de données sans connaître ni se soucier des différences d’infrastructure.