Un assistant IA ne sait rien de votre application. Il ne lit pas votre base, n'appelle pas vos API et ne connaît pas l'état d'une commande. Le Model Context Protocol (MCP), publié par Anthropic en novembre 2024, règle ce problème d'une seule façon pour tout le monde : votre application expose des outils dans un format commun, et n'importe quel client compatible sait les découvrir puis les appeler.
Cet article a été réécrit le 27/10/2026. Sa première version reposait sur un bundle communautaire, abandonné depuis au profit du bundle officiel de Symfony. Tout ce qui suit s'appuie sur des paquets maintenus, et chaque version citée a été relevée ce jour-là sur Packagist ou dans le dépôt du projet.
Ce que fait MCP, en trois rôles
Le protocole sépare trois rôles :
- l'hôte : l'application où vit l'assistant (Claude Desktop, Cursor, VS Code, ChatGPT) ;
- le client : le composant de l'hôte qui ouvre une connexion vers un serveur ;
- le serveur : votre code, qui déclare ce qu'il sait faire.
Un serveur expose trois sortes de capacités. Les outils sont des fonctions que le modèle peut appeler, avec un schéma JSON pour leurs arguments. Les ressources sont des données qu'il peut lire, identifiées par une URI. Les prompts sont des modèles d'instructions prêts à l'emploi. Les messages circulent en JSON-RPC 2.0, en local par l'entrée et la sortie standard (STDIO) ou à distance par HTTP.
L'intérêt tient en une ligne : au lieu d'écrire un connecteur par couple « modèle × outil », chaque outil est écrit une fois et chaque client le comprend.
Où en est le protocole au 27/10/2026
- La spécification : la révision la plus récente est celle du 2026-07-28, marquée « latest » sur modelcontextprotocol.io. Elle supprime la poignée de main
initializeet la session associée : chaque requête se décrit elle-même, ce qui permet à n'importe quel worker PHP de répondre. La révision précédente, 2025-11-25, reste servie par les SDK. - La gouvernance : depuis le 9 décembre 2025, MCP appartient à l'Agentic AI Foundation, un fonds de la Linux Foundation cofondé par Anthropic, Block et OpenAI (annonce d'Anthropic du 09/12/2025).
- L'adoption : la même annonce compte plus de 10 000 serveurs MCP publics actifs et cite ChatGPT, Cursor, Gemini, Microsoft Copilot et Visual Studio Code parmi les produits qui l'ont adopté.
- L'autorisation : la spécification décrit une autorisation de type OAuth 2.1 (découverte RFC 8414 et RFC 9728, enregistrement automatique des clients), c'est ce qu'attendent Claude et Cursor d'un serveur distant.
Les deux paquets PHP à connaître
| Paquet | Rôle | Version relevée le 27/10/2026 | Prérequis |
|---|---|---|---|
mcp/sdk |
SDK PHP officiel du MCP, sans dépendance à un framework : serveur et client, STDIO et HTTP | v0.9.0 (18/10/2026) | PHP 8.1 ou plus |
symfony/mcp-bundle |
intégration Symfony du SDK : configuration, découverte des services, route HTTP, commandes | v1.0.0-BETA1 (22/10/2026) | Symfony 7.3 ou 8, mcp/sdk ^0.9 |
Le SDK est développé dans le dépôt modelcontextprotocol/php-sdk, en collaboration entre la PHP Foundation et le projet Symfony. Le bundle vit dans le monorepo symfony/ai, à côté de l'AI Bundle.
Les deux se déclarent encore expérimentaux : ils ne sont pas couverts par la promesse de rétrocompatibilité de Symfony tant que la première version majeure n'est pas sortie. Concrètement, figez la version dans composer.json et relisez le journal des changements à chaque montée.
Installer le bundle
composer require symfony/mcp-bundle
Le SDK arrive en dépendance. Ajoutez ensuite la route du bundle :
# config/routes.yaml
mcp:
resource: .
type: mcp
Puis déclarez un serveur. Le bloc registry est obligatoire : un serveur n'expose que ce qu'il liste.
# config/packages/mcp.yaml
mcp:
servers:
default:
name: 'mon-app'
transports:
stdio: true
http: true
http:
path: /mcp
registry: ['App\Mcp\']
Avec cette configuration, tout service de l'espace de noms App\Mcp\ qui porte un attribut MCP est publié, et rien d'autre. Une faute de frappe dans un motif fait échouer la compilation du conteneur, ce qui vaut mieux qu'un outil exposé par erreur.
Un premier outil
Les capacités se déclarent par attributs PHP, ceux du SDK. Dans une application Symfony standard, avec l'autoconfiguration active, poser l'attribut sur une classe de src/ suffit : le bundle la repère à la compilation du conteneur et génère le schéma d'entrée à partir de la signature de la méthode.
Voici un outil météo en classe invocable. Il appelle l'API d'OpenWeatherMap avec le client HTTP de Symfony :
<?php
namespace App\Mcp;
use Mcp\Capability\Attribute\McpTool;
use Mcp\Capability\Attribute\Schema;
use Mcp\Exception\ToolCallException;
use Mcp\Schema\ToolAnnotations;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Contracts\HttpClient\HttpClientInterface;
#[McpTool(
name: 'get_weather',
description: 'Donne la météo actuelle pour une ville.',
annotations: new ToolAnnotations(
title: 'Météo',
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: true,
),
)]
final class WeatherTool
{
public function __construct(
private HttpClientInterface $httpClient,
#[Autowire(env: 'OPENWEATHER_API_KEY')]
private string $apiKey,
) {
}
public function __invoke(
#[Schema(description: 'Nom de la ville, par exemple Toulouse')]
string $city,
#[Schema(description: 'Système d\'unités', enum: ['metric', 'imperial'])]
string $unit = 'metric',
): array {
$response = $this->httpClient->request('GET', 'https://api.openweathermap.org/data/2.5/weather', [
'query' => ['q' => $city, 'appid' => $this->apiKey, 'units' => $unit, 'lang' => 'fr'],
]);
if (200 !== $response->getStatusCode()) {
throw new ToolCallException(sprintf('Ville introuvable : %s', $city));
}
$data = $response->toArray();
return [
'ville' => $data['name'],
'temperature' => $data['main']['temp'],
'description' => $data['weather'][0]['description'],
'humidite' => $data['main']['humidity'],
];
}
}
Trois points comptent ici.
D'abord, le schéma : vous ne l'écrivez pas. Les types PHP, les valeurs par défaut et l'attribut #[Schema] suffisent au SDK pour produire le JSON Schema que le modèle lira.
Ensuite, les annotations (readOnlyHint, destructiveHint…) disent au client si l'outil modifie quelque chose. Un client prudent demande une confirmation avant un outil destructeur : renseignez-les honnêtement.
Dernier point, les erreurs : une ToolCallException revient au modèle sous forme de résultat isError: true, avec votre message, ce qui lui permet de se corriger. Toute autre exception devient une erreur JSON-RPC au message générique : le modèle sait qu'il y a eu un problème, sans détail.
Un tableau retourné est envoyé au client en JSON. Pour plusieurs outils proches, une classe peut aussi porter un #[McpTool] par méthode plutôt qu'un __invoke.
Ressources et prompts
Une ressource se lit, elle ne s'exécute pas. L'exemple suit la documentation du bundle :
<?php
namespace App\Mcp;
use Mcp\Capability\Attribute\McpResource;
final class CatalogueResource
{
#[McpResource(uri: 'catalogue://conditions', name: 'conditions-generales')]
public function conditions(): array
{
return [
'uri' => 'catalogue://conditions',
'mimeType' => 'text/markdown',
'text' => file_get_contents(__DIR__.'/../../docs/conditions.md'),
];
}
}
#[McpResourceTemplate] fait la même chose avec une URI paramétrée (commande://{reference}), et #[McpPrompt] publie un modèle d'instructions. Pour lister ce qui est réellement exposé, serveur par serveur :
php bin/console debug:mcp
La commande affiche aussi, à part, les services qui portent un attribut MCP mais qu'aucun serveur ne publie.
Tester avant de brancher un assistant
Deux transports, deux façons de tester.
En STDIO, pour Claude Desktop ou un IDE sur votre poste, le serveur se lance par une commande de la console :
php bin/console mcp:server default
En HTTP, l'outil de référence est le MCP Inspector, une application Node.js publiée par le projet MCP :
npx @modelcontextprotocol/inspector http://localhost:8000/mcp
L'Inspector tourne dans votre navigateur sur une autre origine que votre application. Le transport HTTP du SDK refuse par défaut les requêtes venues d'ailleurs (protection contre le DNS rebinding) : en développement, autorisez l'origine de l'Inspector dans http.allowed_origins, par exemple ['http://localhost:6274'].
Préférez l'Inspector à un curl écrit à la main : selon la révision du protocole négociée, une requête tools/call isolée peut exiger une poignée de main préalable ou des métadonnées dans l'enveloppe, et l'Inspector gère cela pour vous.
Mettre un serveur MCP en production
Un serveur MCP public est une API comme une autre, avec une différence : c'est un modèle qui choisit quand l'appeler et avec quels arguments. Quatre réglages ne se négocient pas.
Les hôtes autorisés. Par défaut, seul localhost est accepté. Pour un serveur public, listez vos domaines dans http.allowed_hosts ; ne désactivez la protection que derrière un proxy qui valide déjà l'en-tête Host.
Un serveur par niveau de droits. servers: est une liste nommée : vous pouvez publier un serveur public sur /mcp et un serveur réservé sur /mcp/editors, chacun avec son propre registre. L'accès se règle avec la sécurité Symfony habituelle :
# config/packages/security.yaml
security:
access_control:
- { path: ^/mcp/editors, roles: ROLE_EDITOR }
Chaque serveur a son propre stockage de sessions, et le bundle refuse à la compilation une configuration où deux serveurs en partageraient un. La documentation explique pourquoi : les identifiants de session ne sont pas cloisonnés par serveur, et un partage permettrait de franchir le pare-feu.
L'autorisation OAuth. Le SDK et le bundle s'arrêtent volontairement au rôle de serveur de ressources : ils valident un jeton porteur et chargent l'utilisateur, par un pare-feu Symfony. Émettre les jetons reste le travail d'un serveur d'autorisation dédié. La documentation du bundle renvoie vers le guide d'API Platform (Keycloak, Auth0, Entra, Okta) ou, pour héberger votre propre serveur d'autorisation, vers le paquet communautaire omouren/mcp-oauth-bundle.
Le périmètre des outils. Exposez des actions métier précises (« statut d'une commande ») plutôt qu'un accès générique (« exécuter une requête SQL »). Le modèle se trompera un jour d'argument : c'est la signature de l'outil qui borne les dégâts.
Symfony comme client MCP
Le bundle fonctionne aussi dans l'autre sens : votre application consomme des serveurs MCP distants. On les déclare sous clients: :
# config/packages/mcp.yaml
mcp:
clients:
research:
servers:
github:
transport: http
url: 'https://api.githubcopilot.com/mcp/'
headers:
Authorization: 'Bearer %env(GITHUB_MCP_TOKEN)%'
Puis on injecte le client par son nom :
<?php
namespace App\Service;
use Symfony\AI\McpBundle\Client\McpClientInterface;
use Symfony\Component\DependencyInjection\Attribute\Target;
final class ResearchService
{
public function __construct(
#[Target('research')] private McpClientInterface $client,
) {
}
public function listerOutils(): iterable
{
return $this->client->get('github')->getTools();
}
}
La connexion s'ouvre à la première requête, pas à l'injection. Un échec de poignée de main lève une ConnectionException, un appel raté une RemoteCallException, toutes deux propres au bundle et au nom du client et du serveur concernés.
Ce qui reste à venir
Au 27/10/2026, la feuille de route du SDK PHP liste encore, avant sa première version majeure : l'authentification OAuth côté client, la génération de schémas à partir de TypeScript ou de JSON Schema, la conformité complète à la spécification, l'extension Tasks et le découpage du SDK en plusieurs paquets. L'autorisation côté serveur, les élicitations et le client, eux, sont livrés.
Côté bundle, la première bêta de la 1.0 est sortie le 22/10/2026 : la version stable, et avec elle la promesse de rétrocompatibilité, n'a pas encore de date publiée.
Le registre officiel des serveurs MCP (registry.modelcontextprotocol.io) répond et sert la découverte des serveurs publics. Son README annonce une API figée en v0.1 depuis octobre 2025 et une version générale à venir.
Faut-il s'y mettre maintenant ?
Si votre application Symfony a des données ou des actions qu'un assistant devrait pouvoir utiliser (catalogue, suivi de commande, base documentaire), oui : commencez par un outil en lecture seule, le code repose maintenant sur les paquets officiels. La prudence porte sur deux points, pas plus. Le statut expérimental, d'abord, impose de figer les versions. Les outils qui écrivent, ensuite, demandent une vraie réflexion sur les droits avant d'ouvrir l'accès.
Le coût du modèle qui appellera vos outils est marginal à côté de ce travail d'intégration et de sécurité. Pour comparer les tarifs actuels, nous tenons à jour une page des prix des modèles IA.
Sources (relevées le 27/10/2026)
- Packagist, fiches
mcp/sdk(v0.9.0 du 18/10/2026) etsymfony/mcp-bundle(v1.0.0-BETA1 du 22/10/2026). - Dépôt GitHub
modelcontextprotocol/php-sdk: README, documentation des outils, feuille de route (ROADMAP.md) à la version v0.9.0. - Documentation du MCP Bundle, fichier
docs/bundles/mcp-bundle.rstdu dépôtsymfony/aià la version v1.0.0-BETA1, publiée sur symfony.com/doc. - Spécification MCP, modelcontextprotocol.io : révision 2026-07-28 marquée « latest ».
- Anthropic, « Donating the Model Context Protocol and establishing the Agentic AI Foundation », 09/12/2025.
- README du dépôt
modelcontextprotocol/registry.