Compare commits
5
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Félix Malfait
|
9decbf41d3 | ||
|
Félix Malfait
|
8d1da76d2c | ||
|
channi23
|
0fe2e260d3 | ||
|
channi23
|
e3e9d8d598 | ||
|
channi23
|
16e66c8df0 |
@@ -1,142 +0,0 @@
|
||||
---
|
||||
title: خادم MCP
|
||||
description: اربط مساعدي الذكاء الاصطناعي بمساحة عمل Twenty الخاصة بك باستخدام بروتوكول سياق النموذج.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
MCP حاليًا في مرحلة **ألفا** وهو متاح فقط في بعض مساحات العمل. قد لا يكون مفعّلًا لمساحة عملك بعد.
|
||||
</Warning>
|
||||
|
||||
تعرض Twenty خادم [MCP](https://modelcontextprotocol.io/) بحيث تتمكّن مساعدات الذكاء الاصطناعي — Claude Desktop وClaude Code وCursor وChatGPT وغيرها — من قراءة وكتابة بيانات نظام إدارة علاقات العملاء (CRM) لديك باستخدام اللغة الطبيعية.
|
||||
|
||||
استخدم **عنوان URL لمساحة العمل** (عنوان URL الذي تستخدمه للوصول إلى Twenty) كنقطة نهاية MCP. على Twenty Cloud، قد يكون عنوان URL لمساحة العمل هو `https://{mycompany}.twenty.com` أو نطاق مخصص. الخادم متاح على:
|
||||
|
||||
| البيئة | نقطة نهاية MCP |
|
||||
| --------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| **السحابة** | `https://{your-workspace-url}/mcp` (على سبيل المثال: `https://mycompany.twenty.com/mcp`) |
|
||||
| **الاستضافة الذاتية** | `https://{your-domain}/mcp` |
|
||||
|
||||
## طرق المصادقة
|
||||
|
||||
لديك طريقتان لمصادقة عميل MCP: **OAuth** (مُوصى بها) أو **مفتاح API**.
|
||||
|
||||
### الخيار أ — OAuth (مُوصى به)
|
||||
|
||||
باستخدام OAuth، يفتح عميل MCP لديك نافذة متصفح لتسجيل الدخول. لا يتم تخزين أي أسرار في ملفات الإعداد، ويتم تحديث الرموز المميِّزة تلقائيًا.
|
||||
|
||||
<Note>
|
||||
يتطلب OAuth عميل MCP يدعم [مواصفة تفويض MCP](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). تدعمه Claude Desktop وClaude Code وCursor وChatGPT.
|
||||
</Note>
|
||||
|
||||
أضِف ما يلي إلى تهيئة عميل MCP لديك، واستبدِل `{your-workspace-url}` بمضيف مساحة العمل لديك (على سبيل المثال: `mycompany.twenty.com`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
هذا كل شيء — لا حاجة إلى مفتاح API. عند اتصال العميل للمرة الأولى، سيفعل ما يلي:
|
||||
|
||||
1. اكتشاف بيانات التعريف الخاصة بـ OAuth لدى Twenty عبر `/.well-known/oauth-protected-resource` و`/.well-known/oauth-authorization-server`
|
||||
2. تسجيل نفسه كعميل OAuth عبر التسجيل الديناميكي للعميل (RFC 7591)
|
||||
3. فتح متصفحك لتفويض الوصول
|
||||
4. استلام الرموز المميِّزة والاتصال بخادم MCP
|
||||
|
||||
تعيد الاتصالات اللاحقة استخدام الرموز المميِّزة المخزنة وتحدِّثها تلقائيًا.
|
||||
|
||||
### الخيار ب — مفتاح API
|
||||
|
||||
إذا كان عميل MCP لديك لا يدعم OAuth، أو كنت تفضّل بيانات اعتماد ثابتة، فمرِّر مفتاح API في ترويسة `Authorization`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
يمنح مفتاح API الخاص بك حق الوصول إلى بيانات مساحة العمل. أبعِده عن أنظمة التحكم في الإصدارات وملفات dotfiles المشتركة.
|
||||
</Warning>
|
||||
|
||||
لإنشاء مفتاح API، انتقل إلى **Settings > APIs & Webhooks > + Create key**. راجع [واجهات برمجة التطبيقات](/l/ar/developers/extend/api) للتفاصيل.
|
||||
|
||||
## البدء السريع
|
||||
|
||||
### 1. انسخ الإعداد
|
||||
|
||||
انتقل إلى **Settings > AI > More > MCP Server** في Twenty. اختر طريقة المصادقة (OAuth أو مفتاح API)، وانسخ مقطع JSON (سيستخدم بالفعل عنوان URL لمساحة العمل لديك)، ثم الصقه في ملف إعدادات عميل MCP لديك.
|
||||
|
||||
| العميل | موقع ملف الإعداد |
|
||||
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) أو `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
|
||||
| **Claude Code** | `~/.claude.json` (المستخدم) أو `.mcp.json` (المشروع) |
|
||||
| **Cursor** | `.cursor/mcp.json` ضمن مشروعك، أو `~/.cursor/mcp.json` عالميًا |
|
||||
| **ChatGPT** | فعِّل وضع المطوّر في **Settings > Apps & Connectors > Advanced settings**، ثم استخدم **Create** في **Settings > Apps & Connectors** لإضافة خادم MCP |
|
||||
|
||||
### ٢. الاتصال
|
||||
|
||||
أعِد تشغيل عميل MCP لديك (أو أعد تحميل ملف الإعداد). إذا كنت تستخدم OAuth فسيتم توجيهك إلى Twenty لتفويض الوصول. إذا كنت تستخدم مفتاح API فسيكون الاتصال فوريًا.
|
||||
|
||||
### ٣. ابدأ باستخدامه
|
||||
|
||||
اطلب من مساعد الذكاء الاصطناعي التفاعل مع نظام إدارة علاقات العملاء (CRM) لديك:
|
||||
|
||||
* *"أرني أحدث 5 شركات تم إنشاؤها"*
|
||||
* *"أنشئ شخصًا جديدًا باسم Jane Doe في Acme Corp"*
|
||||
* *"اعثر على جميع الفرص المفتوحة التي تزيد قيمتها عن 10 آلاف دولار"*
|
||||
|
||||
## الأدوات المتاحة
|
||||
|
||||
بعد الاتصال، يوفّر خادم MCP أدوات تعكس واجهة برمجة تطبيقات Twenty (API). سير العمل الموصى به هو:
|
||||
|
||||
1. **`get_tool_catalog`** — اكتشف جميع الأدوات المتاحة
|
||||
2. **`learn_tools`** — احصل على مخطط الإدخال لأدوات محددة
|
||||
3. **`execute_tool`** — شغّل أداة
|
||||
|
||||
لا تحتاج إلى تذكّر أسماء الأدوات. اسأل مساعد الذكاء الاصطناعي عمّا يمكنه فعله وسيستدعي `get_tool_catalog` تلقائيًا.
|
||||
|
||||
## الصلاحيات
|
||||
|
||||
ترث اتصالات MCP أذونات المستخدم المُصادَق عليه (OAuth) أو الدور المُعيَّن لمفتاح API. لتقييد ما يمكن لخادم MCP القيام به:
|
||||
|
||||
* **OAuth**: ينطبق دور المستخدم في مساحة العمل.
|
||||
* **API Key**: عيِّن دورًا لمفتاح API ضمن **Settings > Roles**. راجع [الأذونات](/l/ar/user-guide/permissions-access/capabilities/permissions).
|
||||
|
||||
## التكوين ذاتي الاستضافة
|
||||
|
||||
في حالات الاستضافة الذاتية، استبدِل `{your-workspace-url}` بعنوان URL الخاص بالخادم لديك. تأكّد من أن قيمة `SERVER_URL` في بيئتك تطابق عنوان URL العام لمثيل Twenty لديك — إذ يُستخدَم ذلك لإنشاء بيانات تعريف اكتشاف OAuth.
|
||||
|
||||
```bash
|
||||
SERVER_URL=https://twenty.yourcompany.com
|
||||
```
|
||||
|
||||
تُشتق نقطة نهاية MCP ونقاط نهاية OAuth وبيانات تعريف الاكتشاف جميعها من هذه القيمة.
|
||||
|
||||
## استكشاف الأخطاء وإصلاحها
|
||||
|
||||
**أخطاء "Unauthorized" أو 401**
|
||||
|
||||
* OAuth: أعد التفويض عبر مسح الرموز المميِّزة المخزنة في عميل MCP لديك ثم أعد الاتصال.
|
||||
* API Key: تحقّق من أن المفتاح صالح ولم تنتهِ صلاحيته. أعِد توليده إذا لزم الأمر.
|
||||
|
||||
**عملية OAuth لا تفتح متصفحًا**
|
||||
|
||||
* تأكّد من أن عميل MCP لديك يدعم تفويض MCP. ارجع إلى طريقة مفتاح API إذا لم يكن كذلك.
|
||||
|
||||
**انتهاء مهلة الاتصال**
|
||||
|
||||
* تحقّق من إمكانية الوصول إلى عنوان URL لنقطة نهاية MCP من جهازك. بالنسبة لحالات الاستضافة الذاتية، تحقّق من أن الخادم يعمل وأن `SERVER_URL` مُعيَّن بشكل صحيح.
|
||||
@@ -1,142 +0,0 @@
|
||||
---
|
||||
title: MCP-Server
|
||||
description: Verbinden Sie KI-Assistenten mit Ihrem Twenty-Workspace über das Model Context Protocol.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
MCP befindet sich derzeit in **alpha** und ist nur in einigen Workspaces verfügbar. Möglicherweise ist es für Ihren Workspace noch nicht aktiviert.
|
||||
</Warning>
|
||||
|
||||
Twenty stellt einen [MCP](https://modelcontextprotocol.io/)-Server bereit, damit KI-Assistenten — Claude Desktop, Claude Code, Cursor, ChatGPT und andere — Ihre CRM-Daten in natürlicher Sprache lesen und schreiben können.
|
||||
|
||||
Verwenden Sie Ihre **Workspace-URL** (die URL, mit der Sie auf Twenty zugreifen) als MCP-Endpunkt. In Twenty Cloud kann Ihre Workspace-URL `https://{mycompany}.twenty.com` oder eine benutzerdefinierte Domain sein. Der Server ist verfügbar unter:
|
||||
|
||||
| Umgebung | MCP-Endpunkt |
|
||||
| ----------------- | ----------------------------------------------------------------------------- |
|
||||
| **Cloud** | `https://{your-workspace-url}/mcp` (z. B. `https://mycompany.twenty.com/mcp`) |
|
||||
| **Selbsthosting** | `https://{your-domain}/mcp` |
|
||||
|
||||
## Authentifizierungsmethoden
|
||||
|
||||
Sie haben zwei Möglichkeiten, Ihren MCP-Client zu authentifizieren: **OAuth** (empfohlen) oder **API-Schlüssel**.
|
||||
|
||||
### Option A — OAuth (empfohlen)
|
||||
|
||||
Mit OAuth öffnet Ihr MCP-Client ein Browserfenster, damit Sie sich anmelden können. Es werden keine geheimen Informationen in Konfigurationsdateien gespeichert, und Token werden automatisch erneuert.
|
||||
|
||||
<Note>
|
||||
OAuth erfordert einen MCP-Client, der die [MCP-Autorisierungsspezifikation](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) unterstützt. Claude Desktop, Claude Code, Cursor und ChatGPT unterstützen dies.
|
||||
</Note>
|
||||
|
||||
Fügen Sie dies zu Ihrer MCP-Client-Konfiguration hinzu und ersetzen Sie `{your-workspace-url}` durch den Host Ihrer Workspace-URL (z. B. `mycompany.twenty.com`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Das ist alles — kein API-Schlüssel erforderlich. Wenn der Client sich zum ersten Mal verbindet, wird er:
|
||||
|
||||
1. Die OAuth-Metadaten von Twenty über `/.well-known/oauth-protected-resource` und `/.well-known/oauth-authorization-server` ermitteln
|
||||
2. Sich über die dynamische Client-Registrierung (RFC 7591) als OAuth-Client registrieren
|
||||
3. Ihren Browser öffnen, um den Zugriff zu autorisieren
|
||||
4. Token empfangen und eine Verbindung zum MCP-Server herstellen
|
||||
|
||||
Nachfolgende Verbindungen verwenden die gespeicherten Token erneut und erneuern sie automatisch.
|
||||
|
||||
### Option B — API-Schlüssel
|
||||
|
||||
Wenn Ihr MCP-Client OAuth nicht unterstützt oder Sie statische Anmeldeinformationen bevorzugen, übergeben Sie einen API-Schlüssel im `Authorization`-Header:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Ihr API-Schlüssel gewährt Zugriff auf Workspace-Daten. Halten Sie ihn von der Versionskontrolle und gemeinsam genutzten Dotfiles fern.
|
||||
</Warning>
|
||||
|
||||
Um einen API-Schlüssel zu erstellen, gehen Sie zu **Settings > APIs & Webhooks > + Create key**. Details finden Sie unter [APIs](/l/de/developers/extend/api).
|
||||
|
||||
## Schnellstart
|
||||
|
||||
### 1. Konfiguration kopieren
|
||||
|
||||
Gehen Sie in Twenty zu **Settings > AI > More > MCP Server**. Wählen Sie Ihre Authentifizierungsmethode (OAuth oder API-Schlüssel), kopieren Sie das JSON-Snippet (es verwendet bereits Ihre Workspace-URL) und fügen Sie es in die Konfigurationsdatei Ihres MCP-Clients ein.
|
||||
|
||||
| Client | Speicherort der Konfigurationsdatei |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) oder `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
|
||||
| **Claude Code** | `~/.claude.json` (Benutzer) oder `.mcp.json` (Projekt) |
|
||||
| **Cursor** | `.cursor/mcp.json` in Ihrem Projekt oder `~/.cursor/mcp.json` global |
|
||||
| **ChatGPT** | Aktivieren Sie den Entwicklermodus in **Settings > Apps & Connectors > Advanced settings** und verwenden Sie dann **Create** in **Settings > Apps & Connectors**, um den MCP-Server hinzuzufügen |
|
||||
|
||||
### 2. Verbinden
|
||||
|
||||
Starten Sie Ihren MCP-Client neu (oder laden Sie die Konfiguration neu). Bei Verwendung von OAuth werden Sie zu Twenty weitergeleitet, um den Zugriff zu autorisieren. Bei Verwendung eines API-Schlüssels wird die Verbindung sofort hergestellt.
|
||||
|
||||
### 3. Jetzt loslegen
|
||||
|
||||
Bitten Sie Ihren KI-Assistenten, mit Ihrem CRM zu interagieren:
|
||||
|
||||
* *"Zeige mir die 5 zuletzt erstellten Unternehmen"*
|
||||
* *"Erstelle eine neue Person namens Jane Doe bei Acme Corp"*
|
||||
* *"Finde alle offenen Verkaufschancen mit einem Wert von mehr als $10k"*
|
||||
|
||||
## Verfügbare Tools
|
||||
|
||||
Nach der Verbindung stellt der MCP-Server Tools bereit, die die Twenty-API widerspiegeln. Der empfohlene Workflow ist:
|
||||
|
||||
1. **`get_tool_catalog`** — alle verfügbaren Tools entdecken
|
||||
2. **`learn_tools`** — das Eingabeschema für bestimmte Tools abrufen
|
||||
3. **`execute_tool`** — ein Tool ausführen
|
||||
|
||||
Sie müssen sich die Tool-Namen nicht merken. Fragen Sie Ihren KI-Assistenten, was er tun kann, und er ruft `get_tool_catalog` automatisch auf.
|
||||
|
||||
## Berechtigungen
|
||||
|
||||
MCP-Verbindungen erben die Berechtigungen des authentifizierten Benutzers (OAuth) oder die dem API-Schlüssel zugewiesene Rolle. So beschränken Sie, was der MCP-Server tun darf:
|
||||
|
||||
* **OAuth**: Es gilt die Workspace-Rolle des Benutzers.
|
||||
* **API-Schlüssel**: Weisen Sie dem API-Schlüssel unter **Settings > Roles** eine Rolle zu. Siehe [Berechtigungen](/l/de/user-guide/permissions-access/capabilities/permissions).
|
||||
|
||||
## Selbstgehostete Konfiguration
|
||||
|
||||
Für selbstgehostete Instanzen ersetzen Sie `{your-workspace-url}` durch die URL Ihres Servers. Stellen Sie sicher, dass `SERVER_URL` in Ihrer Umgebung der öffentlichen URL Ihrer Twenty-Instanz entspricht — diese wird verwendet, um die OAuth-Discovery-Metadaten zu generieren.
|
||||
|
||||
```bash
|
||||
SERVER_URL=https://twenty.yourcompany.com
|
||||
```
|
||||
|
||||
Der MCP-Endpunkt, die OAuth-Endpunkte und die Discovery-Metadaten leiten sich alle von diesem Wert ab.
|
||||
|
||||
## Fehlerbehebung
|
||||
|
||||
**"Unauthorized"- oder 401-Fehler**
|
||||
|
||||
* OAuth: Autorisieren Sie erneut, indem Sie die gespeicherten Token in Ihrem MCP-Client löschen und die Verbindung wiederherstellen.
|
||||
* API-Schlüssel: Überprüfen Sie, dass der Schlüssel gültig ist und nicht abgelaufen ist. Generieren Sie ihn bei Bedarf neu.
|
||||
|
||||
**Der OAuth-Flow öffnet keinen Browser**
|
||||
|
||||
* Stellen Sie sicher, dass Ihr MCP-Client MCP Authorization unterstützt. Wechseln Sie andernfalls zur API-Schlüssel-Methode.
|
||||
|
||||
**Verbindungszeitüberschreitung**
|
||||
|
||||
* Stellen Sie sicher, dass die MCP-Endpunkt-URL von Ihrem Rechner aus erreichbar ist. Bei selbstgehosteten Instanzen prüfen Sie, ob der Server läuft und `SERVER_URL` korrekt gesetzt ist.
|
||||
@@ -1,142 +0,0 @@
|
||||
---
|
||||
title: Server MCP
|
||||
description: Collega gli assistenti AI al tuo spazio di lavoro di Twenty utilizzando il Model Context Protocol.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
MCP è attualmente in **alpha** ed è disponibile solo su alcuni spazi di lavoro. Potrebbe non essere ancora abilitato per il tuo spazio di lavoro.
|
||||
</Warning>
|
||||
|
||||
Twenty exposes an [MCP](https://modelcontextprotocol.io/) server so that AI assistants — Claude Desktop, Claude Code, Cursor, ChatGPT, and others — can read and write your CRM data through natural language.
|
||||
|
||||
Use your **workspace URL** (the URL you use to access Twenty) as the MCP endpoint. On Twenty Cloud, your workspace URL might be `https://{mycompany}.twenty.com` or a custom domain. The server is available at:
|
||||
|
||||
| Ambiente | MCP Endpoint |
|
||||
| ----------------- | ---------------------------------------------------------------------------- |
|
||||
| **Cloud** | `https://{your-workspace-url}/mcp` (e.g. `https://mycompany.twenty.com/mcp`) |
|
||||
| **Auto-ospitato** | `https://{your-domain}/mcp` |
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
You have two ways to authenticate your MCP client: **OAuth** (recommended) or **API Key**.
|
||||
|
||||
### Option A — OAuth (Recommended)
|
||||
|
||||
With OAuth, your MCP client opens a browser window for you to log in. No secrets are stored in config files, and tokens refresh automatically.
|
||||
|
||||
<Note>
|
||||
OAuth requires an MCP client that supports the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor, and ChatGPT support it.
|
||||
</Note>
|
||||
|
||||
Add this to your MCP client configuration, replacing `{your-workspace-url}` with your workspace host (e.g. `mycompany.twenty.com`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
That's it — no API key needed. When the client connects for the first time it will:
|
||||
|
||||
1. Discover Twenty's OAuth metadata via `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`
|
||||
2. Register itself as an OAuth client via dynamic client registration (RFC 7591)
|
||||
3. Open your browser to authorize access
|
||||
4. Receive tokens and connect to the MCP server
|
||||
|
||||
Subsequent connections reuse the stored tokens and refresh them automatically.
|
||||
|
||||
### Option B — API Key
|
||||
|
||||
If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the `Authorization` header:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
|
||||
</Warning>
|
||||
|
||||
To create an API key, go to **Settings > APIs & Webhooks > + Create key**. See [APIs](/l/it/developers/extend/api) for details.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Copy the config
|
||||
|
||||
Go to **Settings > AI > More > MCP Server** in Twenty. Choose your authentication method (OAuth or API Key), copy the JSON snippet (it will already use your workspace URL), and paste it into your MCP client's config file.
|
||||
|
||||
| Client | Config file location |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
|
||||
| **Claude Code** | `~/.claude.json` (user) or `.mcp.json` (project) |
|
||||
| **Cursor** | `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally |
|
||||
| **ChatGPT** | Turn on Developer Mode in **Settings > Apps & Connectors > Advanced settings**, then use **Create** in **Settings > Apps & Connectors** to add the MCP server |
|
||||
|
||||
### 2. Connect
|
||||
|
||||
Restart your MCP client (or reload the config). If using OAuth you will be redirected to Twenty to authorize access. If using an API key the connection is immediate.
|
||||
|
||||
### 3. Start using it
|
||||
|
||||
Ask your AI assistant to interact with your CRM:
|
||||
|
||||
* *"Show me the 5 most recently created companies"*
|
||||
* *"Create a new person named Jane Doe at Acme Corp"*
|
||||
* *"Find all open opportunities worth more than $10k"*
|
||||
|
||||
## Available Tools
|
||||
|
||||
Once connected, the MCP server exposes tools that mirror the Twenty API. The recommended workflow is:
|
||||
|
||||
1. **`get_tool_catalog`** — discover all available tools
|
||||
2. **`learn_tools`** — get the input schema for specific tools
|
||||
3. **`execute_tool`** — run a tool
|
||||
|
||||
You don't need to remember tool names. Ask your AI assistant what it can do and it will call `get_tool_catalog` automatically.
|
||||
|
||||
## Permessi
|
||||
|
||||
MCP connections inherit the permissions of the authenticated user (OAuth) or the role assigned to the API key. To restrict what the MCP server can do:
|
||||
|
||||
* **OAuth**: The user's workspace role applies.
|
||||
* **API Key**: Assign a role to the API key under **Settings > Roles**. See [Permissions](/l/it/user-guide/permissions-access/capabilities/permissions).
|
||||
|
||||
## Self-Hosted Configuration
|
||||
|
||||
For self-hosted instances, replace `{your-workspace-url}` with your server URL. Make sure `SERVER_URL` in your environment matches the public URL of your Twenty instance — this is used to generate the OAuth discovery metadata.
|
||||
|
||||
```bash
|
||||
SERVER_URL=https://twenty.yourcompany.com
|
||||
```
|
||||
|
||||
The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.
|
||||
|
||||
## Risoluzione dei problemi
|
||||
|
||||
**"Unauthorized" or 401 errors**
|
||||
|
||||
* OAuth: re-authorize by clearing the stored tokens in your MCP client and reconnecting.
|
||||
* API Key: verify the key is valid and hasn't expired. Regenerate it if needed.
|
||||
|
||||
**OAuth flow doesn't open a browser**
|
||||
|
||||
* Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn't.
|
||||
|
||||
**Connection timeout**
|
||||
|
||||
* Confirm the MCP endpoint URL is reachable from your machine. For self-hosted instances, check that the server is running and `SERVER_URL` is set correctly.
|
||||
@@ -1,142 +0,0 @@
|
||||
---
|
||||
title: Servidor MCP
|
||||
description: Conecte assistentes de IA ao seu espaço de trabalho do Twenty usando o Model Context Protocol.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
O MCP está atualmente em **alfa** e está disponível apenas em alguns espaços de trabalho. O MCP pode ainda não estar ativado no seu espaço de trabalho.
|
||||
</Warning>
|
||||
|
||||
Twenty exposes an [MCP](https://modelcontextprotocol.io/) server so that AI assistants — Claude Desktop, Claude Code, Cursor, ChatGPT, and others — can read and write your CRM data through natural language.
|
||||
|
||||
Use your **workspace URL** (the URL you use to access Twenty) as the MCP endpoint. On Twenty Cloud, your workspace URL might be `https://{mycompany}.twenty.com` or a custom domain. The server is available at:
|
||||
|
||||
| Ambiente | MCP Endpoint |
|
||||
| ------------------ | ---------------------------------------------------------------------------- |
|
||||
| **Nuvem** | `https://{your-workspace-url}/mcp` (e.g. `https://mycompany.twenty.com/mcp`) |
|
||||
| **Auto-hospedado** | `https://{your-domain}/mcp` |
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
You have two ways to authenticate your MCP client: **OAuth** (recommended) or **API Key**.
|
||||
|
||||
### Option A — OAuth (Recommended)
|
||||
|
||||
With OAuth, your MCP client opens a browser window for you to log in. No secrets are stored in config files, and tokens refresh automatically.
|
||||
|
||||
<Note>
|
||||
OAuth requires an MCP client that supports the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor, and ChatGPT support it.
|
||||
</Note>
|
||||
|
||||
Add this to your MCP client configuration, replacing `{your-workspace-url}` with your workspace host (e.g. `mycompany.twenty.com`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
That's it — no API key needed. When the client connects for the first time it will:
|
||||
|
||||
1. Discover Twenty's OAuth metadata via `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`
|
||||
2. Register itself as an OAuth client via dynamic client registration (RFC 7591)
|
||||
3. Open your browser to authorize access
|
||||
4. Receive tokens and connect to the MCP server
|
||||
|
||||
Subsequent connections reuse the stored tokens and refresh them automatically.
|
||||
|
||||
### Option B — API Key
|
||||
|
||||
If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the `Authorization` header:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
|
||||
</Warning>
|
||||
|
||||
To create an API key, go to **Settings > APIs & Webhooks > + Create key**. See [APIs](/l/pt/developers/extend/api) for details.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Copy the config
|
||||
|
||||
Go to **Settings > AI > More > MCP Server** in Twenty. Choose your authentication method (OAuth or API Key), copy the JSON snippet (it will already use your workspace URL), and paste it into your MCP client's config file.
|
||||
|
||||
| Client | Config file location |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
|
||||
| **Claude Code** | `~/.claude.json` (user) or `.mcp.json` (project) |
|
||||
| **Cursor** | `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally |
|
||||
| **ChatGPT** | Turn on Developer Mode in **Settings > Apps & Connectors > Advanced settings**, then use **Create** in **Settings > Apps & Connectors** to add the MCP server |
|
||||
|
||||
### 2. Connect
|
||||
|
||||
Restart your MCP client (or reload the config). If using OAuth you will be redirected to Twenty to authorize access. If using an API key the connection is immediate.
|
||||
|
||||
### 3. Start using it
|
||||
|
||||
Ask your AI assistant to interact with your CRM:
|
||||
|
||||
* *"Show me the 5 most recently created companies"*
|
||||
* *"Create a new person named Jane Doe at Acme Corp"*
|
||||
* *"Find all open opportunities worth more than $10k"*
|
||||
|
||||
## Available Tools
|
||||
|
||||
Once connected, the MCP server exposes tools that mirror the Twenty API. The recommended workflow is:
|
||||
|
||||
1. **`get_tool_catalog`** — discover all available tools
|
||||
2. **`learn_tools`** — get the input schema for specific tools
|
||||
3. **`execute_tool`** — run a tool
|
||||
|
||||
You don't need to remember tool names. Ask your AI assistant what it can do and it will call `get_tool_catalog` automatically.
|
||||
|
||||
## Permissões
|
||||
|
||||
MCP connections inherit the permissions of the authenticated user (OAuth) or the role assigned to the API key. To restrict what the MCP server can do:
|
||||
|
||||
* **OAuth**: The user's workspace role applies.
|
||||
* **API Key**: Assign a role to the API key under **Settings > Roles**. See [Permissions](/l/pt/user-guide/permissions-access/capabilities/permissions).
|
||||
|
||||
## Self-Hosted Configuration
|
||||
|
||||
For self-hosted instances, replace `{your-workspace-url}` with your server URL. Make sure `SERVER_URL` in your environment matches the public URL of your Twenty instance — this is used to generate the OAuth discovery metadata.
|
||||
|
||||
```bash
|
||||
SERVER_URL=https://twenty.yourcompany.com
|
||||
```
|
||||
|
||||
The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.
|
||||
|
||||
## Resolução de Problemas
|
||||
|
||||
**"Unauthorized" or 401 errors**
|
||||
|
||||
* OAuth: re-authorize by clearing the stored tokens in your MCP client and reconnecting.
|
||||
* API Key: verify the key is valid and hasn't expired. Regenerate it if needed.
|
||||
|
||||
**OAuth flow doesn't open a browser**
|
||||
|
||||
* Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn't.
|
||||
|
||||
**Connection timeout**
|
||||
|
||||
* Confirm the MCP endpoint URL is reachable from your machine. For self-hosted instances, check that the server is running and `SERVER_URL` is set correctly.
|
||||
@@ -1,142 +0,0 @@
|
||||
---
|
||||
title: Server MCP
|
||||
description: Conectați asistenți AI la spațiul dvs. de lucru Twenty folosind Model Context Protocol.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
MCP este în prezent în **alpha** și este disponibil doar în unele spații de lucru. Este posibil să nu fie activat încă pentru spațiul dvs. de lucru.
|
||||
</Warning>
|
||||
|
||||
Twenty expune un server [MCP](https://modelcontextprotocol.io/) astfel încât asistenții AI — Claude Desktop, Claude Code, Cursor, ChatGPT și alții — să poată citi și scrie datele tale din CRM prin limbaj natural.
|
||||
|
||||
Folosește **URL-ul spațiului de lucru** (URL-ul pe care îl folosești pentru a accesa Twenty) drept punct final MCP. Pe Twenty Cloud, URL-ul spațiului tău de lucru poate fi `https://{mycompany}.twenty.com` sau un domeniu personalizat. Serverul este disponibil la:
|
||||
|
||||
| Mediu | Punct final MCP |
|
||||
| -------------------- | ------------------------------------------------------------------------------ |
|
||||
| **Cloud** | `https://{your-workspace-url}/mcp` (de ex. `https://mycompany.twenty.com/mcp`) |
|
||||
| **Găzduire proprie** | `https://{your-domain}/mcp` |
|
||||
|
||||
## Metode de autentificare
|
||||
|
||||
Ai două moduri de a-ți autentifica clientul MCP: **OAuth** (recomandat) sau **Cheie API**.
|
||||
|
||||
### Opțiunea A — OAuth (Recomandat)
|
||||
|
||||
Cu OAuth, clientul tău MCP deschide o fereastră de browser pentru a te autentifica. Nicio informație secretă nu este stocată în fișierele de configurare, iar tokenurile se reîmprospătează automat.
|
||||
|
||||
<Note>
|
||||
OAuth necesită un client MCP care suportă [specificația MCP Authorization](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor și ChatGPT o suportă.
|
||||
</Note>
|
||||
|
||||
Adaugă asta în configurația clientului tău MCP, înlocuind `{your-workspace-url}` cu gazda spațiului tău de lucru (de ex. `mycompany.twenty.com`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Atât — nu este necesară nicio cheie API. Când clientul se conectează pentru prima dată, acesta va:
|
||||
|
||||
1. Va descoperi metadatele OAuth ale Twenty prin `/.well-known/oauth-protected-resource` și `/.well-known/oauth-authorization-server`
|
||||
2. Se va înregistra ca un client OAuth prin înregistrare dinamică a clientului (RFC 7591)
|
||||
3. Îți va deschide browserul pentru a autoriza accesul
|
||||
4. Va primi tokenurile și se va conecta la serverul MCP
|
||||
|
||||
Conexiunile ulterioare reutilizează tokenurile stocate și le reîmprospătează automat.
|
||||
|
||||
### Opțiunea B — Cheie API
|
||||
|
||||
Dacă clientul tău MCP nu suportă OAuth sau preferi acreditări statice, furnizează o cheie API în antetul `Authorization`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Cheia ta API oferă acces la datele spațiului de lucru. Ține-o în afara controlului versiunilor și a dotfiles partajate.
|
||||
</Warning>
|
||||
|
||||
Pentru a crea o cheie API, mergi la **Settings > APIs & Webhooks > + Create key**. Vezi [API-uri](/l/ro/developers/extend/api) pentru detalii.
|
||||
|
||||
## Pornire rapidă
|
||||
|
||||
### 1. Copiază configurația
|
||||
|
||||
Mergi la **Settings > AI > More > MCP Server** în Twenty. Alege metoda de autentificare (OAuth sau Cheie API), copiază fragmentul JSON (va folosi deja URL-ul spațiului tău de lucru) și lipește-l în fișierul de configurare al clientului tău MCP.
|
||||
|
||||
| Client | Locația fișierului de configurare |
|
||||
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) sau `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
|
||||
| **Claude Code** | `~/.claude.json` (utilizator) sau `.mcp.json` (proiect) |
|
||||
| **Cursor** | `.cursor/mcp.json` în proiectul tău sau `~/.cursor/mcp.json` global |
|
||||
| **ChatGPT** | Activează Modul pentru dezvoltatori în **Settings > Apps & Connectors > Advanced settings**, apoi folosește **Create** în **Settings > Apps & Connectors** pentru a adăuga serverul MCP |
|
||||
|
||||
### 2. Conectează-te
|
||||
|
||||
Repornește clientul tău MCP (sau reîncarcă configurația). Dacă folosești OAuth, vei fi redirecționat către Twenty pentru a autoriza accesul. Dacă folosești o cheie API, conexiunea este imediată.
|
||||
|
||||
### 3. Începe să-l folosești
|
||||
|
||||
Roagă-ți asistentul AI să interacționeze cu CRM-ul tău:
|
||||
|
||||
* *"Arată-mi cele 5 companii create cel mai recent"*
|
||||
* *"Creează o persoană nouă numită Jane Doe la Acme Corp"*
|
||||
* *"Găsește toate oportunitățile deschise cu o valoare mai mare de $10k"*
|
||||
|
||||
## Instrumente disponibile
|
||||
|
||||
După conectare, serverul MCP expune instrumente care oglindesc API-ul Twenty. Fluxul de lucru recomandat este:
|
||||
|
||||
1. **`get_tool_catalog`** — descoperă toate instrumentele disponibile
|
||||
2. **`learn_tools`** — obține schema de intrare pentru instrumente specifice
|
||||
3. **`execute_tool`** — rulează un instrument
|
||||
|
||||
Nu este nevoie să reții numele instrumentelor. Întreabă-ți asistentul AI ce poate face și va apela `get_tool_catalog` automat.
|
||||
|
||||
## Permisiuni
|
||||
|
||||
Conexiunile MCP moștenesc permisiunile utilizatorului autentificat (OAuth) sau rolul atribuit cheii API. Pentru a restricționa ce poate face serverul MCP:
|
||||
|
||||
* **OAuth**: Se aplică rolul utilizatorului din spațiul de lucru.
|
||||
* **Cheie API**: Atribuie un rol cheii API în **Settings > Roles**. Vezi [Permisiuni](/l/ro/user-guide/permissions-access/capabilities/permissions).
|
||||
|
||||
## Configurație pentru auto-găzduire
|
||||
|
||||
Pentru instanțele auto-găzduite, înlocuiește `{your-workspace-url}` cu URL-ul serverului tău. Asigură-te că `SERVER_URL` din mediul tău corespunde URL-ului public al instanței tale Twenty — acesta este folosit pentru a genera metadatele de descoperire OAuth.
|
||||
|
||||
```bash
|
||||
SERVER_URL=https://twenty.yourcompany.com
|
||||
```
|
||||
|
||||
Punctul final MCP, punctele finale OAuth și metadatele de descoperire derivă toate din această valoare.
|
||||
|
||||
## Depanare
|
||||
|
||||
**Erori "Unauthorized" sau 401**
|
||||
|
||||
* OAuth: reautorizează ștergând tokenurile stocate din clientul tău MCP și reconectează-te.
|
||||
* Cheie API: verifică dacă cheia este validă și nu a expirat. Regenereaz-o dacă este necesar.
|
||||
|
||||
**Fluxul OAuth nu deschide un browser**
|
||||
|
||||
* Asigură-te că clientul tău MCP suportă MCP Authorization. Dacă nu, revino la metoda cu Cheie API.
|
||||
|
||||
**Timeout de conexiune**
|
||||
|
||||
* Confirmă că URL-ul punctului final MCP este accesibil de pe calculatorul tău. Pentru instanțele auto-găzduite, verifică faptul că serverul rulează și că `SERVER_URL` este setat corect.
|
||||
@@ -1,142 +0,0 @@
|
||||
---
|
||||
title: Сервер MCP
|
||||
description: Подключайте ИИ-ассистентов к вашему рабочему пространству Twenty с помощью протокола Model Context Protocol.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
В настоящее время MCP находится на стадии **alpha** и доступен только в некоторых рабочих пространствах. В вашем рабочем пространстве он может быть ещё не включён.
|
||||
</Warning>
|
||||
|
||||
Twenty exposes an [MCP](https://modelcontextprotocol.io/) server so that AI assistants — Claude Desktop, Claude Code, Cursor, ChatGPT, and others — can read and write your CRM data through natural language.
|
||||
|
||||
Use your **workspace URL** (the URL you use to access Twenty) as the MCP endpoint. On Twenty Cloud, your workspace URL might be `https://{mycompany}.twenty.com` or a custom domain. The server is available at:
|
||||
|
||||
| Среда | MCP Endpoint |
|
||||
| --------------------------- | ---------------------------------------------------------------------------- |
|
||||
| **Облако** | `https://{your-workspace-url}/mcp` (e.g. `https://mycompany.twenty.com/mcp`) |
|
||||
| **Самостоятельный хостинг** | `https://{your-domain}/mcp` |
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
You have two ways to authenticate your MCP client: **OAuth** (recommended) or **API Key**.
|
||||
|
||||
### Option A — OAuth (Recommended)
|
||||
|
||||
With OAuth, your MCP client opens a browser window for you to log in. No secrets are stored in config files, and tokens refresh automatically.
|
||||
|
||||
<Note>
|
||||
OAuth requires an MCP client that supports the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor, and ChatGPT support it.
|
||||
</Note>
|
||||
|
||||
Add this to your MCP client configuration, replacing `{your-workspace-url}` with your workspace host (e.g. `mycompany.twenty.com`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
That's it — no API key needed. When the client connects for the first time it will:
|
||||
|
||||
1. Discover Twenty's OAuth metadata via `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`
|
||||
2. Register itself as an OAuth client via dynamic client registration (RFC 7591)
|
||||
3. Open your browser to authorize access
|
||||
4. Receive tokens and connect to the MCP server
|
||||
|
||||
Subsequent connections reuse the stored tokens and refresh them automatically.
|
||||
|
||||
### Option B — API Key
|
||||
|
||||
If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the `Authorization` header:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
|
||||
</Warning>
|
||||
|
||||
To create an API key, go to **Settings > APIs & Webhooks > + Create key**. See [APIs](/l/ru/developers/extend/api) for details.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Copy the config
|
||||
|
||||
Go to **Settings > AI > More > MCP Server** in Twenty. Choose your authentication method (OAuth or API Key), copy the JSON snippet (it will already use your workspace URL), and paste it into your MCP client's config file.
|
||||
|
||||
| Client | Config file location |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
|
||||
| **Claude Code** | `~/.claude.json` (user) or `.mcp.json` (project) |
|
||||
| **Cursor** | `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally |
|
||||
| **ChatGPT** | Turn on Developer Mode in **Settings > Apps & Connectors > Advanced settings**, then use **Create** in **Settings > Apps & Connectors** to add the MCP server |
|
||||
|
||||
### 2. Connect
|
||||
|
||||
Restart your MCP client (or reload the config). If using OAuth you will be redirected to Twenty to authorize access. If using an API key the connection is immediate.
|
||||
|
||||
### 3. Start using it
|
||||
|
||||
Ask your AI assistant to interact with your CRM:
|
||||
|
||||
* *"Show me the 5 most recently created companies"*
|
||||
* *"Create a new person named Jane Doe at Acme Corp"*
|
||||
* *"Find all open opportunities worth more than $10k"*
|
||||
|
||||
## Available Tools
|
||||
|
||||
Once connected, the MCP server exposes tools that mirror the Twenty API. The recommended workflow is:
|
||||
|
||||
1. **`get_tool_catalog`** — discover all available tools
|
||||
2. **`learn_tools`** — get the input schema for specific tools
|
||||
3. **`execute_tool`** — run a tool
|
||||
|
||||
You don't need to remember tool names. Ask your AI assistant what it can do and it will call `get_tool_catalog` automatically.
|
||||
|
||||
## Разрешения
|
||||
|
||||
MCP connections inherit the permissions of the authenticated user (OAuth) or the role assigned to the API key. To restrict what the MCP server can do:
|
||||
|
||||
* **OAuth**: The user's workspace role applies.
|
||||
* **API Key**: Assign a role to the API key under **Settings > Roles**. See [Permissions](/l/ru/user-guide/permissions-access/capabilities/permissions).
|
||||
|
||||
## Self-Hosted Configuration
|
||||
|
||||
For self-hosted instances, replace `{your-workspace-url}` with your server URL. Make sure `SERVER_URL` in your environment matches the public URL of your Twenty instance — this is used to generate the OAuth discovery metadata.
|
||||
|
||||
```bash
|
||||
SERVER_URL=https://twenty.yourcompany.com
|
||||
```
|
||||
|
||||
The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.
|
||||
|
||||
## Устранение неполадок
|
||||
|
||||
**"Unauthorized" or 401 errors**
|
||||
|
||||
* OAuth: re-authorize by clearing the stored tokens in your MCP client and reconnecting.
|
||||
* API Key: verify the key is valid and hasn't expired. Regenerate it if needed.
|
||||
|
||||
**OAuth flow doesn't open a browser**
|
||||
|
||||
* Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn't.
|
||||
|
||||
**Connection timeout**
|
||||
|
||||
* Confirm the MCP endpoint URL is reachable from your machine. For self-hosted instances, check that the server is running and `SERVER_URL` is set correctly.
|
||||
@@ -1,142 +0,0 @@
|
||||
---
|
||||
title: MCP Sunucusu
|
||||
description: Model Context Protocol kullanarak yapay zeka asistanlarını Twenty çalışma alanınıza bağlayın.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
MCP şu anda **alfa** aşamasındadır ve yalnızca bazı çalışma alanlarında kullanılabilir. Çalışma alanınızda henüz etkinleştirilmemiş olabilir.
|
||||
</Warning>
|
||||
|
||||
Twenty exposes an [MCP](https://modelcontextprotocol.io/) server so that AI assistants — Claude Desktop, Claude Code, Cursor, ChatGPT, and others — can read and write your CRM data through natural language.
|
||||
|
||||
Use your **workspace URL** (the URL you use to access Twenty) as the MCP endpoint. On Twenty Cloud, your workspace URL might be `https://{mycompany}.twenty.com` or a custom domain. The server is available at:
|
||||
|
||||
| Ortam | MCP Endpoint |
|
||||
| ---------------------------- | ---------------------------------------------------------------------------- |
|
||||
| **Bulut** | `https://{your-workspace-url}/mcp` (e.g. `https://mycompany.twenty.com/mcp`) |
|
||||
| **Kendi Kendine Barındırma** | `https://{your-domain}/mcp` |
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
You have two ways to authenticate your MCP client: **OAuth** (recommended) or **API Key**.
|
||||
|
||||
### Option A — OAuth (Recommended)
|
||||
|
||||
With OAuth, your MCP client opens a browser window for you to log in. No secrets are stored in config files, and tokens refresh automatically.
|
||||
|
||||
<Note>
|
||||
OAuth requires an MCP client that supports the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor, and ChatGPT support it.
|
||||
</Note>
|
||||
|
||||
Add this to your MCP client configuration, replacing `{your-workspace-url}` with your workspace host (e.g. `mycompany.twenty.com`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
That's it — no API key needed. When the client connects for the first time it will:
|
||||
|
||||
1. Discover Twenty's OAuth metadata via `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`
|
||||
2. Register itself as an OAuth client via dynamic client registration (RFC 7591)
|
||||
3. Open your browser to authorize access
|
||||
4. Receive tokens and connect to the MCP server
|
||||
|
||||
Subsequent connections reuse the stored tokens and refresh them automatically.
|
||||
|
||||
### Option B — API Key
|
||||
|
||||
If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the `Authorization` header:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
|
||||
</Warning>
|
||||
|
||||
To create an API key, go to **Settings > APIs & Webhooks > + Create key**. See [APIs](/l/tr/developers/extend/api) for details.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Copy the config
|
||||
|
||||
Go to **Settings > AI > More > MCP Server** in Twenty. Choose your authentication method (OAuth or API Key), copy the JSON snippet (it will already use your workspace URL), and paste it into your MCP client's config file.
|
||||
|
||||
| Client | Config file location |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
|
||||
| **Claude Code** | `~/.claude.json` (user) or `.mcp.json` (project) |
|
||||
| **Cursor** | `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally |
|
||||
| **ChatGPT** | Turn on Developer Mode in **Settings > Apps & Connectors > Advanced settings**, then use **Create** in **Settings > Apps & Connectors** to add the MCP server |
|
||||
|
||||
### 2. Connect
|
||||
|
||||
Restart your MCP client (or reload the config). If using OAuth you will be redirected to Twenty to authorize access. If using an API key the connection is immediate.
|
||||
|
||||
### 3. Start using it
|
||||
|
||||
Ask your AI assistant to interact with your CRM:
|
||||
|
||||
* *"Show me the 5 most recently created companies"*
|
||||
* *"Create a new person named Jane Doe at Acme Corp"*
|
||||
* *"Find all open opportunities worth more than $10k"*
|
||||
|
||||
## Available Tools
|
||||
|
||||
Once connected, the MCP server exposes tools that mirror the Twenty API. The recommended workflow is:
|
||||
|
||||
1. **`get_tool_catalog`** — discover all available tools
|
||||
2. **`learn_tools`** — get the input schema for specific tools
|
||||
3. **`execute_tool`** — run a tool
|
||||
|
||||
You don't need to remember tool names. Ask your AI assistant what it can do and it will call `get_tool_catalog` automatically.
|
||||
|
||||
## İzinler
|
||||
|
||||
MCP connections inherit the permissions of the authenticated user (OAuth) or the role assigned to the API key. To restrict what the MCP server can do:
|
||||
|
||||
* **OAuth**: The user's workspace role applies.
|
||||
* **API Key**: Assign a role to the API key under **Settings > Roles**. See [Permissions](/l/tr/user-guide/permissions-access/capabilities/permissions).
|
||||
|
||||
## Self-Hosted Configuration
|
||||
|
||||
For self-hosted instances, replace `{your-workspace-url}` with your server URL. Make sure `SERVER_URL` in your environment matches the public URL of your Twenty instance — this is used to generate the OAuth discovery metadata.
|
||||
|
||||
```bash
|
||||
SERVER_URL=https://twenty.yourcompany.com
|
||||
```
|
||||
|
||||
The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.
|
||||
|
||||
## Sorun Giderme
|
||||
|
||||
**"Unauthorized" or 401 errors**
|
||||
|
||||
* OAuth: re-authorize by clearing the stored tokens in your MCP client and reconnecting.
|
||||
* API Key: verify the key is valid and hasn't expired. Regenerate it if needed.
|
||||
|
||||
**OAuth flow doesn't open a browser**
|
||||
|
||||
* Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn't.
|
||||
|
||||
**Connection timeout**
|
||||
|
||||
* Confirm the MCP endpoint URL is reachable from your machine. For self-hosted instances, check that the server is running and `SERVER_URL` is set correctly.
|
||||
@@ -1,142 +0,0 @@
|
||||
---
|
||||
title: MCP服务器
|
||||
description: 使用 Model Context Protocol 将 AI 助手连接到你的 Twenty 工作区。
|
||||
---
|
||||
|
||||
<Warning>
|
||||
MCP 目前处于**alpha**阶段，并且仅在部分工作区可用。 它可能尚未在你的工作区启用。
|
||||
</Warning>
|
||||
|
||||
Twenty exposes an [MCP](https://modelcontextprotocol.io/) server so that AI assistants — Claude Desktop, Claude Code, Cursor, ChatGPT, and others — can read and write your CRM data through natural language.
|
||||
|
||||
Use your **workspace URL** (the URL you use to access Twenty) as the MCP endpoint. On Twenty Cloud, your workspace URL might be `https://{mycompany}.twenty.com` or a custom domain. The server is available at:
|
||||
|
||||
| 环境 | MCP Endpoint |
|
||||
| ------- | ---------------------------------------------------------------------------- |
|
||||
| **云端** | `https://{your-workspace-url}/mcp` (e.g. `https://mycompany.twenty.com/mcp`) |
|
||||
| **自托管** | `https://{your-domain}/mcp` |
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
You have two ways to authenticate your MCP client: **OAuth** (recommended) or **API Key**.
|
||||
|
||||
### Option A — OAuth (Recommended)
|
||||
|
||||
With OAuth, your MCP client opens a browser window for you to log in. No secrets are stored in config files, and tokens refresh automatically.
|
||||
|
||||
<Note>
|
||||
OAuth requires an MCP client that supports the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor, and ChatGPT support it.
|
||||
</Note>
|
||||
|
||||
Add this to your MCP client configuration, replacing `{your-workspace-url}` with your workspace host (e.g. `mycompany.twenty.com`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
That's it — no API key needed. When the client connects for the first time it will:
|
||||
|
||||
1. Discover Twenty's OAuth metadata via `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`
|
||||
2. Register itself as an OAuth client via dynamic client registration (RFC 7591)
|
||||
3. Open your browser to authorize access
|
||||
4. Receive tokens and connect to the MCP server
|
||||
|
||||
Subsequent connections reuse the stored tokens and refresh them automatically.
|
||||
|
||||
### Option B — API Key
|
||||
|
||||
If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the `Authorization` header:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"twenty": {
|
||||
"type": "streamable-http",
|
||||
"url": "https://{your-workspace-url}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer YOUR_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
|
||||
</Warning>
|
||||
|
||||
To create an API key, go to **Settings > APIs & Webhooks > + Create key**. See [APIs](/l/zh/developers/extend/api) for details.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Copy the config
|
||||
|
||||
Go to **Settings > AI > More > MCP Server** in Twenty. Choose your authentication method (OAuth or API Key), copy the JSON snippet (it will already use your workspace URL), and paste it into your MCP client's config file.
|
||||
|
||||
| Client | Config file location |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
|
||||
| **Claude Code** | `~/.claude.json` (user) or `.mcp.json` (project) |
|
||||
| **Cursor** | `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally |
|
||||
| **ChatGPT** | Turn on Developer Mode in **Settings > Apps & Connectors > Advanced settings**, then use **Create** in **Settings > Apps & Connectors** to add the MCP server |
|
||||
|
||||
### 2. Connect
|
||||
|
||||
Restart your MCP client (or reload the config). If using OAuth you will be redirected to Twenty to authorize access. If using an API key the connection is immediate.
|
||||
|
||||
### 3. Start using it
|
||||
|
||||
Ask your AI assistant to interact with your CRM:
|
||||
|
||||
* *"Show me the 5 most recently created companies"*
|
||||
* *"Create a new person named Jane Doe at Acme Corp"*
|
||||
* *"Find all open opportunities worth more than $10k"*
|
||||
|
||||
## Available Tools
|
||||
|
||||
Once connected, the MCP server exposes tools that mirror the Twenty API. The recommended workflow is:
|
||||
|
||||
1. **`get_tool_catalog`** — discover all available tools
|
||||
2. **`learn_tools`** — get the input schema for specific tools
|
||||
3. **`execute_tool`** — run a tool
|
||||
|
||||
You don't need to remember tool names. Ask your AI assistant what it can do and it will call `get_tool_catalog` automatically.
|
||||
|
||||
## 权限
|
||||
|
||||
MCP connections inherit the permissions of the authenticated user (OAuth) or the role assigned to the API key. To restrict what the MCP server can do:
|
||||
|
||||
* **OAuth**: The user's workspace role applies.
|
||||
* **API Key**: Assign a role to the API key under **Settings > Roles**. See [Permissions](/l/zh/user-guide/permissions-access/capabilities/permissions).
|
||||
|
||||
## Self-Hosted Configuration
|
||||
|
||||
For self-hosted instances, replace `{your-workspace-url}` with your server URL. Make sure `SERVER_URL` in your environment matches the public URL of your Twenty instance — this is used to generate the OAuth discovery metadata.
|
||||
|
||||
```bash
|
||||
SERVER_URL=https://twenty.yourcompany.com
|
||||
```
|
||||
|
||||
The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.
|
||||
|
||||
## 故障排除
|
||||
|
||||
**"Unauthorized" or 401 errors**
|
||||
|
||||
* OAuth: re-authorize by clearing the stored tokens in your MCP client and reconnecting.
|
||||
* API Key: verify the key is valid and hasn't expired. Regenerate it if needed.
|
||||
|
||||
**OAuth flow doesn't open a browser**
|
||||
|
||||
* Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn't.
|
||||
|
||||
**Connection timeout**
|
||||
|
||||
* Confirm the MCP endpoint URL is reachable from your machine. For self-hosted instances, check that the server is running and `SERVER_URL` is set correctly.
|
||||
+4
-19
@@ -7,8 +7,6 @@ import {
|
||||
|
||||
import { capitalize } from 'twenty-shared/utils';
|
||||
|
||||
import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.module';
|
||||
import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
|
||||
import { metadataToRepositoryMapping } from 'src/engine/object-metadata-repository/metadata-to-repository.mapping';
|
||||
import { GlobalWorkspaceOrmManager } from 'src/engine/twenty-orm/global-workspace-datasource/global-workspace-orm.manager';
|
||||
import { TwentyORMModule } from 'src/engine/twenty-orm/twenty-orm.module';
|
||||
@@ -33,29 +31,16 @@ export class ObjectMetadataRepositoryModule {
|
||||
provide: `${capitalize(
|
||||
convertClassNameToObjectMetadataName(objectMetadata.name),
|
||||
)}Repository`,
|
||||
useFactory: (
|
||||
globalWorkspaceOrmManager: GlobalWorkspaceOrmManager,
|
||||
workspaceManyOrAllFlatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
|
||||
) => {
|
||||
return new repositoryClass(
|
||||
globalWorkspaceOrmManager,
|
||||
workspaceManyOrAllFlatEntityMapsCacheService,
|
||||
);
|
||||
useFactory: (globalWorkspaceOrmManager: GlobalWorkspaceOrmManager) => {
|
||||
return new repositoryClass(globalWorkspaceOrmManager);
|
||||
},
|
||||
inject: [
|
||||
GlobalWorkspaceOrmManager,
|
||||
WorkspaceManyOrAllFlatEntityMapsCacheService,
|
||||
],
|
||||
inject: [GlobalWorkspaceOrmManager],
|
||||
};
|
||||
});
|
||||
|
||||
return {
|
||||
module: ObjectMetadataRepositoryModule,
|
||||
imports: [
|
||||
WorkspaceDataSourceModule,
|
||||
TwentyORMModule,
|
||||
WorkspaceManyOrAllFlatEntityMapsCacheModule,
|
||||
],
|
||||
imports: [WorkspaceDataSourceModule, TwentyORMModule],
|
||||
providers: [...providers],
|
||||
exports: providers,
|
||||
};
|
||||
|
||||
+1
-53
@@ -1,12 +1,10 @@
|
||||
import { Injectable, Logger } from '@nestjs/common';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
|
||||
import { isDefined } from 'class-validator';
|
||||
import { type ObjectRecord } from 'twenty-shared/types';
|
||||
import { In, MoreThan } from 'typeorm';
|
||||
|
||||
import { objectRecordDiffMerge } from 'src/engine/core-modules/event-emitter/utils/object-record-diff-merge';
|
||||
import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
|
||||
import { buildFieldMapsFromFlatObjectMetadata } from 'src/engine/metadata-modules/flat-field-metadata/utils/build-field-maps-from-flat-object-metadata.util';
|
||||
import { GlobalWorkspaceOrmManager } from 'src/engine/twenty-orm/global-workspace-datasource/global-workspace-orm.manager';
|
||||
import { buildSystemAuthContext } from 'src/engine/twenty-orm/utils/build-system-auth-context.util';
|
||||
import { type TimelineActivityPayload } from 'src/modules/timeline/types/timeline-activity-payload';
|
||||
@@ -22,11 +20,8 @@ type TimelineActivityPayloadWorkspaceIdAndObjectSingularName = {
|
||||
|
||||
@Injectable()
|
||||
export class TimelineActivityRepository {
|
||||
private readonly logger = new Logger(TimelineActivityRepository.name);
|
||||
|
||||
constructor(
|
||||
private readonly globalWorkspaceOrmManager: GlobalWorkspaceOrmManager,
|
||||
private readonly workspaceManyOrAllFlatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
|
||||
) {}
|
||||
|
||||
async upsertTimelineActivities({
|
||||
@@ -34,23 +29,6 @@ export class TimelineActivityRepository {
|
||||
workspaceId,
|
||||
payloads,
|
||||
}: TimelineActivityPayloadWorkspaceIdAndObjectSingularName) {
|
||||
const timelineActivityPropertyName =
|
||||
await this.getTimelineActivityPropertyName(objectSingularName);
|
||||
|
||||
const hasMorphRelationField =
|
||||
await this.hasTimelineActivityMorphRelationField(
|
||||
workspaceId,
|
||||
timelineActivityPropertyName,
|
||||
);
|
||||
|
||||
if (!hasMorphRelationField) {
|
||||
this.logger.warn(
|
||||
`Skipping timeline activity upsert: morph relation field "${timelineActivityPropertyName}" is missing in timelineActivity metadata for object "${objectSingularName}" in workspace ${workspaceId}. Run workspace:sync-metadata to fix.`,
|
||||
);
|
||||
|
||||
return;
|
||||
}
|
||||
|
||||
const authContext = buildSystemAuthContext(workspaceId);
|
||||
|
||||
await this.globalWorkspaceOrmManager.executeInWorkspaceContext(async () => {
|
||||
@@ -218,34 +196,4 @@ export class TimelineActivityRepository {
|
||||
private async getTimelineActivityPropertyName(objectSingularName: string) {
|
||||
return `${buildTimelineActivityRelatedMorphFieldMetadataName(objectSingularName)}Id`;
|
||||
}
|
||||
|
||||
private async hasTimelineActivityMorphRelationField(
|
||||
workspaceId: string,
|
||||
joinColumnName: string,
|
||||
): Promise<boolean> {
|
||||
const { flatFieldMetadataMaps, flatObjectMetadataMaps } =
|
||||
await this.workspaceManyOrAllFlatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
|
||||
{
|
||||
workspaceId,
|
||||
flatMapsKeys: ['flatFieldMetadataMaps', 'flatObjectMetadataMaps'],
|
||||
},
|
||||
);
|
||||
|
||||
const timelineActivityObjectMetadata = Object.values(
|
||||
flatObjectMetadataMaps.byId,
|
||||
).find(
|
||||
(objectMetadata) => objectMetadata?.nameSingular === 'timelineActivity',
|
||||
);
|
||||
|
||||
if (!timelineActivityObjectMetadata) {
|
||||
return false;
|
||||
}
|
||||
|
||||
const { fieldIdByJoinColumnName } = buildFieldMapsFromFlatObjectMetadata(
|
||||
flatFieldMetadataMaps,
|
||||
timelineActivityObjectMetadata,
|
||||
);
|
||||
|
||||
return isDefined(fieldIdByJoinColumnName[joinColumnName]);
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user