Créer un serveur MCP avec Symfony : le MCP Bundle pas à pas

Créer un serveur MCP avec Symfony : le MCP Bundle pas à pas

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.

Un service Symfony avec des attributs MCP, détecté par le MCP Bundle, exposé par la commande mcp:server en stdio et par la route /mcp en HTTP
Schéma — Le bundle détecte votre service et l'expose en stdio (commande) et en HTTP (route). (Cliquez sur le schéma pour l'agrandir.)
  • stdio : la commande bin/console mcp:server, que Claude Desktop ou Claude Code lancent en sous-processus ;
  • Streamable HTTP : une route /mcp servie 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 :

La classe CarnetDeNotes : la méthode ajouter devient un Tool, toutes devient une Resource, resumer devient un Prompt
Schéma — Chaque méthode marquée d'un attribut devient une primitive 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 service Security ou 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
  • name et version sont annoncés au client lors de l'initialize (en 2026-07-28 : dans le serverInfo du _meta de chaque réponse) ;
  • registry limite l'exposition aux services de l'espace de noms App\Mcp\ (la recette met '*' par défaut, qui exposerait aussi les services MCP de bundles tiers) ;
  • transports active les deux portes d'entrée. stdio est désactivé par défaut, d'où le stdio: 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 :

Séquence HTTP : initialize renvoie Mcp-Session-Id, notifications/initialized renvoie 202, tools/call renvoie 200, DELETE termine la session
Schéma — Une session MCP sur HTTP en révision 2025-11-25, avec les vrais codes de réponse observés. (Cliquez sur le schéma pour l'agrandir.)

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ête Mcp-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 dans http.allowed_hosts.
  • L'authentification : /mcp est 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 exemple claude 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 commande bin/console mcp:server pour stdio, la route /mcp pour 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 un DELETE termine la session. Il est supprimé en 2026-07-28 : chaque requête est autonome et annonce sa méthode avec Mcp-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.

Continuer la lecture

Article suivant — Outils IA Tools, Resources et Prompts : les primitives MCP et votre premier serveur Explorer tout : Outils IA

Commentaires

Soyez le premier à laisser un commentaire — le robot attend.

Laisser un commentaire

Les champs obligatoires sont indiqués avec *