Serveur MCP — Model Context Protocol

MCP (Model Context Protocol) est un protocole qui permet à un LLM (Claude, etc.) d'appeler des outils externes et d'accéder à des ressources contextuelles. Telaria expose son corpus documentaire via un serveur MCP.

1. Rôle du serveur MCP Telaria

Sans MCP, Claude ne connaît que ce qu'on lui donne dans le prompt. Avec le serveur MCP Telaria, Claude peut interroger le corpus documentaire (telaria-doc, adoption-corpus) en temps réel, via des outils formels.

Utilisateur → Claude Desktop / Cursor
                │  "Quelles sont les entités Doctrine de Telaria ?"
                ▼
            Claude → appel outil MCP → list_docs / search_docs / read_doc
                │
                ▼
            Serveur MCP Telaria (tlr-mcp)
                │  cherche dans l'index RAG
                ▼
            Réponse contextualisée → Claude → Utilisateur

2. Le bundle tlr-mcp

Package Composer : telaria/mcp-bundle
Namespace : Telaria\Mcp\
Version courante : v0.1.3

3 outils exposés

list_docs — authentification optionnelle

tools/list est accessible sans auth (permet aux clients MCP de découvrir les outils disponibles). Les appels aux outils eux-mêmes requièrent un token valide.

3. Authentification par token opaque

Chaque client MCP reçoit un token opaque (chaîne aléatoire). Le serveur stocke le hash SHA-512 du token, jamais le token en clair.

Génération d'un token

php bin/console app:token:generate
# Sortie :
# Token (à transmettre au client) : tlr_abc123...xyz
# Hash stocké en BDD : 7f3a... (SHA-512)

Vérification à chaque requête MCP

// MCP Authenticator
$hash = hash('sha512', $tokenFromHeader);
$tenant = $this->tokenRepository->findByHash($hash);

if (!$tenant || !hash_equals($tenant->getHash(), $hash)) {
    throw new UnauthorizedHttpException('Bearer');
}

4. Quotas par tenant et par outil

Chaque tenant (client) a des quotas définis par outil, sur fenêtre glissante.

# config/packages/telaria_mcp.yaml
telaria_mcp:
    quotas:
        default:
            list_docs:   { limit: 100, window: 3600 }   # 100 appels/heure
            read_doc:    { limit: 200, window: 3600 }
            search_docs: { limit: 50,  window: 3600 }

Les quotas sont vérifiés avant chaque appel outil. Dépassement → HTTP 429 Too Many Requests avec header Retry-After.

5. Format de requête MCP (JSON-RPC 2.0)

Le serveur implémente le protocole MCP sur HTTP, en JSON-RPC 2.0.

Initialisation :

POST /mcp HTTP/1.1
Authorization: Bearer tlr_abc123...xyz
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": { "name": "claude-desktop", "version": "1.0" }
  },
  "id": 1
}

Appel outil :

POST /mcp HTTP/1.1
Authorization: Bearer tlr_abc123...xyz

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_docs",
    "arguments": { "query": "configuration OpenDKIM multi-NDD", "k": 5 }
  },
  "id": 2
}

6. Intégration Claude Desktop

Fichier de configuration : ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows).

{
  "mcpServers": {
    "telaria": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "SERVER_URL": "https://telaria.dev/mcp",
        "AUTH_TOKEN": "tlr_abc123...xyz"
      }
    }
  }
}

En pratique, Telaria utilise un serveur MCP HTTP (pas stdio). Le client doit supporter le transport HTTP — Claude Desktop le supporte depuis la version 1.x via le proxy server-fetch.

7. Intégration Cursor

Fichier : .cursor/mcp.json à la racine du projet.

{
  "mcpServers": {
    "telaria": {
      "url": "https://telaria.dev/mcp",
      "headers": {
        "Authorization": "Bearer tlr_abc123...xyz"
      }
    }
  }
}

8. Le MCP comme pont entre deux corpus

Le serveur MCP Telaria peut servir deux corpus distincts avec le même protocole :

Un même client Claude peut interroger les deux via search_docs, en passant un paramètre de corpus optionnel. Un développeur qui conçoit et maintient les deux corpus : c'est le différenciateur de Telaria.

9. Déploiement

Le bundle tlr-mcp est une dépendance Composer de telaria-app. Il n'a pas de déploiement séparé.

# Vérifier que le bundle est installé
composer show telaria/mcp-bundle

# Vérifier la route MCP
php bin/console router:match /mcp
# → Tlr\Mcp\Controller\McpController::handle

# Tester l'endpoint (sans auth → liste des outils uniquement)
curl https://telaria.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

10. Pièges connus

Documentation complète — fin du cycle VPS→prod.

Voir aussi : ../guides/stack-production.md pour la carte d'identité de la stack.