---
title: "Symfony AI Mate : Donnez des super-pouvoirs à Claude Code avec ce serveur MCP"
excerpt: "Découvrez comment connecter votre agent IA (Claude Code, Cursor, JetBrains AI...) à votre projet Symfony grâce à AI Mate, le serveur MCP officiel. Installation pas à pas, extensions Monolog et Profiler : tout pour transformer votre assistant IA en copilote Symfony."
publishDate: 2026-03-08T00:00:00.000Z
tags: ["symfony", "ia", "mcp", "claude", "anthropic", "php", "tutorial", "ai-mate", "claude-code", "monolog", "profiler"]
canonical: "https://yoandev.co/symfony-ai-mate-claude-code"
---

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](https://symfony.com/doc/current/ai/components/mate.html)**, le serveur MCP officiel de Symfony. MCP (Model Context Protocol) est le protocole créé par [Anthropic](https://www.anthropic.com/) 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](https://symfony.com/download))
- **Claude Code** installé ([claude.ai/code](https://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.

```bash
symfony new --demo my_project
```

Entrez dans le projet :

```bash
cd my_project
```

Vérifiez que tout fonctionne :

```bash
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 :

```bash
composer require --dev symfony/ai-mate
```

Puis on initialise la configuration :

```bash
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 :

```bash
composer dump-autoload
```

---

## Étape 3 : Installer les extensions

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

| Tool | Description |
|------|-------------|
| `php-version` | Version de PHP utilisée |
| `operating-system` | Système d'exploitation courant |
| `operating-system-family` | Famille d'OS (Linux, Darwin, Windows) |
| `php-extensions` | Liste des extensions PHP chargées |

Pour interagir avec Symfony, on installe deux **extensions officielles** :

### Extension Monolog (logs)

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

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

| Tool | Description |
|------|-------------|
| `monolog-tail` | Afficher les N dernières entrées de log |
| `monolog-search` | Rechercher dans les logs par terme |
| `monolog-search-regex` | Rechercher avec une regex |
| `monolog-by-level` | Filtrer par niveau (ERROR, WARNING...) |
| `monolog-list-files` | Lister les fichiers de log disponibles |
| `monolog-list-channels` | Lister les channels Monolog |
| `monolog-context-search` | Rechercher dans le contexte des logs |

### Extension Symfony (container + profiler)

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

Cette extension donne accès à :

| Tool | Description |
|------|-------------|
| `symfony-services` | Lister tous les services du container |
| `symfony-profiler-list` | Lister les profils du profiler |
| `symfony-profiler-latest` | Obtenir le dernier profil |
| `symfony-profiler-search` | Rechercher des profils (par status, méthode...) |
| `symfony-profiler-get` | Obtenir un profil par son token |

### Découvrir les extensions

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

```bash
vendor/bin/mate discover
```

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

```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
<?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 :

```bash
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 :

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

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

```bash
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 :

```json
{
    "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 :

```bash
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é :

| Package | Rôle |
|---------|------|
| `symfony/ai-mate` | Serveur MCP de base |
| `symfony/ai-monolog-mate-extension` | Accès aux logs Monolog |
| `symfony/ai-symfony-mate-extension` | Accès au container et au profiler |

| Fichier | Rôle |
|---------|------|
| `mcp.json` | Configuration du client MCP (généré par `mate init`) |
| `mate/config.php` | Paramètres des extensions |
| `mate/extensions.php` | Activation/désactivation des extensions |

---

## 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
<?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 :

```bash
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](https://symfony.com/doc/current/ai/components/mate/creating-extensions.html).

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](https://symfony.com/doc/current/ai/components/mate.html)
> - [Créer des extensions MCP](https://symfony.com/doc/current/ai/components/mate/creating-extensions.html)
> - [Repository GitHub symfony/ai-mate](https://github.com/symfony/ai-mate)
> - [Symfony AI](https://ai.symfony.com/)