Telaria MCP - Exploitation, coûts et observabilité

Ce document couvre le troubleshooting et l'observabilité du serveur MCP Telaria en production.

1. Métriques tokens (Telaria)

Les tokens MCP ne passent pas par Claude directement — le serveur MCP V1 est lecture seule (RAG, pas de génération). Les métriques Anthropic sont gérées côté tlr-codexia :

• metrics_usage — usage brut par (jour, modèle, clé API, service tier)
• metrics_daily — snapshot org-wide quotidien (tokens + coûts)
• metrics_alert — seuils USD avec anti-spam (1 mail/franchissement/période)
• Synchronisation : php bin/console app:sync:metrics

Pour le MCP lui-même, la traçabilité est dans mcp_tool_audit_log (outil, statut, client, timestamp) — voir §7 ci-dessous.

2. Observabilité

Chaque appel tools/call est enregistré dans mcp_tool_audit_log avant toute exécution. L'audit log est dénormalisé délibérément — la suppression d'un tenant n'efface pas l'historique.

Requêtes de supervision standard → voir tlr-mcp-data-model.md §SQL.

3. Troubleshooting

Token refusé — refused dans l'audit log

-- Identifier le client et ses scopes
SELECT ac.id, ac.scopes, ac.revoked, ac.expires_at
FROM mcp_api_client ac
WHERE ac.token_hash = SHA2('<token>', 256);

Causes courantes :

• Scope manquant : le token n'a pas tool:<name> ou project:<slug> — recréer via app:mcp:seed.
• Token révoqué : revoked=1 — recréer un client.
• Token expiré : expires_at dans le passé.
• Rate limit dépassé : quota (tenant, outil) atteint — vérifier rate_limit_per_minute sur mcp_api_client.

Outil non trouvé — METHOD_NOT_FOUND (-32601)

Le ToolRegistry ne trouve pas l'outil demandé. Vérifier que le service PHP est tagué mcp.tool dans services.yaml et que le bundle est enregistré dans bundles.php.

Résultats search_docs vides ou non pertinents

1. L'index RAG est vide → php bin/console app:rag:stats puis app:rag:ingest --full.
2. Le root_path du mcp_project ne correspond pas à la racine indexée.
3. Seuil de score trop élevé → ajuster retrieval.k dans telaria_rag.yaml.

Audit log : diagnostiquer une session complète

SELECT timestamp, tool_name, status, error_code, api_client_id
FROM mcp_tool_audit_log
WHERE tenant_id = <id>
ORDER BY timestamp DESC
LIMIT 50;

4. Voir aussi

• tlr-mcp-data-model.md — entités BDD complètes + requêtes SQL de diagnostic
• tlr-mcp-securite-conformite.md — tokens, scopes, RGPD
• ../../../03-comment-je-travaille/guides/runbook.md — runbook VPS complet (déploiement, incidents, rollback)