Utiliser SQL MCP Server avec des modèles locaux

Important

Le serveur MCP (SQL Model Context Protocol) est disponible dans le générateur d’API de données version 1.7. Pour les dernières fonctionnalités et correctifs de bogues, utilisez la préversion 2.0.

Le serveur MCP (SQL Model Context Protocol) fonctionne avec n’importe quel client compatible MCP, pas seulement avec les services IA hébergés dans le cloud. Si votre environnement restreint l’accès au modèle de langage volumineux (LLM) cloud( courant dans les secteurs de la santé, de la défense, de la finance, de l’énergie et des maritimes), vous pouvez connecter un modèle local servi par le biais d’outils Ollama ou similaires. Ce guide traite de la configuration, de la configuration des métadonnées de champ et des modèles d’invite qui rendent les petits modèles locaux fiables.

Prerequisites

Interface CLI du générateur d’API de données installée et configurée avec au moins une entité. Installez l’interface CLI.
Ollama avec un modèle qui prend en charge l’appel d’outils (par exemple, qwen3:8b, llama3.1:8b).
Python 3.10+ avec les packages mcp et ollama.
Instance SQL Server en cours d’exécution avec des données.

Étape 1 : Configurer les métadonnées de champ

Les métadonnées de champ constituent l’étape de configuration la plus importante pour la précision du modèle local. Sans les noms de champs ni les descriptions, les agents ne voient que les noms d’entités et devinent incorrectement les noms de colonnes.

Avertissement

Ignorer cette étape produit un serveur MCP qui fonctionne techniquement, mais qui est fonctionnellement inutilisable par n’importe quel modèle qui lit les réponses de l’outil. Le modèle n’a aucune information sur vos colonnes.

Ajoutez votre entité avec une description, puis ajoutez des descriptions de champ qui incluent des valeurs valides pour les colonnes contraintes :

dab add ServerInventory \
  --source dbo.ServerInventory \
  --permissions "anonymous:read" \
  --description "SQL Server instance inventory with version, environment, and sizing data"

dab update ServerInventory \
  --fields.name InstanceName --fields.primary-key true \
  --fields.description "SQL Server instance name (e.g., YOURSERVER01)"

dab update ServerInventory \
  --fields.name Environment \
  --fields.description "Deployment environment. Valid values: Prod, Dev, Test, UAT"

Pour obtenir la référence CLI complète et les meilleures pratiques, notamment les valeurs contraintes, les descriptions des paramètres et les modèles de script, consultez Ajouter des descriptions aux entités.

Note

L’interface dab update CLI traite les virgules comme séparateurs d’arguments. Si votre description contient des virgules, modifiez dab-config.json directement à la place.

Étape 2 : Démarrer SQL MCP Server

dab start

SQL MCP Server écoute sur http://localhost:5000/mcp à l’aide du transport HTTP en streaming par défaut. Tout client qui implémente le protocole MCP peut se connecter à ce point de terminaison.

Étape 3 : Connecter votre modèle local

Créez un client MCP qui connecte votre modèle Ollama à SQL MCP Server. L’exemple de Python suivant utilise le sdk MCP Python et le package ollama.

Installer des dépendances

pip install mcp ollama

Harnais de Python minimal

import asyncio
import json
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
import ollama

MCP_URL = "http://localhost:5000/mcp"
MODEL = "qwen3:8b"

async def get_schema(session: ClientSession) -> str:
    """Call describe_entities and format results for the system prompt."""
    result = await session.call_tool("describe_entities", arguments={})
    entities = json.loads(result.content[0].text)
    lines = []
    for entity in entities.get("entities", []):
        fields = ", ".join(
            f"{f['name']} ({f.get('description', 'no description')})"
            for f in entity.get("fields", [])
        )
        lines.append(f"- {entity['name']}: {entity.get('description', '')}")
        if fields:
            lines.append(f"  Fields: {fields}")
    return "\n".join(lines)

