API MCP (Model Context Protocol)

Le protocole MCP (Model Context Protocol) de Kotbo permet de connecter une intelligence artificielle externe (comme Claude.ai ou ChatGPT) directement à votre serveur Discord. L’IA peut alors lire des données ou exécuter des actions de modération selon des droits strictement définis.

Fonctionnalité en Bêta

L’intégration MCP est actuellement en phase de test. Les fonctionnalités et l’interface de connexion peuvent encore évoluer.

---

Qu’est-ce que le MCP ?

Le MCP est un standard ouvert permettant à un modèle d’IA d’interagir avec des outils et des bases de données externes. Grâce au serveur MCP exposé par Kotbo, votre IA peut devenir un assistant d’administration ou d’animation puissant en disposant d’un contexte en temps réel sur la vie de votre serveur.

---

Étape 1 : Créer une clé d’accès MCP

Pour connecter une IA, vous devez générer des identifiants dédiés à partir du dashboard de Kotbo.

1. Allez dans Configuration → API MCP (Accéder à l’API MCP ↗).
2. Cliquez sur le bouton Nouvelle clé en haut à droite.
3. Saisissez un Nom de clé pour l’identifier facilement (ex: Claude Web, ChatGPT Staff).
4. Configurez les permissions de la clé. Cochez uniquement ce qui est nécessaire pour l’usage prévu.

Permissions de Lecture (READ)

• Stats serveur : Membres, messages, activité.
• Membres & messages : Profils, messages récents, lecture des forums et articles.
• Sanctions : Liste et historique.
• Staff : Liste et profils du staff.
• Tickets : Liste des tickets ouverts.
• Communauté : Classements, suggestions, événements, quêtes, réputation, accueil personnalisé, paris de clan et dettes.
• Économie : Profils RPG, boutique, marketplace, classements économiques.
• Modération : AutoMod, mots bannis, réponses auto, CodePolice.
• Analytics : Stats par salon, heatmap horaire, Pulse, prédictions.
• Lire les automatisations : Consulter les automatisations, leur historique d’exécution et le catalogue de blocs disponibles.

Permissions d’Écriture (WRITE)

Permissions sensibles

Les permissions d’écriture permettent à l’IA d’effectuer des modifications réelles sur votre serveur. Soyez vigilants.

• Sanctionner : Appliquer ou lever des sanctions via l’IA.
• Gérer messages : Envoyer, éditer ou supprimer des messages, et gérer forums, articles et tags.
• Gérer tickets : Répondre aux tickets et les fermer via l’IA.
• Gérer communauté : Répondre aux suggestions, gérer événements et giveaways, le pipeline d’accueil personnalisé, trancher et annuler les paris de clan.
• Gérer membres : Notes modérateur, ajout et retrait de rôles, niveaux, invitations.
• Gérer les automatisations : Créer, modifier, activer et supprimer des automatisations.

La permission qui agit sans vous

Gérer les automatisations est la seule qui laisse une trace durable : une automatisation activée par l’IA agit ensuite seule, y compris pour sanctionner. Ne l’accordez qu’à une clé de confiance.

5. Cliquez sur Générer la clé.
6. IMPORTANT : Une fenêtre s’affiche avec votre Client ID et votre Client Secret (qui commence par mcp_). Copiez et sauvegardez ces informations immédiatement. Le Client Secret ne sera plus jamais affiché en clair par la suite.

Une clé suit son porteur

Une clé est rattachée au compte qui l’a créée : elle cesse de répondre si ce compte perd ses droits sur le serveur.

Les clés créées avant cette règle portent la mention Sans propriétaire : elle continue de répondre même si celui qui s’en sert perd ses droits sur le serveur. Révoquez-la et recréez-la pour qu’elle suive son porteur.

---

Étape 2 : Configurer votre client IA

Sélectionnez votre intelligence artificielle pour afficher les instructions de configuration :

Claude.ai

Claude de Anthropic prend en charge les serveurs MCP distants sous forme de connecteurs personnalisés (Custom Connectors).

1. Ouvrez Claude.ai et accédez à vos paramètres en cliquant sur votre profil, puis allez dans Customize → Connectors (ou cliquez sur le bouton disponible dans l’aide de connexion de Kotbo).
2. Cliquez sur le bouton + puis choisissez Add custom connector.
3. Saisissez les informations suivantes :
   • Name : Kotbo
   • URL : Dans le dashboard Kotbo, dans la ligne de votre clé MCP, cliquez sur Générer l’URL directe Claude et copiez-la. Collez cette URL longue signée sur Claude.
   • Note : Laissez les champs optionnels (Client ID, Client Secret, Advanced) vides lorsque vous utilisez l’URL directe.
4. Cliquez sur Add. Claude est désormais connecté à Kotbo !

En cas d’échec d’autorisation

Si Claude affiche une erreur « Authorization failed » après connexion, utilisez l’URL directe Claude générée par le dashboard plutôt que l’URL standard du serveur MCP. Cette URL signée contourne les blocages d’autorisation réseau de Claude.

ChatGPT

ChatGPT d’OpenAI permet d’ajouter des serveurs MCP distants en activant le mode développeur.

1. Ouvrez ChatGPT sur le web.
2. Allez dans vos paramètres : Settings → Apps → Advanced settings.
3. Cochez l’interrupteur Developer mode pour l’activer.
4. Cliquez sur Create app et sélectionnez l’option pour ajouter un serveur MCP distant.
5. Saisissez les paramètres de connexion :
   • App name : Kotbo
   • MCP server URL : Copiez l’URL du serveur MCP (Endpoint URL) affichée en haut de la page API MCP de votre dashboard Kotbo (format https://api.kotbo.fr/api/mcp/ID_SERVEUR).
   • Authentication : Sélectionnez OAuth ou Mixed Authentication.
6. Validez. Lors de votre première discussion avec ChatGPT sollicitant le bot, une fenêtre d’autorisation Kotbo s’ouvrira : saisissez votre clé d’accès MCP pour finaliser l’association.

---

Intégrations personnalisées (API & Gemini)

Si vous développez votre propre client MCP (ex: via les SDK MCP de Google pour Gemini, ou Python/TypeScript) :

L’authentification s’effectue en transmettant la clé d’accès sous forme de Bearer Token dans l’en-tête de vos requêtes HTTP.

Exemple de configuration JSON pour un serveur MCP :

{
  "type": "mcp_server",
  "name": "Kotbo",
  "url": "https://api-kotbo-url/api/mcp/VOTRE_ID_SERVEUR",
  "headers": {
    "Authorization": "Bearer mcp_VOTRE_CLIENT_SECRET"
  }
}

(Remplacez mcp_VOTRE_CLIENT_SECRET par le Client Secret complet copié à la création).

---

Diagnostics et Logs

Si l’IA n’arrive pas à lire les informations ou si des requêtes échouent, vous pouvez consulter les logs en temps réel.

1. Allez dans Configuration → API MCP.
2. À côté de l’URL de votre Endpoint, cliquez sur le bouton Logs.
3. Vous y verrez toutes les connexions entrantes récentes, les méthodes appelées (ex: listTools, callTool) ainsi que les erreurs éventuelles retournées par le bot.