Connecter un client

Dès MCP_ENABLED=true, l'application sert un unique point de terminaison JSON-RPC sur MCP_MOUNT_PATH — https://votre-app.example.com/mcp sauf si vous l'avez déplacé. Tout client compatible MCP peut lui parler.

La configuration générique

Claude Desktop, Claude Code, Cursor et ChatGPT Dev Mode lisent tous une forme ou une autre de bloc mcpServers :

{
  "mcpServers": {
    "sovrium": {
      "url": "https://votre-app.example.com/mcp",
      "transport": "http"
    }
  }
}

L'emplacement de ce bloc diffère selon le client — fichier de réglages, configuration de projet, panneau d'interface — mais les deux valeurs qu'il demande sont toujours les mêmes : l'URL et le transport.

S'authentifier

Il n'y a aucun mode à choisir. L'en-tête que vous envoyez détermine le vérificateur exécuté, et les deux sont actifs en même temps. Voir Authentification, RBAC et limites pour ce qu'accorde chacun.

Clé d'API. L'option la plus simple pour un script ou un job de CI. Connectez-vous avec l'utilisateur dont le client doit hériter du rôle, émettez une clé, et envoyez-la sur x-api-key. La clé agit comme son propriétaire : rétrograder ou bannir cet utilisateur prend effet dès l'appel suivant, sans rien réémettre.

x-api-key: <votre-clé-d-api>

OAuth. Pour un client capable de dérouler une connexion dans un navigateur. Enregistrez-le une fois par enregistrement dynamique, puis déroulez le flux d'autorisation ordinaire. L'enregistrement exige une session : lancez-le connecté en tant qu'administrateur, avec votre cookie de connexion dans $SOVRIUM_SESSION :

curl -X POST 'https://votre-app.example.com/api/auth/oauth2/register' \
  --header 'Content-Type: application/json' \
  --cookie "$SOVRIUM_SESSION" \
  --data '{
    "client_name": "Sovrium MCP — Claude",
    "redirect_uris": ["https://votre-app.example.com/oauth/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "client_secret_post"
  }'

Un appel au point de terminaison MCP sans identifiant répond 401 avec un en-tête de découverte WWW-Authenticate: Bearer, de sorte qu'un client conforme peut engager le flux sans qu'on le lui explique.

IDE local en stdio

Pour une intégration locale, il n'y a pas d'HTTP du tout. Définissez MCP_TRANSPORT=stdio et le client lance le binaire Sovrium en processus fils, en parlant MCP sur l'entrée et la sortie standard.

{
  "mcpServers": {
    "sovrium": {
      "command": "sovrium",
      "args": ["start", "./app.ts"],
      "env": { "MCP_ENABLED": "true", "MCP_TRANSPORT": "stdio" }
    }
  }
}

La route HTTP /mcp n'est pas montée dans ce mode. Ce sont deux alternatives, pas deux couches — choisissez-en une par processus.

Vérifier la connexion

Ne vous fiez pas à la pastille verte du client. La vérification utile la plus simple est tools/list :

curl -X POST 'https://votre-app.example.com/mcp' \
  --header 'x-api-key: <votre-clé-d-api>' \
  --header 'Content-Type: application/json' \
  --data '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

La réponse liste exactement les outils que votre identifiant peut appeler — les tables, actions et automatisations marquées d'un aiAccess, filtrées par le rôle derrière l'identifiant.

C'est cette dernière proposition qui rend l'exercice utile. Exécutez-le tour à tour avec une clé détenue par un admin puis une clé détenue par un viewer : deux listes différentes prouvent que le filtrage par rôle est actif. Une liste identique signale un problème d'identifiants, pas de schéma.

Pages associées

• Présentation de MCP — activer le serveur.
• Mode serveur — ce qui apparaît dans tools/list et pourquoi.
• Authentification, RBAC et limites — jetons, OAuth et quotas.
• Connecter Claude via MCP — une mise en place complète.
• Serveur OAuth — le greffon OAuth derrière le mode oauth2.