MCP V1.1 — Transport HTTP Streamable (TLR-006)

Contexte : tlr-mcp v0.1.3 ne supporte que le transport stdio (mcp:serve). Pour que les instances Claude Code se connectent directement au VPS sans dépendance locale (WSL + PHP), il faut implémenter le transport HTTP Streamable (spec MCP 2025-11-25). Résultat : un .mcp.json réduit à une URL, zéro WSL.

Spec V1 stdio de référence : ia-mcp.md.

1. Architecture cible

Claude Code (.mcp.json)
  └─ url: https://mcp.telaria.dev/mcp
  └─ Authorization: Bearer <token>
          │
VPS — Apache
  └─ mcp.telaria.dev → DocumentRoot /var/www/telaria-dev/public
      └─ POST /mcp  ← JSON-RPC (réponse JSON)
      └─ GET  /mcp  ← ouverture canal SSE (optionnel V1.1)

2. Périmètre `tlr-mcp` bundle

2.1 Nouveau contrôleur `McpHttpController`

src/Controller/McpHttpController.php

Route POST /mcp — chemin principal :

Lire Authorization: Bearer <token> → 401 si absent
Valider le token : hash('sha256', $token) → lookup mcp_api_client.token_hash → 401 si invalide
Vérifier non révoqué + scopes → 403 si insuffisant
Résoudre tenant/projet depuis mcp_api_client → mcp_project → mcp_tenant
Parser le body JSON-RPC 2.0
Dispatcher via ExecutionPipeline (même logique que stdio)
Logger dans mcp_tool_audit_log
Retourner la réponse JSON-RPC (Content-Type: application/json)

Route GET /mcp — canal SSE (optionnel) :

Retourner Content-Type: text/event-stream avec un événement endpoint
Permet aux clients MCP conformes 2025-11-25 de négocier le mode streaming

Header MCP-Session-Id :

Première requête : générer un UUID v4, le renvoyer dans le header MCP-Session-Id
Requêtes suivantes : si le header est présent, le valider (optionnel V1.1 — log seulement)

Erreurs auth standardisées :

Cas	HTTP	Code JSON-RPC
Token absent	401	`-32001` `AUTH_REQUIRED`
Token invalide / révoqué	401	`-32001` `AUTH_REQUIRED`
Scope manquant	403	`-32003` `FORBIDDEN_TOOL`

2.2 Auto-montage dans Symfony

Route déclarée dans Resources/config/routes.xml du bundle — telaria-app l'hérite sans modification de ses propres fichiers de config.

Aucune modification de security.yaml dans telaria-app — l'auth est entièrement gérée dans le contrôleur (stateless).

3. Infrastructure VPS

3.1 Sous-domaine `mcp.telaria.dev`

Nouveau vhost Apache sur le VPS staging. À intégrer dans tlr-ansible / tlr-vhosts.

<VirtualHost *:443>
    ServerName mcp.telaria.dev

    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/telaria.dev/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/telaria.dev/privkey.pem

    DocumentRoot /var/www/telaria-dev/public

    <FilesMatch \.php$>
        SetHandler "proxy:unix:/run/php/php8.5-fpm.sock|fcgi://localhost"
    </FilesMatch>

    <Directory /var/www/telaria-dev/public>
        AllowOverride None
        Require all granted
        FallbackResource /index.php
    </Directory>

    ErrorLog  ${APACHE_LOG_DIR}/mcp-telaria-dev-error.log
    CustomLog ${APACHE_LOG_DIR}/mcp-telaria-dev-access.log combined
</VirtualHost>

Le sous-domaine partage le DocumentRoot de telaria.dev — même app Symfony, Symfony dispatche sur /mcp.

3.2 DNS + Certbot

DNS : ajouter entrée mcp.telaria.dev → même IP que telaria.dev
Certbot : étendre le certificat existant (--expand) ou obtenir un certificat dédié

4. `.mcp.json` par instance (après livraison)

{
  "mcpServers": {
    "tlr-mcp": {
      "url": "https://mcp.telaria.dev/mcp",
      "headers": {
        "Authorization": "Bearer <token-instance>"
      }
    }
  }
}

Instance	Dépôt	Token
Atlas	`C:/src/tlr-doc`	client id=1, déjà seedé sur telaria-dev
Lead Tech	`C:/src/telaria-app`	à générer après livraison
Chef	`C:/src/tlr-blueprint`	à générer après livraison

Les tokens sont émis via app:mcp:seed sur le VPS staging (cf. mcp-mise-en-service.md).

5. Tests

ContainerWiringTest : vérifier que McpHttpController est dans le conteneur
Test fonctionnel : POST /mcp avec token valide → réponse JSON-RPC 200
Test fonctionnel : POST /mcp sans token → 401
Test fonctionnel : POST /mcp token révoqué → 403

6. Hors périmètre V1.1

SSE full streaming des résultats d'outils (réponses synchrones suffisantes en V1.1)
Multi-tenant HTTP dynamique
Invalidation de session active (MCP-Session-Id en lecture seule)
Déploiement prod telaria.fr — staging d'abord, prod après feu vert Chef

Références

Spec MCP 2025-11-25 — Streamable HTTP transport
Spec V1 stdio : ia-mcp.md
Guide mise en service : mcp-mise-en-service.md
Gouvernance tokens : mcp-gouvernance-instances.md