Comment fonctionne le serveur MCP de Guida

20 janvier 2025 · 8 min de lecture ·

technical

Guida inclut un serveur Model Context Protocol (MCP) intégré. C’est ce qui permet à une IA externe — Claude Code, Cursor ou tout client compatible MCP — de contrôler le navigateur. C’est le pont entre « je veux scraper cette page » dit à une IA et les vraies requêtes DOM, clics et opérations de stockage qui rendent cela possible.

Cet article est une plongée technique dans son fonctionnement. Nous couvrirons le protocole, la couche de transport, l’enregistrement des outils et le modèle de sécurité à trois couches qui garantit que l’IA ne peut rien faire sans votre connaissance et votre accord.

Ce qu’est MCP, rapidement

MCP est un protocole JSON-RPC qui connecte des modèles IA à des outils externes. L’IA envoie une requête comme « appelle l’outil Navigate avec url: https://example.com », le serveur l’exécute et renvoie le résultat. Le modèle ne touche jamais directement le navigateur : il voit seulement le contrat d’entrée/sortie de l’outil.

Le protocole définit trois primitives :

Tools — fonctions que l’IA peut appeler : naviguer, cliquer, extraire, etc.
Resources — données que l’IA peut lire : onglets ouverts, contenu de page
Prompts — modèles réutilisables pour des opérations courantes

Guida implémente les primitives tools et resources. Il expose plus de 100 outils couvrant automatisation du navigateur, stockage de données, recherche et plus encore.

Transport : HTTP local

MCP prend en charge plusieurs transports. Guida utilise un transport HTTP local : le serveur lance une instance Kestrel intégrée sur http://127.0.0.1:9315.

Le choix de HTTP plutôt que stdio a des raisons pratiques. Guida est une application desktop WPF, pas un outil CLI. Il n’y a pas de stdin/stdout à relier. HTTP permet aussi à des clients MCP externes de se connecter pendant que l’interface navigateur, l’état des autorisations, l’historique des tâches et les panneaux d’espace de travail restent visibles.

Pour les clients HTTP streamable actuels, l’endpoint utile est la racine du serveur :

http://127.0.0.1:9315/

La négociation suit le standard MCP : le client initialise, le serveur renvoie ses capacités, puis le client découvre les outils et commence les appels.

Client → initialize
         {"jsonrpc": "2.0", "method": "initialize", ...}

Server → capabilities
         {"jsonrpc": "2.0", "id": 1, "result": {...}}

Client → tools/list
Client → tools/call

Enregistrement des outils

Les outils sont enregistrés dans McpServerService.cs avec le SDK MCP .NET. Chaque outil a un nom, une description, un schéma JSON pour les paramètres et un handler asynchrone.

Quelques outils représentatifs parmi les plus de 100 disponibles :

Outil	Description
`Navigate`	Navigue l’onglet actif vers une URL
`Click`	Clique sur un élément par sélecteur CSS
`GetElements`	Interroge les éléments DOM et extrait des attributs
`Screenshot`	Capture le viewport visible en PNG
`ExecuteScript`	Exécute un script `g.*` dans le moteur de scripting de l’application
`StoreGet` / `StorePut`	Lit/écrit dans le stockage de l’espace de travail
`QueueEnqueue` / `QueueDequeue`	Gère les files de travail
`SearchQuery`	Recherche plein texte dans les documents indexés

Sous le capot, la plupart des outils délèguent aux mêmes services que l’API de scripting g.*. Navigate appelle le même BrowserAutomationService.NavigateAsync() que g.nav.navigateToUrl(). La couche MCP est un adaptateur fin qui mappe les requêtes JSON-RPC vers des appels de service et formate les résultats.

Cela signifie que scripts et outils IA ont les mêmes capacités, avec une exception critique abordée dans la section sécurité.

Sécurité en trois couches

C’est ici que Guida diverge de la plupart des serveurs MCP. L’IA est puissante, mais elle n’est pas de confiance. Chaque action passe par trois couches de sécurité avant d’atteindre le navigateur.

Couche 1 : liste de domaines autorisés

Avant que l’IA puisse naviguer vers une URL, le domaine doit être autorisé. Guida prend en charge trois niveaux :

Par session — domaines approuvés qui expirent à la fermeture de l’application
Par espace de travail — domaines listés dans domains.json dans le dossier d’espace de travail
Global — domaines toujours autorisés, configurés dans les paramètres

Si l’IA tente de naviguer vers un domaine non autorisé, l’appel échoue avec un message clair. L’IA voit le refus et peut expliquer ce qui s’est passé.

Les jokers fonctionnent : *.example.com autorise tous les sous-domaines. La liste autorisée s’applique à la navigation scriptée seulement ; vous pouvez naviguer manuellement où vous voulez.

Couche 2 : autorisation d’outil

Même sur un domaine autorisé, les appels surveillés demandent votre autorisation explicite. Quand l’IA veut cliquer sur un bouton ou exécuter un script, Guida vous montre :

le nom exact de l’outil appelé ;
les paramètres exacts : URL, sélecteur, code de script, etc. ;
les options pour autoriser une fois, autoriser pour cette session ou refuser.

