> For the complete documentation index, see [llms.txt](https://ovion-studio.gitbook.io/keryo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ovion-studio.gitbook.io/keryo-docs/keryo-docs-fr/developpeurs/mcp-connector.md). # Connecteur MCP Le connecteur MCP de Keryo — outils, authentification OAuth 2.1, connexion depuis un client IA et auto-hébergement. Le **connecteur Keryo** est un **serveur MCP** distant qui expose Keryo à des clients IA comme Claude. Il permet à un assistant de lister les comptes connectés, de lire les posts et les statistiques, et de créer, planifier ou publier des posts pour votre compte — en langage naturel. ## Qu'est-ce que MCP ? Le **Model Context Protocol (MCP)** est un standard ouvert qui permet aux clients IA de se connecter à des outils et des données externes via une interface de serveur bien définie. Un client MCP (l'application IA) découvre les outils qu'un serveur propose et les appelle pour le compte de l'utilisateur. Le serveur MCP de Keryo présente les actions de Keryo sous forme d'un petit ensemble d'outils. ## Outils Le connecteur Keryo expose exactement six outils. Chacun applique les **mêmes scopes** que l'endpoint REST équivalent. | Outil | Scope | Rôle | | --------------------------- | --------------- | ---------------------------------------------------------------- | | **List connected accounts** | `accounts:read` | Lister les comptes sociaux connectés d'un espace. | | **List posts** | `posts:read` | Lister les posts d'un espace. | | **Get statistics** | `stats:read` | Lire les statistiques actuelles d'une plateforme dans un espace. | | **Create a draft post** | `posts:write` | Créer un brouillon (média optionnel). | | **Schedule a post** | `posts:publish` | Planifier un brouillon existant à une date ISO-8601 future. | | **Publish a post now** | `posts:publish` | Publier immédiatement un brouillon existant (irréversible). | {% hint style="info" %} **Le gating par offre s'applique toujours.** Comme dans l'API REST, *Get statistics* requiert une offre **Studio** (ou supérieure) en plus du scope `stats:read`. Seuls **LinkedIn** et **X** sont actifs pour les statistiques à ce jour. {% endhint %} ## Authentification (OAuth 2.1) Le connecteur authentifie les utilisateurs finaux via **OAuth 2.1**. Le **backend Keryo est le serveur d'autorisation** ; le serveur MCP vérifie le jeton d'accès JWT signé par le backend et le transmet à l'API REST. * Le serveur d'autorisation publie ses métadonnées à l'adresse `/.well-known/oauth-authorization-server`. * Lorsqu'une requête arrive sans jeton valide, le serveur répond par un `401` accompagné d'un défi `WWW-Authenticate` qui oriente les clients vers les métadonnées de la ressource protégée, afin qu'ils puissent découvrir le serveur d'autorisation : ```http HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource" ``` Le client IA suit ce défi, exécute le flux OAuth 2.1 auprès du backend Keryo et obtient un jeton d'accès scopé. Le jeton porte les scopes accordés par l'utilisateur, et chaque appel d'outil est vérifié par rapport à ceux-ci. ## Connecter le connecteur Keryo dans un client IA En tant qu'utilisateur final, ajoutez le connecteur Keryo à un client IA compatible MCP (comme Claude) : 1. Dans les paramètres de connecteurs / serveurs MCP de votre client IA, **ajoutez un nouveau serveur MCP** et saisissez l'URL du serveur MCP de Keryo — par exemple `https://mcp.keryo.io`. 2. Le client découvre le serveur d'autorisation et démarre le flux **OAuth 2.1**. Connectez-vous à Keryo. 3. **Accordez les scopes** demandés par le connecteur. N'accordez que le nécessaire — pour un usage en lecture seule, vous pouvez ne pas accorder `posts:publish`. 4. Une fois l'autorisation accordée, les outils du connecteur deviennent disponibles et l'assistant peut agir sur vos espaces dans la limite des scopes accordés. {% hint style="warning" %} **La publication est irréversible.** Accorder `posts:publish` permet à l'assistant de publier immédiatement. Si vous souhaitez qu'il se limite à rédiger et planifier pour votre relecture, n'accordez pas ce scope. {% endhint %} ## Auto-héberger le serveur MCP Si vous exécutez vous-même le serveur MCP, configurez-le avec ces variables d'environnement : | Variable | Défaut | Rôle | | ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------- | | `PORT` | `3002` | Port d'écoute du serveur MCP. | | `BACKEND_URL` | — | URL du backend REST Keryo vers lequel le serveur transmet. | | `OAUTH_ISSUER_URL` | — | URL du serveur d'autorisation OAuth 2.1 (le backend Keryo). | | `PUBLIC_URL` | — | URL publique propre au serveur MCP (par ex. `https://mcp.keryo.io`). | | `JWT_SECRET` | — | Secret partagé servant à vérifier les jetons d'accès JWT signés par le backend. Doit correspondre à celui du backend. | {% hint style="danger" %} `JWT_SECRET` doit avoir la **même** valeur sur le serveur MCP et sur le backend Keryo. S'ils diffèrent, la vérification du jeton échoue et chaque appel d'outil renvoie `401`. {% endhint %} ## Pages associées * [Authentification](/keryo-docs/keryo-docs-fr/developpeurs/authentication.md) — la liste des scopes, partagée avec les clés API. * [Référence de l'API](/keryo-docs/keryo-docs-fr/developpeurs/api-reference.md) — les endpoints REST derrière chaque outil. * [Limites de débit & erreurs](/keryo-docs/keryo-docs-fr/developpeurs/rate-limits-and-errors.md) — sémantique des erreurs pour les appels d'outils.