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

L'identifiant à envoyer dépend de MCP_AUTH_STRATEGY. Voir Authentification, RBAC et limites pour ce qu'accorde chacun.

Mode jeton. Envoyez le jeton bearer du rôle à chaque requête. Le jeton est le rôle — un jeton viewer ne verra jamais que les outils de lecture et de listage.

Authorization: Bearer <MCP_TOKEN_ADMIN>

Mode OAuth. Lorsque app.auth est configuré, enregistrez un client une fois par enregistrement dynamique, puis déroulez le flux d'autorisation ordinaire :

curl -X POST 'https://votre-app.example.com/api/auth/oauth2/register' \
  --header 'Content-Type: application/json' \
  --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"
  }'

Une requête non authentifiée 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 'Authorization: Bearer <MCP_TOKEN_ADMIN>' \
  --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 un jeton admin puis un jeton 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.