Skip to main content
View as Markdown

Intégration MCP

Le Model Context Protocol (MCP) est un standard ouvert pour connecter les assistants IA aux outils et données. Sovrium parle MCP dans les deux sens :

  • Mode serveur — des clients IA externes (Claude Desktop, Claude Code, ChatGPT Dev Mode, Cursor) se connectent à Sovrium et appellent des outils générés : CRUD de table, invocation d'automatisation manuelle, et exécution de modèle d'action.
  • Mode client — les agents Sovrium appellent des outils hébergés sur des serveurs MCP externes (recherche web, récupération de documents, exécution de code) dans le cadre de leurs flux de travail.

Les deux modes sont configurés indépendamment et servent des rôles opposés.

Mode Contrôlé par Où LLM requis sur Sovrium ?
Serveur Opérateur (env) MCP_ENABLED, MCP_TRANSPORT, … Non — le LLM vit chez le client connecté
Client Auteur de schéma Bloc mcp.allowedTools d'un agent Oui — AI_PROVIDER défini

Mode serveur

Activation

Le serveur MCP est désactivé par défaut. L'opérateur s'engage via des variables d'environnement ; le serveur ne monte la route /mcp que lorsque MCP_ENABLED=true.

Variable Description Défaut
MCP_ENABLED Interrupteur principal — monte la route MCP uniquement lorsque true. false
MCP_TRANSPORT streamable-http pour les clients distants, stdio pour l'intégration IDE locale. streamable-http
MCP_MOUNT_PATH Préfixe de route lorsque le transport est streamable-http. /mcp
MCP_AUTH_STRATEGY oauth2 (lorsque app.auth est configuré) ou token. oauth2 lorsque auth câblé
MCP_TOKEN_ADMIN Jeton bearer accordant le rôle admin (≥32 caractères ; openssl rand -hex 32). —
MCP_TOKEN_MEMBER Jeton bearer accordant le rôle member (≥32 caractères). —
MCP_TOKEN_VIEWER Jeton bearer accordant le rôle viewer (≥32 caractères). —
MCP_RATE_LIMIT_PER_MINUTE Requêtes par jeton par minute. 60
MCP_RATE_LIMIT_PER_DAY Requêtes par jeton par jour. 5000
MCP_AUDIT_ENABLED Journaliser chaque appel d'outil dans system.ai_tool_calls + le flux d'activité. true
MCP_EXPOSE_INTERNALS Exposer les tables auth/system en lecture seule au rôle admin. true
MCP_CONFIRM_DESTRUCTIVE Compiler destructiveHint=true sur les outils de suppression et les automatisations non idempotentes. true 
MCP_ENABLED=true
MCP_TRANSPORT=streamable-http
MCP_AUTH_STRATEGY=token
MCP_TOKEN_ADMIN=$(openssl rand -hex 32)
MCP_TOKEN_VIEWER=$(openssl rand -hex 32)

Surfaces exposées

Lorsqu'il est monté, le serveur génère des outils à partir de quatre surfaces — toutes encadrées par RBAC et aiAccess :

/mcp ─── tools/list ───▶ filtré par le rôle connecté
            │
   ┌────────┴───────────────────────────────────┐
   │ 1. Tables utilisateur  {app}_{table}_{op}     │  CRUD
   │ 2. Automatisations manuelles {app}_automation_{name}│ invocation
   │ 3. Modèles d'action    {app}_action_{name}    │  exécution
   │ 4. Internes admin      {app}_auth_*_read/_list │  lecture seule, secrets en liste noire
   └─────────────────────────────────────────────┘
            │
   Audit → system.ai_tool_calls   Limite de débit → par jeton / client_id OAuth

Déclarer les entités éligibles à l'IA

Un auteur de schéma marque une entité comme éligible à l'exposition MCP avec aiAccess. Cela déclare l'intention ; l'opérateur doit encore activer le serveur avec MCP_ENABLED. aiAccess s'applique de manière identique à app.tables[], aux app.automations[] à déclenchement manuel, et à app.actions[].

Il prend deux formes — un raccourci booléen ou un objet de configuration riche :

