Aller au contenu

Synapse MCP

Le package synapse-mcp expose une interface Model Context Protocol (MCP) qui permet à un client MCP (Claude Desktop, etc.) d'interagir directement avec Synapse : lister les agents et presets, créer des entités temporaires de test (sandbox), exécuter des workflows et inspecter les résultats.

Vue d'ensemble des outils

Outils de lecture

Outil Description
list_agents Liste les agents disponibles (DB + code, clé, nom, preset, outils, statut)
list_presets Liste les presets disponibles (provider, modèle, paramètres)
list_models Liste tous les modèles LLM du catalogue, groupés par provider
list_workflows Liste les workflows disponibles

Outils d'exécution

Outil Description
run_agent_test Exécute un agent (DB ou code) et retourne la réponse avec métriques
run_workflow Exécute un workflow complet via WorkflowRunner
inspect_agent_debug Inspecte un log de debug par debugId
inspect_workflow_run Inspecte un run de workflow par workflowRunId

Outils d'administration

Outil Description
update_agent_system_prompt Propose une nouvelle version de prompt (HITL Guardrail #3)
update_agent Met à jour les métadonnées d'un agent (nom, description, preset, outils, statut)
update_preset Met à jour les paramètres d'un preset LLM
update_workflow Met à jour la définition d'un workflow
delete_agent Supprime un agent (avec vérification de dépendances)
delete_preset Supprime un preset (avec vérification de dépendances)
delete_workflow Supprime un workflow (avec vérification de dépendances)

Outils Sandbox

Ces outils constituent le cycle de vie complet pour les tests autonomes :

Outil Description
create_sandbox_preset Crée un preset temporaire
create_sandbox_agent Crée un agent temporaire
create_sandbox_workflow Assemble un pipeline multi-agents temporaire
cleanup_sandbox Supprime toutes les entités sandbox

Prérequis

  • synapse-core installé et configuré
  • PermissionCheckerInterface implémentée (les outils vérifient canAccessAdmin())
  • Un client MCP (ex : Claude Desktop) connecté via le transport HTTP ou stdio

Pattern Sandbox

Le pattern sandbox est le mécanisme central de la Phase 10. Il permet à un client MCP de créer des entités temporaires (preset + agent + workflow) pour tester une configuration complète, puis de tout nettoyer en une seule opération.

Les entités sandbox sont :

  • invisibles dans l'admin et le chat (filtrées par findAllActive(), findAllOrdered(), findAllPresets())
  • résolvables pour l'exécution (findByKey() et findActiveByKey() ne filtrent pas isSandbox)
  • nettoyables en bloc via cleanup_sandbox

Voir Sandbox — guide complet.

Sécurité

Tous les outils MCP vérifient PermissionCheckerInterface::canAccessAdmin() avant toute opération. Si l'utilisateur MCP n'a pas les droits admin, l'outil retourne :

{
  "status": "error",
  "error": "Access denied. Admin role required."
}

Voir PermissionCheckerInterface.