The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
i18n - docs translations (#18674)
github-actions[bot]5011e1d77bd3
diff --git a/packages/twenty-docs/l/ar/user-guide/ai/capabilities/mcp.mdx b/packages/twenty-docs/l/ar/user-guide/ai/capabilities/mcp.mdxnew file mode 100644index 00000000000..3b2f701a383--- /dev/null+++ b/packages/twenty-docs/l/ar/user-guide/ai/capabilities/mcp.mdx@@ -0,0 +1,142 @@+---+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` مُعيَّن بشكل صحيح.diff --git a/packages/twenty-docs/l/de/user-guide/ai/capabilities/mcp.mdx b/packages/twenty-docs/l/de/user-guide/ai/capabilities/mcp.mdxnew file mode 100644index 00000000000..533c079d55e--- /dev/null+++ b/packages/twenty-docs/l/de/user-guide/ai/capabilities/mcp.mdx@@ -0,0 +1,142 @@+---+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.diff --git a/packages/twenty-docs/l/it/user-guide/ai/capabilities/mcp.mdx b/packages/twenty-docs/l/it/user-guide/ai/capabilities/mcp.mdxnew file mode 100644index 00000000000..ff92b6462e7--- /dev/null+++ b/packages/twenty-docs/l/it/user-guide/ai/capabilities/mcp.mdx@@ -0,0 +1,142 @@+---+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.diff --git a/packages/twenty-docs/l/pt/user-guide/ai/capabilities/mcp.mdx b/packages/twenty-docs/l/pt/user-guide/ai/capabilities/mcp.mdxnew file mode 100644index 00000000000..7b3087da071--- /dev/null+++ b/packages/twenty-docs/l/pt/user-guide/ai/capabilities/mcp.mdx@@ -0,0 +1,142 @@+---+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.diff --git a/packages/twenty-docs/l/ro/user-guide/ai/capabilities/mcp.mdx b/packages/twenty-docs/l/ro/user-guide/ai/capabilities/mcp.mdxnew file mode 100644index 00000000000..066358d785f--- /dev/null+++ b/packages/twenty-docs/l/ro/user-guide/ai/capabilities/mcp.mdx@@ -0,0 +1,142 @@+---+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.diff --git a/packages/twenty-docs/l/ru/user-guide/ai/capabilities/mcp.mdx b/packages/twenty-docs/l/ru/user-guide/ai/capabilities/mcp.mdxnew file mode 100644index 00000000000..9aa48848af9--- /dev/null+++ b/packages/twenty-docs/l/ru/user-guide/ai/capabilities/mcp.mdx@@ -0,0 +1,142 @@+---+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.diff --git a/packages/twenty-docs/l/tr/user-guide/ai/capabilities/mcp.mdx b/packages/twenty-docs/l/tr/user-guide/ai/capabilities/mcp.mdxnew file mode 100644index 00000000000..2ca9d7d6cc4--- /dev/null+++ b/packages/twenty-docs/l/tr/user-guide/ai/capabilities/mcp.mdx@@ -0,0 +1,142 @@+---+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.diff --git a/packages/twenty-docs/l/zh/user-guide/ai/capabilities/mcp.mdx b/packages/twenty-docs/l/zh/user-guide/ai/capabilities/mcp.mdxnew file mode 100644index 00000000000..da452086dc9--- /dev/null+++ b/packages/twenty-docs/l/zh/user-guide/ai/capabilities/mcp.mdx@@ -0,0 +1,142 @@+---+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.