github-actions[bot]
2b3b2362db
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
142 lines
7.7 KiB
Plaintext
142 lines
7.7 KiB
Plaintext
---
|
|
title: Serveur MCP
|
|
description: Connectez des assistants IA à votre espace de travail Twenty à l'aide du Model Context Protocol.
|
|
---
|
|
|
|
<Warning>
|
|
MCP est actuellement en **alpha** et n'est disponible que sur certains espaces de travail. Il se peut qu'il ne soit pas encore activé pour votre espace de travail.
|
|
</Warning>
|
|
|
|
Twenty expose un serveur [MCP](https://modelcontextprotocol.io/) afin que les assistants IA — Claude Desktop, Claude Code, Cursor, ChatGPT et autres — puissent lire et écrire vos données CRM en langage naturel.
|
|
|
|
Utilisez l'**URL de votre espace de travail** (l'URL que vous utilisez pour accéder à Twenty) comme point de terminaison MCP. Sur Twenty Cloud, l'URL de votre espace de travail peut être `https://{mycompany}.twenty.com` ou un domaine personnalisé. Le serveur est disponible à l'adresse :
|
|
|
|
| Environnement | Point de terminaison MCP |
|
|
| ---------------- | ----------------------------------------------------------------------------------- |
|
|
| **Cloud** | `https://{your-workspace-url}/mcp` (par exemple `https://mycompany.twenty.com/mcp`) |
|
|
| **Auto-hébergé** | `https://{your-domain}/mcp` |
|
|
|
|
## Méthodes d'authentification
|
|
|
|
Vous disposez de deux moyens d'authentifier votre client MCP : **OAuth** (recommandé) ou **clé API**.
|
|
|
|
### Option A — OAuth (recommandé)
|
|
|
|
Avec OAuth, votre client MCP ouvre une fenêtre de navigateur pour que vous puissiez vous connecter. Aucun secret n'est stocké dans les fichiers de configuration et les jetons se renouvellent automatiquement.
|
|
|
|
<Note>
|
|
OAuth nécessite un client MCP qui prend en charge la [spécification MCP Authorization](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor et ChatGPT la prennent en charge.
|
|
</Note>
|
|
|
|
Ajoutez ceci à la configuration de votre client MCP, en remplaçant `{your-workspace-url}` par l'hôte de votre espace de travail (par exemple `mycompany.twenty.com`) :
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"twenty": {
|
|
"type": "streamable-http",
|
|
"url": "https://{your-workspace-url}/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Et voilà — aucune clé API n'est nécessaire. Lorsque le client se connecte pour la première fois, il va :
|
|
|
|
1. Découvrir les métadonnées OAuth de Twenty via `/.well-known/oauth-protected-resource` et `/.well-known/oauth-authorization-server`
|
|
2. S'enregistrer comme client OAuth via l'enregistrement dynamique de client (RFC 7591)
|
|
3. Ouvrir votre navigateur pour autoriser l'accès
|
|
4. Recevoir des jetons et se connecter au serveur MCP
|
|
|
|
Les connexions suivantes réutilisent les jetons stockés et les actualisent automatiquement.
|
|
|
|
### Option B — Clé API
|
|
|
|
Si votre client MCP ne prend pas en charge OAuth, ou si vous préférez des identifiants statiques, transmettez une clé API dans l'en-tête `Authorization` :
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"twenty": {
|
|
"type": "streamable-http",
|
|
"url": "https://{your-workspace-url}/mcp",
|
|
"headers": {
|
|
"Authorization": "Bearer YOUR_API_KEY"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<Warning>
|
|
Votre clé API donne accès aux données de votre espace de travail. Ne l'ajoutez pas au contrôle de version et évitez de la placer dans des fichiers de configuration partagés.
|
|
</Warning>
|
|
|
|
Pour créer une clé API, allez dans **Paramètres > APIs & Webhooks > + Créer une clé**. Voir [APIs](/l/fr/developers/extend/api#create-an-api-key) pour plus de détails.
|
|
|
|
## Démarrage rapide
|
|
|
|
### 1. Copiez la configuration
|
|
|
|
Allez dans **Paramètres > IA > Plus > MCP Server** dans Twenty. Choisissez votre méthode d'authentification (OAuth ou clé API), copiez l'extrait JSON (il utilisera déjà l'URL de votre espace de travail) et collez-le dans le fichier de configuration de votre client MCP.
|
|
|
|
| Client | Emplacement du fichier de configuration |
|
|
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
|
|
| **Claude Code** | `~/.claude.json` (utilisateur) ou `.mcp.json` (projet) |
|
|
| **Cursor** | `.cursor/mcp.json` dans votre projet, ou `~/.cursor/mcp.json` globalement |
|
|
| **ChatGPT** | Activez le mode Développeur dans **Paramètres > Applications et connecteurs > Paramètres avancés**, puis utilisez **Créer** dans **Paramètres > Applications et connecteurs** pour ajouter le serveur MCP |
|
|
|
|
### 2. Se connecter
|
|
|
|
Redémarrez votre client MCP (ou rechargez la configuration). Si vous utilisez OAuth, vous serez redirigé vers Twenty pour autoriser l'accès. Si vous utilisez une clé API, la connexion est immédiate.
|
|
|
|
### 3. Commencez à l'utiliser
|
|
|
|
Demandez à votre assistant IA d'interagir avec votre CRM :
|
|
|
|
* *"Montre-moi les 5 entreprises créées le plus récemment"*
|
|
* *"Crée une nouvelle personne nommée Jane Doe chez Acme Corp"*
|
|
* *"Trouve toutes les opportunités ouvertes d'une valeur supérieure à 10 000 $"*
|
|
|
|
## Outils disponibles
|
|
|
|
Une fois connecté, le serveur MCP expose des outils qui reflètent l'API de Twenty. Le flux de travail recommandé est :
|
|
|
|
1. **`learn_tools`** — obtenir le schéma d'entrée pour des outils spécifiques
|
|
2. **`execute_tool`** — exécuter un outil
|
|
|
|
Vous n'avez pas besoin de mémoriser les noms des outils. Demandez à votre assistant IA ce qu'il peut faire et il appellera `learn_tools` automatiquement.
|
|
|
|
## Autorisations
|
|
|
|
Les connexions MCP héritent des autorisations de l'utilisateur authentifié (OAuth) ou du rôle attribué à la clé API. Pour restreindre ce que le serveur MCP peut faire :
|
|
|
|
* **OAuth** : Le rôle de l'utilisateur dans l'espace de travail s'applique.
|
|
* **Clé API** : Attribuez un rôle à la clé API dans **Paramètres > Rôles**. Voir [Autorisations](/l/fr/user-guide/permissions-access/capabilities/permissions).
|
|
|
|
## Configuration auto-hébergée
|
|
|
|
Pour les instances auto-hébergées, remplacez `{your-workspace-url}` par l'URL de votre serveur. Assurez-vous que `SERVER_URL` dans votre environnement correspond à l'URL publique de votre instance Twenty — cela est utilisé pour générer les métadonnées de découverte OAuth.
|
|
|
|
```bash
|
|
SERVER_URL=https://twenty.yourcompany.com
|
|
```
|
|
|
|
Le point de terminaison MCP, les points de terminaison OAuth et les métadonnées de découverte dérivent tous de cette valeur.
|
|
|
|
## Résolution des problèmes
|
|
|
|
**Erreurs "Unauthorized" ou 401**
|
|
|
|
* OAuth : réautorisez en supprimant les jetons stockés dans votre client MCP puis reconnectez-vous.
|
|
* Clé API : vérifiez que la clé est valide et n'a pas expiré. Régénérez-la si nécessaire.
|
|
|
|
**Le flux OAuth n'ouvre pas de navigateur**
|
|
|
|
* Assurez-vous que votre client MCP prend en charge MCP Authorization. Si ce n'est pas le cas, revenez à la méthode par clé API.
|
|
|
|
**Délai d'attente de connexion**
|
|
|
|
* Confirmez que l'URL du point de terminaison MCP est accessible depuis votre machine. Pour les instances auto-hébergées, vérifiez que le serveur est en cours d'exécution et que `SERVER_URL` est correctement défini.
|