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.mdx
new file mode 100644
index 0000000000..3b2f701a38
--- /dev/null
+++ b/packages/twenty-docs/l/ar/user-guide/ai/capabilities/mcp.mdx
@@ -0,0 +1,142 @@
+---
+title: خادم MCP
+description: اربط مساعدي الذكاء الاصطناعي بمساحة عمل Twenty الخاصة بك باستخدام بروتوكول سياق النموذج.
+---
+
+
+MCP حاليًا في مرحلة **ألفا** وهو متاح فقط في بعض مساحات العمل. قد لا يكون مفعّلًا لمساحة عملك بعد.
+
+
+تعرض 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 لديك نافذة متصفح لتسجيل الدخول. لا يتم تخزين أي أسرار في ملفات الإعداد، ويتم تحديث الرموز المميِّزة تلقائيًا.
+
+
+يتطلب OAuth عميل MCP يدعم [مواصفة تفويض MCP](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). تدعمه Claude Desktop وClaude Code وCursor وChatGPT.
+
+
+أضِف ما يلي إلى تهيئة عميل 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"
+ }
+ }
+ }
+}
+```
+
+
+يمنح مفتاح API الخاص بك حق الوصول إلى بيانات مساحة العمل. أبعِده عن أنظمة التحكم في الإصدارات وملفات dotfiles المشتركة.
+
+
+لإنشاء مفتاح 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.mdx
new file mode 100644
index 0000000000..533c079d55
--- /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.
+---
+
+
+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.
+
+
+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.
+
+
+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.
+
+
+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"
+ }
+ }
+ }
+}
+```
+
+
+Ihr API-Schlüssel gewährt Zugriff auf Workspace-Daten. Halten Sie ihn von der Versionskontrolle und gemeinsam genutzten Dotfiles fern.
+
+
+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.mdx
new file mode 100644
index 0000000000..ff92b6462e
--- /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.
+---
+
+
+MCP è attualmente in **alpha** ed è disponibile solo su alcuni spazi di lavoro. Potrebbe non essere ancora abilitato per il tuo spazio di lavoro.
+
+
+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.
+
+
+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.
+
+
+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"
+ }
+ }
+ }
+}
+```
+
+
+Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
+
+
+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.mdx
new file mode 100644
index 0000000000..7b3087da07
--- /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.
+---
+
+
+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.
+
+
+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.
+
+
+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.
+
+
+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"
+ }
+ }
+ }
+}
+```
+
+
+Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
+
+
+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.mdx
new file mode 100644
index 0000000000..066358d785
--- /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.
+---
+
+
+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.
+
+
+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.
+
+
+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ă.
+
+
+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"
+ }
+ }
+ }
+}
+```
+
+
+Cheia ta API oferă acces la datele spațiului de lucru. Ține-o în afara controlului versiunilor și a dotfiles partajate.
+
+
+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.mdx
new file mode 100644
index 0000000000..9aa48848af
--- /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.
+---
+
+
+В настоящее время MCP находится на стадии **alpha** и доступен только в некоторых рабочих пространствах. В вашем рабочем пространстве он может быть ещё не включён.
+
+
+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.
+
+
+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.
+
+
+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"
+ }
+ }
+ }
+}
+```
+
+
+Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
+
+
+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.mdx
new file mode 100644
index 0000000000..2ca9d7d6cc
--- /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.
+---
+
+
+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.
+
+
+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.
+
+
+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.
+
+
+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"
+ }
+ }
+ }
+}
+```
+
+
+Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
+
+
+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.mdx
new file mode 100644
index 0000000000..da452086dc
--- /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 工作区。
+---
+
+
+MCP 目前处于**alpha**阶段，并且仅在部分工作区可用。 它可能尚未在你的工作区启用。
+
+
+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.
+
+
+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.
+
+
+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"
+ }
+ }
+ }
+}
+```
+
+
+Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
+
+
+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.