Symfony AI Mate : Donnez des super-pouvoirs à Claude Code avec ce serveur MCP

Et si votre assistant IA pouvait lire vos logs, inspecter le profiler et lister vos services, sans quitter votre terminal ?

C’est exactement ce que permet Symfony AI Mate, le serveur MCP officiel de Symfony. MCP (Model Context Protocol) est le protocole créé par Anthropic qui permet aux agents IA de se connecter à des outils externes. AI Mate transpose ce protocole dans l’écosystème Symfony : il expose des tools structurées que Claude Code (ou tout autre client MCP compatible) peut appeler directement.

Important : AI Mate est un outil de développement. Il s’installe en dépendance --dev et n’a pas vocation à être déployé en production.

Bien que ce tutoriel utilise Claude Code comme exemple, AI Mate fonctionne avec tous les agents et IDE compatibles MCP : Cursor, Windsurf, GitHub Copilot (via agent mode), JetBrains AI, et bien d’autres.

Dans ce tutoriel, on va partir de la Symfony Demo, une application de blog complète avec authentification, CRUD et base de données, et la connecter pas à pas à Claude Code grâce à AI Mate. À la fin, Claude Code pourra :

• Parcourir et rechercher dans vos logs Monolog
• Inspecter les profils du Symfony Profiler
• Lister les services du container

Le tout sans écrire une seule commande manuellement, Claude le fait pour vous.

---

Pré-requis

Avant de commencer, assurez-vous d’avoir :

• PHP 8.4+ installé
• Composer installé globalement
• La CLI Symfony installée (symfony.com/download)
• Claude Code installé (claude.ai/code)
• SQLite (extension PHP pdo_sqlite)

---

Étape 1 : Créer le projet Symfony Demo

On va utiliser la Symfony Demo, une application de blog complète avec authentification, CRUD, base de données SQLite et tests. C’est le terrain de jeu parfait pour expérimenter AI Mate.

symfony new --demo my_project

Entrez dans le projet :

cd my_project

Vérifiez que tout fonctionne :

symfony server:start -d

Ouvrez votre navigateur sur l’URL affichée (par défaut https://127.0.0.1:8000). Vous devriez voir la Symfony Demo avec son blog et son interface d’administration.

Astuce : la Symfony Demo utilise SQLite, donc aucune configuration de base de données n’est nécessaire.

---

Étape 2 : Installer AI Mate

AI Mate est un package de développement. On l’installe avec Composer :

composer require --dev symfony/ai-mate

Puis on initialise la configuration :

vendor/bin/mate init

Cette commande crée :

• Un dossier mate/ à la racine du projet avec :
  • config.php : configuration des services et paramètres
  • extensions.php : liste des extensions activées/désactivées
  • src/ : dossier pour vos tools customs
• Un fichier mcp.json à la racine : configuration pour les clients MCP (Claude Code, Cursor, etc.)

Elle met aussi à jour votre composer.json pour ajouter l’autoloading du dossier mate/src/ et la configuration extra.ai-mate. Claude Code détectera automatiquement ce fichier mcp.json au lancement.

N’oubliez pas de dumper l’autoloader :

composer dump-autoload

---

Étape 3 : Installer les extensions

AI Mate est modulaire. Le package de base (symfony/ai-mate) fournit 4 tools système :

Pour interagir avec Symfony, on installe deux extensions officielles :

Extension Monolog (logs)

composer require --dev symfony/ai-monolog-mate-extension

Cette extension donne accès à vos fichiers de logs :

Extension Symfony (container + profiler)

composer require --dev symfony/ai-symfony-mate-extension

Cette extension donne accès à :

Découvrir les extensions

Après l’installation, lancez la découverte :

vendor/bin/mate discover

Cette commande scanne les packages installés et génère automatiquement le fichier mate/extensions.php :

<?php

// This file is managed by 'mate discover'
// You can manually edit to enable/disable extensions

return [
    'symfony/ai-mate' => ['enabled' => true],
    'symfony/ai-monolog-mate-extension' => ['enabled' => true],
    'symfony/ai-symfony-mate-extension' => ['enabled' => true],
];

Vous pouvez désactiver une extension en passant enabled à false.

---

Étape 4 : Configurer AI Mate

Paramètres des extensions

Éditez le fichier mate/config.php pour indiquer à AI Mate où trouver les fichiers de cache, le profiler et les logs :

<?php

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $container): void {
    $container->parameters()
        ->set('ai_mate_symfony.cache_dir', '%mate.root_dir%/var/cache')
        ->set('ai_mate_symfony.profiler_dir', '%mate.root_dir%/var/cache/dev/profiler')
        ->set('ai_mate_monolog.log_dir', '%mate.root_dir%/var/log')
    ;

    $container->services()
        // Enregistrez vos services customs ici si besoin
    ;
};