async def run(user_question: str):
    async with streamable_http_client(MCP_URL) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Preinject schema into the system prompt
            schema_text = await get_schema(session)
            system_prompt = f"""You query a SQL database through MCP tools.

Available entities:
{schema_text}

Rules:
- Use the exact field names shown above.
- Answer count questions with the count only.
- Do not produce summaries unless asked.
- Do not invent example data. Only return data from tool responses.
- If no results, say "No results found" and stop.
"""
            # Get available tools for Ollama
            tools_result = await session.list_tools()
            ollama_tools = [
                {
                    "type": "function",
                    "function": {
                        "name": t.name,
                        "description": t.description or "",
                        "parameters": t.inputSchema,
                    },
                }
                for t in tools_result.tools
            ]

            messages = [
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": user_question},
            ]

            # Chat loop: let the model call tools until it produces a final answer
            while True:
                response = ollama.chat(
                    model=MODEL, messages=messages, tools=ollama_tools
                )
                msg = response["message"]
                messages.append(msg)

                if not msg.get("tool_calls"):
                    print(msg["content"])
                    break

                for tc in msg["tool_calls"]:
                    result = await session.call_tool(
                        tc["function"]["name"],
                        arguments=tc["function"]["arguments"],
                    )
                    messages.append(
                        {
                            "role": "tool",
                            "content": result.content[0].text,
                        }
                    )

asyncio.run(run("How many SQL 2019 servers are in production?"))

Ce harnais gère le cycle complet : préinjection de schéma, découverte d’outils, appel d’outils multitours et extraction finale des réponses. Ajustez MODEL et MCP_URL pour votre environnement.

Schéma de préinjection au démarrage

Les petits modèles locaux (de moins de 14 milliards de paramètres) produisent des appels d’outil plus fiables lorsque les métadonnées du schéma figurent dans l’invite système avant le début de la conversation. Au lieu de compter sur le modèle pour appeler describe_entities lui-même pendant la conversation, appelez-le au démarrage du harnais et injectez le résultat.

Pourquoi la préinjection importe

Approche	Comportement avec de petits modèles
Découverte dynamique	Le modèle doit d’abord décider d’appeler `describe_entities` , d’interpréter les résultats, puis d’appeler l’outil approprié avec des noms de champs corrects. Plusieurs points de défaillance.
Préinjection	Le modèle voit immédiatement les noms d’entités, les noms de champs et les descriptions. Corrigez les appels d’outils dès la première tentative.

L’exemple de harnais dans la section précédente illustre ce modèle. La fonction get_schema() appelle describe_entities une fois au démarrage et met le résultat en forme dans l’invite système.

Tip

Les grands modèles cloud (GPT-4o, Claude) déduisent généralement le schéma au cours de la conversation sans pré-injection. Ce modèle est le plus utile pour les modèles sous des paramètres 14B.

Limiter les réponses du modèle

Un modèle peut effectuer un appel d’outil correct, récupérer les données appropriées et produire une réponse incorrecte. Par exemple, un modèle auquel on demande « combien de serveurs de production ? » peut récupérer correctement 16 lignes, puis répondre par un résumé exécutif de 40 lignes contenant des exemples hallucinés au lieu du nombre 16.

Ajoutez des règles négatives explicites à votre invite système :

Rules:
- Answer count questions with the count only.
- Do not produce summaries unless the user asks for one.
- Do not invent example data. Only return data from tool responses.
- If a tool returns no results, say "No results found" and stop.

La fidélité dans l’appel aux outils et la discipline dans les réponses sont deux problèmes différents. DAB garantit une récupération précise des données par le biais de la couche outil. Votre harnais d’invite contrôle la façon dont le modèle présente les résultats.

Considerations

Sujet	Détails
Matériel	L’appel d’outils fonctionne sur du matériel modeste. Un modèle de paramètre 8B sur un GPU Nvidia grand public (ram vidéo de 8 Go) produit des résultats utiles. Il faut s’attendre à une latence de l’ordre de plusieurs dizaines de secondes par question, ce qui convient aux traitements par lots.
Batch vs. interactif	Les petits modèles conviennent bien au traitement par lots (rapports de performances, requêtes d’inventaire) où la tolérance de latence est plus élevée.
Disponibilité des outils	`aggregate_records` est disponible dans la version 2.0 preview et ultérieure uniquement. Dans la version 1.7.x, les requêtes de comptage et d’agrégation forcent le modèle à lire toutes les lignes correspondantes. Consultez la disponibilité des outils par version.
Transport	Les modèles locaux se connectent à `/mcp` via HTTP en streaming. Le transport d’entrée/sortie standard (stdio) est une alternative pour les configurations à processus unique.
Authentification	Pour le développement local, utilisez les autorisations `anonymous`. Pour la production, configurez l’authentification appropriée pour votre environnement.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-05-20