Dans l'article précédent, on a écrit un petit serveur MCP « carnet de notes » en Node.js. On reprend exactement le même exemple, mais cette fois à l'intérieur d'une application Symfony, avec le MCP Bundle. L'intérêt est énorme : vos services, Doctrine, la sécurité, la configuration… tout ce que vous avez déjà devient accessible à une IA, sans réécrire une ligne de logique métier.
Tout le code de cet article a été testé dans une application Symfony 7.4 neuve, en stdio et en HTTP. Si vous débarquez, commencez par le premier article de la série.
Le MCP Bundle en deux mots
Le paquet symfony/mcp-bundle fait partie de l'initiative Symfony AI. Il s'appuie sur le SDK PHP officiel de MCP (mcp/sdk), fruit d'une collaboration entre la PHP Foundation et le projet Symfony. Son rôle : repérer dans votre code les méthodes marquées comme tools, resources ou prompts, et les exposer en MCP par deux portes d'entrée.

- stdio : la commande
bin/console mcp:server, que Claude Desktop ou Claude Code lancent en sous-processus ; - Streamable HTTP : une route
/mcpservie par votre application, pour des clients distants.
Avertissement important : le bundle et le SDK sont officiellement expérimentaux (version 0.15 du bundle au moment où j'écris). Ils ne sont pas encore couverts par la promesse de rétrocompatibilité de Symfony : l'API peut changer d'une version à l'autre. Épinglez vos versions et relisez le changelog avant de mettre à jour.
Installation
composer require symfony/mcp-bundle
La recette Flex crée deux fichiers : config/packages/mcp.yaml (la configuration) et config/routes/mcp.yaml (qui importe la route HTTP). Si vous comptez utiliser le transport HTTP, ajoutez aussi une implémentation PSR-7/PSR-17 :
composer require nyholm/psr7
Sans elle, la route /mcp répond par une erreur 500 : « No PSR-17 server request factory found ». Le SDK parle le langage standard PSR-7 pour les requêtes HTTP, et le bundle ne fournit pas d'implémentation lui-même. C'est le premier piège que j'ai rencontré.
Le service : trois méthodes, trois attributs
On écrit une classe Symfony tout à fait ordinaire, dans src/Mcp/. Trois attributs PHP suffisent à exposer ses méthodes en MCP :

<?php
// src/Mcp/CarnetDeNotes.php
namespace App\Mcp;
use Mcp\Capability\Attribute\McpPrompt;
use Mcp\Capability\Attribute\McpResource;
use Mcp\Capability\Attribute\McpTool;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
/**
* Le « carnet de notes » des articles précédents, en service Symfony.
* Le MCP Bundle détecte les attributs et l'expose en MCP (stdio et HTTP).
*/
final class CarnetDeNotes
{
public function __construct(
#[Autowire('%kernel.project_dir%/var/notes.json')]
private readonly string $fichier,
) {
}
/**
* Ajoute une note au carnet.
*
* @param string $texte Le contenu de la note
*/
#[McpTool(name: 'ajouter_note')]
public function ajouter(string $texte): string
{
$notes = $this->lire();
$notes[] = $texte;
file_put_contents($this->fichier, json_encode($notes));
return sprintf('Note ajoutée (%d au total).', count($notes));
}
#[McpResource(uri: 'notes://toutes', name: 'liste-des-notes', mimeType: 'text/plain')]
public function toutes(): string
{
$notes = $this->lire();
return implode("\n", array_map(fn ($n, $i) => ($i + 1).'. '.$n, $notes, array_keys($notes)));
}
/**
* Demande un résumé des notes du carnet.
*
* @param string $ton Ex. : « sérieux » ou « drôle »
*/
#[McpPrompt(name: 'resumer_notes')]
public function resumer(string $ton): array
{
return [['role' => 'user', 'content' => "Résume mes notes sur un ton $ton :\n".$this->toutes()]];
}
private function lire(): array
{
return is_file($this->fichier) ? json_decode(file_get_contents($this->fichier), true) : [];
}
}
Ce qui se passe en coulisses :
#[McpTool],#[McpResource]et#[McpPrompt]déclarent les trois primitives. Le bundle les repère à la compilation du conteneur : pas d'enregistrement manuel, l'autoconfiguration s'en charge.- Le JSON Schema envoyé au client (puis transmis au modèle) est déduit de la signature (
string $texte) et de la PHPDoc : la description « Le contenu de la note » vient directement du@param. Soignez vos docblocks, le modèle les lit. - C'est un vrai service : on lui injecte ici le chemin du fichier avec
#[Autowire], mais on pourrait tout aussi bien injecter un repository Doctrine, le serviceSecurityou un client HTTP.
Attention aux exemples trouvés en ligne : l'espace de noms des attributs dépend de la version du SDK. C'est Mcp\Capability\Attribute en SDK 0.9 (celui qu'installe le bundle 0.15), et Mcp\Server\Capability\Attribute à partir de la 0.10. Vérifiez votre version avec composer show mcp/sdk.
La configuration
On remplace le contenu généré par la recette par ceci :
# config/packages/mcp.yaml
mcp:
servers:
default:
name: carnet-de-notes
version: 1.0.0
registry: 'App\Mcp\'
transports:
stdio: true # bin/console mcp:server (Claude Desktop, Claude Code…)
http: true # route /mcp (Streamable HTTP)
http:
path: /mcp
nameetversionsont annoncés au client lors de l'initialize(en 2026-07-28 : dans leserverInfodu_metade chaque réponse) ;registrylimite l'exposition aux services de l'espace de nomsApp\Mcp\(la recette met'*'par défaut, qui exposerait aussi les services MCP de bundles tiers) ;transportsactive les deux portes d'entrée. stdio est désactivé par défaut, d'où lestdio: true.
Tester en stdio
Pour retrouver les mêmes résultats que dans l'article précédent, on démarre avec les deux notes de départ (le service crée le fichier s'il n'existe pas, mais il démarre alors vide) :
echo '["Acheter du café","Relire l'\''article sur MCP"]' > var/notes.json
La commande php bin/console mcp:server démarre le serveur sur l'entrée et la sortie standard. Pour le tester sans IA, l'Inspector officiel fonctionne aussi avec PHP :
npx @modelcontextprotocol/inspector php bin/console mcp:server
Voici les vraies réponses obtenues avec mon client de test :
tools/list -> ajouter_note, inputSchema { texte: string, requis }
tools/call -> Note ajoutée (3 au total).
resources/read -> 1. Acheter du café / 2. Relire l'article sur MCP / 3. Tester MCP
prompts/get -> Résume mes notes sur un ton drôle : …
appel invalide -> erreur JSON-RPC -32602 : « Expected `string`, but received `integer` »
Notez la dernière ligne : sur un argument invalide, le SDK PHP répond par une erreur de protocole (code -32602), alors que le SDK TypeScript renvoyait un résultat isError. Or depuis la révision 2025-11-25, un argument invalide doit être renvoyé avec isError, pour que le modèle puisse se corriger (voir l'article sur le fonctionnement de MCP). Le SDK PHP, encore expérimental, n'a pas suivi sur ce point.
Le brancher sur Claude
Dans Claude Code :
claude mcp add carnet-symfony -- php /chemin/vers/projet/bin/console mcp:server
Dans Claude Desktop, dans claude_desktop_config.json :
{
"mcpServers": {
"carnet-symfony": {
"command": "php",
"args": ["/chemin/vers/projet/bin/console", "mcp:server"]
}
}
}
Rappel du piège stdio : la sortie standard transporte les messages JSON-RPC. Pas d'echo, de dump() ni de var_dump() dans le code appelé par vos tools : utilisez un logger qui écrit dans un fichier ou sur stderr (attention à une configuration Monolog qui écrirait sur php://stdout, fréquente en Docker).
Le transport HTTP, en vrai
Lancez l'application (symfony server:start, ou simplement php -S localhost:8000 -t public), et la route /mcp est prête. Voici ce qui se passe réellement sur le réseau avec un client en révision 2025-11-25, la plus répandue aujourd'hui :

Le premier échange, capturé avec curl :
curl -i -X POST http://localhost:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
HTTP/1.1 200 OK
Content-Type: application/json
Mcp-Session-Id: 57849057-34d4-447e-b2a0-86d0ed4ff9d2
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25",
"capabilities":{"logging":{},"completions":{},"prompts":{},"resources":{"subscribe":true},"tools":{}},
"serverInfo":{"name":"carnet-de-notes","version":"1.0.0"}}}
Trois points à retenir (révision 2025-11-25), que j'ai tous vérifiés :
- Le serveur attribue un identifiant de session dans l'en-tête
Mcp-Session-Id. Le client doit le renvoyer à chaque requête suivante. Sans lui : 400 et l'erreur-32600. - Une notification (comme
notifications/initialized) n'attend pas de réponse JSON-RPC : le serveur répond 202 Accepted, sans corps. - Un
DELETE /mcp, avec l'en-têteMcp-Session-Id, termine la session ; toute requête qui la réutilise reçoit ensuite un 404.
Et en révision 2026-07-28 ?
Le SDK PHP utilisé par le bundle parle déjà la nouvelle révision, et le même serveur accepte les deux. En 2026-07-28, plus de poignée de main ni de session : une seule requête suffit, à condition d'indiquer la méthode (Mcp-Method) et le nom de l'outil visé (Mcp-Name) dans les en-têtes, et la version à la fois dans l'en-tête MCP-Protocol-Version et dans le _meta du message.
curl -i -X POST http://localhost:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: tools/call' -H 'Mcp-Name: ajouter_note' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ajouter_note","arguments":{"texte":"Via HTTP 2026"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1.0"}}}}'
HTTP/1.1 200 OK
Content-Type: application/json
{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Note ajoutée (4 au total)."}],
"isError":false,"resultType":"complete",
"_meta":{"io.modelcontextprotocol/serverInfo":{"name":"carnet-de-notes","version":"1.0.0"}}}}
Aucun Mcp-Session-Id dans la réponse : chaque requête est autonome. Le resultType vaut complete : la réponse est finale, sans aller-retour. Et si l'on oublie l'en-tête Mcp-Method, le serveur répond 400 avec l'erreur -32020 (« Missing required Mcp-Method header »).
Le brancher en HTTP
Côté Claude Code, on branche un serveur HTTP ainsi :
claude mcp add --transport http carnet-http http://localhost:8000/mcp
Avant la production
- Les hôtes autorisés : par défaut, le SDK n'accepte que
localhost(protection contre le DNS rebinding). Pour exposer le serveur publiquement, il faut lister vos domaines danshttp.allowed_hosts. - L'authentification :
/mcpest une route Symfony comme une autre. Protégez-la avec le composant Security (pare-feu, jeton d'accès), et servez-la en HTTPS. La spécification prévoit OAuth 2.1 ; si vous vous contentez d'un simple jeton, le client doit l'envoyer dans un en-tête, par exempleclaude mcp add --transport http carnet-http https://example.com/mcp --header "Authorization: Bearer …". - Le moindre privilège : n'exposez que les services prévus à cet effet (
registry), et vérifiez dans chaque tool que l'utilisateur a bien le droit de faire ce qu'il demande. - La stabilité : le bundle est expérimental. Versions épinglées et tests sur vos tools sont indispensables.
Questions d'entretien : les réponses courtes
- Comment exposer un service Symfony en MCP ?
- Avec le MCP Bundle : on ajoute
#[McpTool],#[McpResource]ou#[McpPrompt]sur les méthodes, et le bundle les détecte à la compilation du conteneur, sans enregistrement manuel. - stdio ou HTTP avec le bundle ?
- Les deux, selon la configuration
transports: la commandebin/console mcp:serverpour stdio, la route/mcppour Streamable HTTP. - À quoi sert l'en-tête Mcp-Session-Id ?
- En révision 2025-11-25, à identifier la session HTTP : le serveur le fournit en réponse à
initialize, le client le renvoie ensuite à chaque requête (sinon 400), et unDELETEtermine la session. Il est supprimé en 2026-07-28 : chaque requête est autonome et annonce sa méthode avecMcp-Method. - D'où vient le JSON Schema d'un tool en PHP ?
- Du typage de la méthode et de sa PHPDoc : le SDK les analyse pour générer le schéma et la description de chaque argument.
- Le bundle est-il prêt pour la production ?
- Il est utilisable, mais expérimental : pas de promesse de rétrocompatibilité. Il faut épingler les versions, tester, et protéger la route HTTP (hôtes autorisés, authentification).
C'est la fin de cette série. Vous savez maintenant pourquoi MCP existe, comment il fonctionne, ce qu'un serveur expose, et comment en construire un avec Symfony.




Commentaires