Note : %mate.root_dir% est un paramètre spécial qui pointe vers la racine de votre projet.

Vérifier que tout fonctionne

Listez les tools disponibles :

vendor/bin/mate mcp:tools:list

Vous devriez voir tous les tools des extensions installées. Vous pouvez aussi inspecter un tool en détail :

vendor/bin/mate mcp:tools:inspect monolog-tail

Ou même appeler un tool directement depuis le terminal :

vendor/bin/mate mcp:tools:call php-version '{}'

---

Étape 5 : Connecter Claude Code

Bonne nouvelle : il n’y a rien à faire. La commande mate init (étape 2) a déjà généré un fichier mcp.json à la racine du projet avec la configuration nécessaire :

{
    "mcpServers": {
        "symfony-ai-mate": {
            "command": "./vendor/bin/mate",
            "args": [
                "serve"
            ]
        }
    }
}

Claude Code détecte automatiquement ce fichier au lancement et se connecte au serveur MCP. Aucune configuration supplémentaire n’est requise.

Tester la connexion

Lancez Claude Code dans le dossier du projet :

claude

Tapez /mcp pour vérifier que le serveur symfony-ai-mate est bien connecté. Vous pouvez ensuite demander :

• “Quels sont les derniers logs ?”
• “Liste-moi tous les services Symfony”
• “Y a-t-il des erreurs dans les logs ?”
• “Montre-moi le dernier profil du profiler”

Claude utilisera automatiquement les tools MCP pour répondre.

---

Étape 6 : Utiliser au quotidien

Maintenant que tout est en place, voici des exemples concrets de ce que vous pouvez demander à Claude Code :

Exploration des logs

“Montre-moi les dernières entrées de log”

Claude appelle monolog-tail et vous présente les logs de manière structurée.

“Y a-t-il des erreurs dans les logs ?”

Claude appelle monolog-tail avec le paramètre level: ERROR.

Debugging avec le Profiler

Démarrez votre serveur Symfony, naviguez dans l’application, puis demandez :

“Liste les derniers profils du profiler”

Claude appelle symfony-profiler-list et vous montre les requêtes récentes avec leur status code.

“Montre-moi le détail de la dernière 404”

Claude enchaîne symfony-profiler-list (filtre par status 404), puis lit la resource symfony-profiler://profile/{token}/exception pour vous montrer l’exception exacte et sa stack trace.

Introspection de l’application

“Liste-moi tous les services Symfony”

Claude appelle symfony-services et vous présente le container.

“Quels channels de log existent dans l’app ?”

Claude appelle monolog-list-channels pour lister les channels disponibles.

---

Récapitulatif

Voici tout ce qu’on a installé et configuré :

---

Pour aller plus loin

Les extensions officielles couvrent les besoins génériques, mais AI Mate permet aussi de créer vos propres tools adaptés à votre projet. Il suffit de créer une classe dans mate/src/ avec l’attribut #[McpTool] :

<?php

// mate/src/MyTools.php

namespace App\Mate;

use Mcp\Capability\Attribute\McpTool;

class MyTools
{
    #[McpTool('my-tool', 'Description de ce que fait le tool')]
    public function myTool(string $param): array
    {
        // Votre logique ici
        return ['result' => $param];
    }
}

AI Mate détecte automatiquement les classes dans mate/src/, pas besoin de configuration supplémentaire. Vérifiez avec :

vendor/bin/mate mcp:tools:list --extension=_custom

Quelques pistes supplémentaires :

• Debug : vendor/bin/mate debug:capabilities pour voir toutes les capabilities exposées, et vendor/bin/mate debug:extensions pour vérifier le statut de chaque extension.
• Instructions personnalisées : ajoutez un fichier CLAUDE.md à la racine du projet pour guider l’IA sur votre projet, vos conventions et la façon d’utiliser vos tools.
• Extensions réutilisables : packagez vos tools en extension Composer avec la section extra.ai-mate. Consultez la documentation sur la création d’extensions.

AI Mate transforme votre agent IA en un véritable copilote Symfony. Plus besoin de copier-coller des commandes bin/console ou de lire des fichiers de log à la main : l’IA le fait pour vous, de manière structurée et contextuelle.

Ressources :

• Documentation officielle Symfony AI Mate
• Créer des extensions MCP
• Repository GitHub symfony/ai-mate
• Symfony AI