C’est le même modèle de permission qu’une application mobile demandant l’accès à la caméra, mais par action et non par installation. Vous pouvez faire confiance à un outil pour la session si vous ne voulez plus cliquer, ou réviser chaque appel individuellement.

L’Approval Center montre les vrais paramètres, pas un résumé. Si l’IA veut appeler Click avec le sélecteur button.delete-account, vous verrez ce sélecteur exact avant exécution.

Couche 3 : registre de traçabilité

Chaque appel d’outil est enregistré dans mcp-audit.db, une base LiteDB séparée inaccessible à l’IA. Le registre capture :

nom de l’outil et paramètres, jusqu’aux 4000 premiers caractères ;
résultat ou erreur, jusqu’aux 2000 premiers caractères ;
durée d’exécution ;
horodatage et ID de session.

Le panneau MCP History affiche le registre en temps réel. Vous pouvez chercher, filtrer par erreur et ouvrir les appels individuels pour voir le JSON complet des paramètres et résultats.

La propriété de sécurité clé : l’IA ne peut pas lire ni effacer son propre registre de traçabilité. Aucun outil MCP n’expose la base d’audit. Même une IA victime d’une injection de prompt ne peut pas couvrir ses traces.

Isolation des identifiants d’accès

Une autre limite de sécurité mérite d’être explicitée. Guida a un panneau Secrets où vous stockez des identifiants d’accès, comme des clés API, mots de passe et jetons, chiffrés avec Windows DPAPI. Les scripts peuvent lire ces valeurs avec g.secrets.getSecret(name), mais les scripts d’origine MCP ne le peuvent pas.

Lorsqu’un script est lancé via un outil MCP comme ExecuteScript, Guida le marque avec l’origine Mcp. Tout appel à g.secrets.getSecret() depuis un script d’origine MCP renvoie une erreur. Cela casse la chaîne d’exfiltration :

AI calls ExecuteScript → script calls g.secrets.getSecret("api-key")
                        → BLOCKED (MCP origin detected)

Sans cela, une IA injectée par prompt pourrait exécuter un script qui lit votre clé API, l’écrit dans g.store, puis lit le stockage via MCP. Le contrôle d’origine bloque la première étape.

Les autres opérations sur les entrées, comme lister les noms ou définir des valeurs, restent possibles. Seule la lecture des valeurs déchiffrées est bloquée. L’IA peut donc aider à gérer les identifiants d’accès sans jamais voir les valeurs réelles.

Outils personnalisés

Au-delà des 100+ outils intégrés, vous pouvez définir des outils HTTP personnalisés dans le tools.json d’un espace de travail :

{
  "tools": [
    {
      "name": "GetWeather",
      "description": "Get current weather for a city",
      "endpoint": "https://api.weather.example/v1/current",
      "method": "GET",
      "parameters": {
        "city": { "type": "string", "description": "City name", "required": true }
      },
      "headers": {
        "Authorization": "Bearer {{secrets.WEATHER_API_KEY}}"
      }
    }
  ]
}

Remarquez le modèle {{secrets.WEATHER_API_KEY}}. La valeur réelle de l’identifiant est injectée au moment de l’appel par le serveur ; l’IA ne la voit jamais. Cela permet de donner à l’IA accès à des API authentifiées sans exposer les identifiants.

Les outils personnalisés passent par le même flux d’autorisation que les outils intégrés. L’IA voit le schéma, propose un appel, et vous autorisez ou refusez.

Résumé d’architecture

Voici comment les pièces s’assemblent :

┌──────────────────────┐
│   AI Client          │  Claude Code, Cursor, etc.
│   (MCP Client)       │
└──────────┬───────────┘
           │ MCP over local HTTP
           │
┌──────────▼───────────┐
│   Guida MCP Server   │  Embedded Kestrel on 127.0.0.1:9315
│                      │
│  ┌─ Domain Filter ─┐ │  Layer 1: URL whitelist check
│  ├─ Approval Center┤ │  Layer 2: User approves/denies
│  ├─ Audit Logger  ─┤ │  Layer 3: Record to mcp-audit.db
│  └─ Tool Handler  ─┘ │  Execute via shared services
│                      │
└──────────┬───────────┘
           │ Service calls
           │
┌──────────▼───────────┐
│   Shared Services    │  BrowserAutomation, Store, Queue,
│                      │  Search, Network, History, etc.
└──────────┬───────────┘
           │
┌──────────▼───────────┐
│   Browser / WebView2 │  Chromium-based browser engine
└──────────────────────┘

Le serveur MCP est une fine couche d’adaptation. Il ne duplique aucune logique métier : il mappe JSON-RPC vers les mêmes services que les scripts. Les couches de sécurité, filtre de domaine, autorisation et traçabilité, sont insérées comme middleware dans le pipeline MCP.

Connecter un client

Pour connecter Claude Code ou un autre client MCP à Guida, ajoutez ceci à la configuration du client :

{
  "mcpServers": {
    "guida": {
      "url": "http://127.0.0.1:9315/"
    }
  }
}

C’est tout. Le client découvre les outils disponibles avec tools/list et commence les appels. L’Approval Center de Guida gère les requêtes surveillées.

Pour plus de détails sur les outils disponibles et la configuration d’espace de travail, consultez la documentation Intégration MCP et le guide Outils personnalisés.