Votre assistant utilise vos propres systèmes

Comment ça marche

MCP (Model Context Protocol) est un standard ouvert pour relier des assistants IA à d'autres logiciels. Un serveur MCP propose une liste d'outils, comme find_slots ou my_orders. Vous le connectez une fois dans MagizAI, vous choisissez les outils que l'assistant peut utiliser, et il les appelle dès qu'une question du visiteur en a besoin.

1. 01

   Connecter

   Compétences, puis Serveurs MCP. Collez l'adresse https et le jeton. MagizAI lit la liste des outils.

2. 02

   Choisir les outils

   Cliquez sur Gérer. Cochez les outils à utiliser. Un outil non coché n'est jamais appelé.

3. 03

   Sûr ou Sensible

   Un outil Sûr s'exécute tout de suite. Un outil Sensible attend que le visiteur recopie un code à six chiffres : rien ne change sans son accord.

4. 04

   Lier les comptes à la connexion

   Pour un outil qui lit les données d'un client, réglez son argument e-mail ou compte sur « Rempli depuis le visiteur connecté ». Il n'est alors jamais pris dans la conversation.

Les limites à connaître

Voici les vraies limites côté MagizAI. Un serveur qui les respecte fonctionne du premier coup.

Clients connectés

Des outils comme « mes commandes » ou « mes rendez-vous » ne doivent montrer que les données du client connecté. MagizAI s'appuie pour cela sur un jeton d'identité signé par votre site, jamais sur ce que tape le visiteur.

1. Dans MagizAI, ouvrez le chatbot, section Identité de visiteur signée, et générez un secret. Gardez-le sur votre serveur.
2. Quand un client est connecté à votre site, votre serveur signe un jeton court (HS256) avec son e-mail et une expiration, et l'ajoute à la balise du widget dans data-identity.
3. Dans les réglages de l'outil MCP, réglez l'argument e-mail sur « Rempli depuis le visiteur connecté ». MagizAI le remplit depuis le jeton vérifié et refuse l'appel si le visiteur n'est pas connecté.

<?php
// On your server, for the signed-in customer. $secret comes from the chatbot's
// "Signed visitor identity" setting and never goes to the browser.
function magiz_identity(string $email, string $name, string $secret): string
{
    $b64 = fn ($s) => rtrim(strtr(base64_encode($s), '+/', '-_'), '=');
    $head = $b64(json_encode(['alg' => 'HS256', 'typ' => 'JWT']));
    $body = $b64(json_encode([
        'email' => $email,
        'name'  => $name,
        'iat'   => time(),
        'exp'   => time() + 3600,
    ]));
    return "$head.$body." . $b64(hash_hmac('sha256', "$head.$body", $secret, true));
}
?>
<script src="https://magiz.ai/widget.js" data-key="YOUR_WIDGET_KEY"
        data-identity="<?= magiz_identity($user->email, $user->name, $secret) ?>" defer></script>

Le jeton doit contenir exp et durer 24 heures au plus. Le secret ne va jamais dans le navigateur, seul le jeton final y va. Les sites WHMCS l'obtiennent automatiquement avec notre module WHMCS.

Exemples par activité

Pour chaque activité : un vrai cas d'usage, une conversation type et deux façons de faire. Un service à connecter dès aujourd'hui, ou un programme de départ à déposer sur votre hébergement et à relier à vos propres données.

Services à connecter dès aujourd'hui

Ces services proposent leur propre serveur MCP, que MagizAI peut connecter avec une clé. Donnez à chaque clé le minimum de droits nécessaires : l'assistant ne peut faire que ce que la clé permet.

Lancer un programme de départ

Chaque programme de départ est un petit programme PHP sans dépendance. Il tourne sur un hébergement mutualisé ordinaire, contient des données de démonstration pour fonctionner dès le dépôt, et un seul fichier tools.php à relier à votre base. Nécessite PHP 7.4 ou plus récent avec PDO (SQLite pour la démonstration, ou MySQL).

1. Téléchargez le programme de votre activité et déposez son dossier sur votre site, par exemple dans public_html/mcp/.
2. Copiez config.sample.php en config.php et mettez dans token un long secret aléatoire. Le serveur refuse de tourner avec le jeton d'exemple.
3. Vérifiez qu'il répond. La commande ci-dessous doit lister les outils.

curl -X POST https://yourdomain.com/mcp/index.php \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

4. Dans MagizAI, connectez-le avec l'adresse de index.php et l'authentification par jeton Bearer, puis réglez les outils comme indiqué sur sa carte.
5. Posez une question à votre assistant depuis le chat de votre site. Appels d'outils récents, sur la page du serveur, montre chaque appel.

Utilisez vos vraies données

Renseignez dsn, db_user et db_pass dans config.php avec votre base MySQL ou MariaDB, puis adaptez le SQL de tools.php à vos tables. Chaque outil est un bloc : un nom, une phrase qui dit quand l'utiliser, ses arguments et une fonction qui renvoie un texte court.

<?php
// tools.php: one block per tool. $db is a PDO connection from config.php.
$server->tool(array(
    'name' => 'my_orders',
    'description' => 'Use when a signed-in customer asks where their order is.',
    'inputSchema' => array('type' => 'object', 'properties' => array(
        'email' => array('type' => 'string', 'maxLength' => 190),
    ), 'required' => array('email')),
    'annotations' => array('readOnlyHint' => true),
    'handler' => function (array $args) use ($db) {
        $q = $db->prepare('SELECT number, status, tracking FROM orders
                           WHERE email = ? ORDER BY placed_on DESC LIMIT 5');
        $q->execute(array($args['email']));
        $out = array();
        foreach ($q->fetchAll() as $o) {
            $out[] = "#{$o['number']}: {$o['status']} {$o['tracking']}";
        }
        return $out ? implode("\n", $out) : 'No orders found.';
    },
));

Le fichier .htaccess fourni n'ouvre au web que index.php. Sur nginx, ajoutez la même règle vous-même, sinon la base de démonstration pourrait être téléchargée.

Créer le vôtre

Tout langage convient s'il parle Streamable HTTP. Voici les options maintenues.

Règles pour des outils efficaces

• Une phrase claire par outil qui dit quand l'utiliser. L'assistant choisit les outils en lisant ces descriptions.
• Marquez les consultations avec readOnlyHint et tout ce qui supprime ou annule avec destructiveHint. MagizAI n'accepte jamais qu'un outil destructif soit marqué Sûr.
• Validez aussi chaque argument de votre côté, et limitez chaque requête aux lignes du client connecté.
• Renvoyez un texte court avec les faits utiles. Jamais de mots de passe, de numéros de carte complets ou de notes internes.
• Traitez un appel d'outil comme toute requête d'API publique : vérifiez le jeton, journalisez et limitez le débit.

Dépannage