# Raccourci booléen — activer avec les valeurs par défaut.
tables:
  - name: contacts
    aiAccess: true
# Config riche — fournir un objet EST le signal d'activation (pas de champ `enabled`).
tables:
  - name: contacts
    aiAccess:
      description: Customer contacts. Use this when the user asks about people.
      operations: [read, list, create, update]
      fieldExposure: permissioned
      annotations:
        readOnly: false
        destructive: false
Propriété Description
description Description d'outil écrite à la main montrée au client IA — le plus grand levier pour orienter le comportement de l'IA.
operations Sous-ensemble de read, list, create, update, delete à exposer (les tables exposent les cinq par défaut).
fieldExposure permissioned (par défaut — uniquement les champs que le rôle peut lire/écrire), all, ou whitelist.
whitelistFields Champs à exposer lorsque fieldExposure: whitelist (requis et non vide dans ce mode).
annotations Indices de risque MCP — voir ci-dessous.
requireConfirmation Forcer destructiveHint=true quel que soit le type d'opération (ex. pour les automatisations envoyant des e-mails).

Annotations de risque d'outil

Les annotations se compilent dans les définitions d'outils MCP afin que les clients puissent décider d'approuver automatiquement un appel ou d'exiger une confirmation. Elles correspondent directement à la spécification MCP :

Annotation Indice MCP Signification
readOnly readOnlyHint L'outil lit uniquement des données ; sûr à approuver automatiquement.
destructive destructiveHint Effectue des opérations destructrices ; les clients devraient exiger une confirmation.
idempotent idempotentHint Appeler deux fois avec les mêmes arguments est sûr (pas d'effets de bord dupliqués).
openWorld openWorldHint Atteint l'extérieur de l'application locale (API externe, appel réseau).

Des valeurs par défaut raisonnables sont dérivées du type d'opération lorsque les annotations ne sont pas définies.

Authentification

Stratégie Quand Comment
token Par défaut lorsque app.auth est absent Jetons bearer statiques par rôle (MCP_TOKEN_ADMIN/MEMBER/VIEWER). Au moins un doit être défini.
oauth2 Par défaut lorsque app.auth est câblé OAuth 2.1 contre le plugin serveur OAuth de Better Auth.

Le rôle de la crédentielle connectée pilote le RBAC : un jeton viewer ne peut que lire/lister même lorsque l'aiAccess.operations d'une entité autorise les écritures. La validation de démarrage rejette MCP_AUTH_STRATEGY=token sans jeton défini, et oauth2 lorsque app.auth n'est pas configuré.

RBAC, audit & limitation de débit

  • RBAC — les clients MCP sont régis par les mêmes permissions de rôle et règles au niveau des lignes que les sessions humaines. Il n'y a aucun contournement IA.
  • Audit — chaque appel d'outil est journalisé dans system.ai_tool_calls et le flux d'activité lorsque MCP_AUDIT_ENABLED est true (la valeur par défaut).
  • Limitation de débit — appliquée par jeton (ou client_id OAuth) ; les requêtes hors limite retournent 429 avec des en-têtes de limitation de débit standard.

Internes admin

Lorsque MCP_EXPOSE_INTERNALS=true (la valeur par défaut), le rôle admin obtient des outils en lecture seule sur les tables des schémas auth et system ({app}_auth_*_read/_list, {app}_system_*_read/_list), avec les colonnes de secrets en liste noire. Définissez-le à false pour retirer tous les outils internes de tools/list, même pour les admins.

Mode client

Les agents Sovrium peuvent consommer des outils depuis des serveurs MCP externes. Le bloc mcp d'un agent définit la liste blanche de noms d'outils externes qu'il peut invoquer.

agents:
  - name: research-agent
    role: analyst
    systemPrompt: Research topics using approved external tools.
    mcp:
      allowedTools: [web_search, fetch_url]
Propriété Description
mcp.allowedTools Noms d'outils MCP externes que l'agent est autorisé à utiliser.

Ceci complète la liste blanche tools interne de l'agent : tools délimite ce que l'agent peut faire à l'intérieur de Sovrium, tandis que mcp.allowedTools délimite quels outils MCP externes il peut appeler.

Pages connexes