mirror/twenty
1
0
Fork 0
mirror of https://github.com/twentyhq/twenty.git synced 2026-06-12 09:57:03 -04:00
Code Issues Packages Projects Releases Wiki Activity

i18n - docs translations (#18677)

Browse Source 
Created by Github action

Co-authored-by: github-actions <github-actions@twenty.com>
This commit is contained in:
github-actions[bot]
2026-03-16 14:14:29 +01:00
committed by GitHub
parent 5011e1d77b
commit ddedecbb36
8 changed files with 290 additions and 290 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
packages/twenty-docs/l/ar/user-guide/ai/capabilities/mcp.mdx
View File

@@ -1,5 +1,5 @@
---
title: خادم MCP
title: خادم MCP},{
description: اربط مساعدي الذكاء الاصطناعي بمساحة عمل Twenty الخاصة بك باستخدام بروتوكول سياق النموذج.
---
@@ -72,7 +72,7 @@ MCP حاليًا في مرحلة **ألفا** وهو متاح فقط في بعض
يمنح مفتاح API الخاص بك حق الوصول إلى بيانات مساحة العمل. أبعِده عن أنظمة التحكم في الإصدارات وملفات dotfiles المشتركة.
</Warning>
لإنشاء مفتاح API، انتقل إلى **Settings > APIs & Webhooks > + Create key**. راجع [واجهات برمجة التطبيقات](/l/ar/developers/extend/api) للتفاصيل.
لإنشاء مفتاح API، انتقل إلى **Settings > APIs & Webhooks > + Create key**. راجع [واجهات برمجة التطبيقات](/l/ar/developers/extend/api#create-an-api-key) للتفاصيل.
## البدء السريع

8
packages/twenty-docs/l/de/user-guide/ai/capabilities/mcp.mdx
View File

@@ -69,10 +69,10 @@ Wenn Ihr MCP-Client OAuth nicht unterstützt oder Sie statische Anmeldeinformati
```
<Warning>
Ihr API-Schlüssel gewährt Zugriff auf Workspace-Daten. Halten Sie ihn von der Versionskontrolle und gemeinsam genutzten Dotfiles fern.
Ihr API-Schlüssel gewährt Zugriff auf Workspace-Daten. Halten Sie es von der Versionskontrolle und von 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).
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#create-an-api-key).
## Schnellstart
@@ -118,7 +118,7 @@ MCP-Verbindungen erben die Berechtigungen des authentifizierten Benutzers (OAuth
## 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.
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 — dieser Wert wird verwendet, um die OAuth-Discovery-Metadaten zu generieren.
```bash
SERVER_URL=https://twenty.yourcompany.com
@@ -131,7 +131,7 @@ Der MCP-Endpunkt, die OAuth-Endpunkte und die Discovery-Metadaten leiten sich al
**"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.
* API-Schlüssel: Überprüfen Sie, ob der Schlüssel gültig ist und nicht abgelaufen ist. Generieren Sie ihn bei Bedarf neu.
**Der OAuth-Flow öffnet keinen Browser**

114
packages/twenty-docs/l/it/user-guide/ai/capabilities/mcp.mdx
View File

@@ -7,28 +7,28 @@ description: Collega gli assistenti AI al tuo spazio di lavoro di Twenty utilizz
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.
Twenty espone un server [MCP](https://modelcontextprotocol.io/) affinché gli assistenti AI — Claude Desktop, Claude Code, Cursor, ChatGPT e altri — possano leggere e scrivere i dati del tuo CRM in linguaggio naturale.
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:
Usa l'**URL dello spazio di lavoro** (l'URL che usi per accedere a Twenty) come endpoint MCP. Su Twenty Cloud, l'URL del tuo spazio di lavoro potrebbe essere `https://{mycompany}.twenty.com` oppure un dominio personalizzato. Il server è disponibile all'indirizzo:
| Ambiente | MCP Endpoint |
| ----------------- | ---------------------------------------------------------------------------- |
| **Cloud** | `https://{your-workspace-url}/mcp` (e.g. `https://mycompany.twenty.com/mcp`) |
| **Auto-ospitato** | `https://{your-domain}/mcp` |
| Ambiente | Endpoint MCP |
| ----------------- | ------------------------------------------------------------------------------ |
| **Cloud** | `https://{your-workspace-url}/mcp` (ad es. `https://mycompany.twenty.com/mcp`) |
| **Auto-ospitato** | `https://{your-domain}/mcp` |
## Authentication Methods
## Metodi di autenticazione
You have two ways to authenticate your MCP client: **OAuth** (recommended) or **API Key**.
Hai due modi per autenticare il tuo client MCP: **OAuth** (consigliato) o **API Key**.
### Option A — OAuth (Recommended)
### Opzione A — OAuth (Consigliato)
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.
Con OAuth, il tuo client MCP apre una finestra del browser per effettuare l'accesso. Nessun segreto viene archiviato nei file di configurazione e i token si rinnovano automaticamente.
<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.
OAuth richiede un client MCP che supporti la [specifica MCP Authorization](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor e ChatGPT lo supportano.
</Note>
Add this to your MCP client configuration, replacing `{your-workspace-url}` with your workspace host (e.g. `mycompany.twenty.com`):
Aggiungi questo alla configurazione del tuo client MCP, sostituendo `{your-workspace-url}` con l'host del tuo spazio di lavoro (ad es. `mycompany.twenty.com`):
```json
{
@@ -41,18 +41,18 @@ Add this to your MCP client configuration, replacing `{your-workspace-url}` with
}
```
That's it — no API key needed. When the client connects for the first time it will:
È tutto — non è necessaria alcuna chiave API. Quando il client si connette per la prima volta, eseguirà:
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
1. Scoprire i metadati OAuth di Twenty tramite `/.well-known/oauth-protected-resource` e `/.well-known/oauth-authorization-server`
2. Registrarsi come client OAuth tramite registrazione dinamica del client (RFC 7591)
3. Aprire il browser per autorizzare l'accesso
4. Ricevere i token e connettersi al server MCP
Subsequent connections reuse the stored tokens and refresh them automatically.
Le connessioni successive riutilizzano i token memorizzati e li rinnovano automaticamente.
### Option B — API Key
### Opzione B — Chiave API
If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the `Authorization` header:
Se il tuo client MCP non supporta OAuth, o preferisci credenziali statiche, passa una chiave API nell'header `Authorization`:
```json
{
@@ -69,74 +69,74 @@ If your MCP client does not support OAuth, or you prefer static credentials, pas
```
<Warning>
Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
La tua chiave API concede l'accesso ai dati dello spazio di lavoro. Mantienila fuori dal controllo versione e dai dotfile condivisi.
</Warning>
To create an API key, go to **Settings > APIs & Webhooks > + Create key**. See [APIs](/l/it/developers/extend/api) for details.
Per creare una chiave API, vai su **Impostazioni > API e Webhook > + Crea chiave**. Vedi [API](/l/it/developers/extend/api#create-an-api-key) per i dettagli.
## Quick Start
## Avvio rapido
### 1. Copy the config
### 1. Copia la configurazione
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.
Vai su **Impostazioni > AI > Altro > MCP Server** in Twenty. Scegli il metodo di autenticazione (OAuth o Chiave API), copia lo snippet JSON (userà già l'URL del tuo spazio di lavoro) e incollalo nel file di configurazione del tuo client MCP.
| 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 |
| Client | Percorso del file di configurazione |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| **Claude Code** | `~/.claude.json` (utente) o `.mcp.json` (progetto) |
| **Cursor** | `.cursor/mcp.json` nel tuo progetto, oppure `~/.cursor/mcp.json` globalmente |
| **ChatGPT** | Attiva la Modalità sviluppatore in **Impostazioni > App e Connettori > Impostazioni avanzate**, quindi usa **Crea** in **Impostazioni > App e Connettori** per aggiungere il server MCP |
### 2. Connect
### 2. Connetti
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.
Riavvia il tuo client MCP (o ricarica la configurazione). Se usi OAuth verrai reindirizzato a Twenty per autorizzare l'accesso. Se usi una chiave API la connessione è immediata.
### 3. Start using it
### 3. Inizia a usarlo
Ask your AI assistant to interact with your CRM:
Chiedi al tuo assistente AI di interagire con il tuo 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"*
* *"Mostrami le 5 aziende create più di recente"*
* *"Crea una nuova persona di nome Jane Doe presso Acme Corp"*
* *"Trova tutte le opportunità aperte di valore superiore a $10k"*
## Available Tools
## Strumenti disponibili
Once connected, the MCP server exposes tools that mirror the Twenty API. The recommended workflow is:
Una volta connesso, il server MCP espone strumenti che rispecchiano l'API di Twenty. Il flusso di lavoro consigliato è:
1. **`get_tool_catalog`** — discover all available tools
2. **`learn_tools`** — get the input schema for specific tools
3. **`execute_tool`** — run a tool
1. **`get_tool_catalog`** — scoprire tutti gli strumenti disponibili
2. **`learn_tools`** — ottenere lo schema di input per strumenti specifici
3. **`execute_tool`** — eseguire uno strumento
You don't need to remember tool names. Ask your AI assistant what it can do and it will call `get_tool_catalog` automatically.
Non è necessario ricordare i nomi degli strumenti. Chiedi al tuo assistente AI cosa può fare e chiamerà `get_tool_catalog` automaticamente.
## 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:
Le connessioni MCP ereditano le autorizzazioni dell'utente autenticato (OAuth) o il ruolo assegnato alla chiave API. Per limitare ciò che il server MCP può fare:
* **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).
* **OAuth**: si applica il ruolo dell'utente nello spazio di lavoro.
* **Chiave API**: assegna un ruolo alla chiave API in **Impostazioni > Ruoli**. Vedi [Autorizzazioni](/l/it/user-guide/permissions-access/capabilities/permissions).
## Self-Hosted Configuration
## Configurazione self-hosted
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.
Per le istanze self-hosted, sostituisci `{your-workspace-url}` con l'URL del tuo server. Assicurati che `SERVER_URL` nel tuo ambiente corrisponda all'URL pubblico della tua istanza Twenty — viene utilizzato per generare i metadati di discovery OAuth.
```bash
SERVER_URL=https://twenty.yourcompany.com
```
The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.
L'endpoint MCP, gli endpoint OAuth e i metadati di discovery derivano tutti da questo valore.
## Risoluzione dei problemi
**"Unauthorized" or 401 errors**
**Errori "Unauthorized" o 401**
* 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: esegui nuovamente l'autorizzazione eliminando i token memorizzati nel tuo client MCP e riconnettiti.
* Chiave API: verifica che la chiave sia valida e non sia scaduta. Rigenerala se necessario.
**OAuth flow doesn't open a browser**
**Il flusso OAuth non apre il browser**
* Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn't.
* Assicurati che il tuo client MCP supporti MCP Authorization. In caso contrario, ricorri al metodo con Chiave API.
**Connection timeout**
**Timeout di connessione**
* 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.
* Verifica che l'URL dell'endpoint MCP sia raggiungibile dalla tua macchina. Per le istanze self-hosted, controlla che il server sia in esecuzione e che `SERVER_URL` sia impostato correttamente.

114
packages/twenty-docs/l/pt/user-guide/ai/capabilities/mcp.mdx
View File

@@ -7,28 +7,28 @@ description: Conecte assistentes de IA ao seu espaço de trabalho do Twenty usan
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.
O Twenty expõe um servidor [MCP](https://modelcontextprotocol.io/) para que assistentes de IA — Claude Desktop, Claude Code, Cursor, ChatGPT e outros — possam ler e escrever seus dados de CRM por meio de linguagem natural.
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:
Use o **URL do espaço de trabalho** (o URL que você usa para acessar o Twenty) como o endpoint do MCP. Na Twenty Cloud, o URL do seu espaço de trabalho pode ser `https://{mycompany}.twenty.com` ou um domínio personalizado. O servidor está disponível em:
| Ambiente | MCP Endpoint |
| ------------------ | ---------------------------------------------------------------------------- |
| **Nuvem** | `https://{your-workspace-url}/mcp` (e.g. `https://mycompany.twenty.com/mcp`) |
| **Auto-hospedado** | `https://{your-domain}/mcp` |
| Ambiente | Endpoint do MCP |
| ------------------ | ------------------------------------------------------------------------------------ |
| **Nuvem** | `https://{your-workspace-url}/mcp` (por exemplo, `https://mycompany.twenty.com/mcp`) |
| **Auto-hospedado** | `https://{your-domain}/mcp` |
## Authentication Methods
## Métodos de autenticação
You have two ways to authenticate your MCP client: **OAuth** (recommended) or **API Key**.
Você tem duas maneiras de autenticar seu cliente MCP: **OAuth** (recomendado) ou **Chave de API**.
### Option A — OAuth (Recommended)
### Opção A — OAuth (recomendado)
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.
Com o OAuth, seu cliente MCP abre uma janela do navegador para você fazer login. Nenhum segredo é armazenado em arquivos de configuração, e os tokens são atualizados automaticamente.
<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.
O OAuth requer um cliente MCP que ofereça suporte à [especificação de Autorização MCP](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor e ChatGPT oferecem suporte.
</Note>
Add this to your MCP client configuration, replacing `{your-workspace-url}` with your workspace host (e.g. `mycompany.twenty.com`):
Adicione isto à configuração do seu cliente MCP, substituindo `{your-workspace-url}` pelo host do seu espaço de trabalho (por exemplo, `mycompany.twenty.com`):
```json
{
@@ -41,18 +41,18 @@ Add this to your MCP client configuration, replacing `{your-workspace-url}` with
}
```
That's it — no API key needed. When the client connects for the first time it will:
É isso — nenhuma chave de API é necessária. Quando o cliente se conectar pela primeira vez, ele irá:
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
1. Descobrir os metadados de OAuth do Twenty por meio de `/.well-known/oauth-protected-resource` e `/.well-known/oauth-authorization-server`
2. Registrar-se como um cliente OAuth por meio de registro dinâmico de cliente (RFC 7591)
3. Abrir seu navegador para autorizar o acesso
4. Receber tokens e conectar-se ao servidor MCP
Subsequent connections reuse the stored tokens and refresh them automatically.
Conexões subsequentes reutilizam os tokens armazenados e os atualizam automaticamente.
### Option B — API Key
### Opção B — Chave de API
If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the `Authorization` header:
Se o seu cliente MCP não oferecer suporte a OAuth, ou se você preferir credenciais estáticas, passe uma chave de API no cabeçalho `Authorization`:
```json
{
@@ -69,74 +69,74 @@ If your MCP client does not support OAuth, or you prefer static credentials, pas
```
<Warning>
Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
Sua chave de API concede acesso aos dados do espaço de trabalho. Mantenha-a fora do controle de versão e de dotfiles compartilhados.
</Warning>
To create an API key, go to **Settings > APIs & Webhooks > + Create key**. See [APIs](/l/pt/developers/extend/api) for details.
Para criar uma chave de API, vá em **Settings > APIs & Webhooks > + Create key**. Veja [APIs](/l/pt/developers/extend/api#create-an-api-key) para detalhes.
## Quick Start
## Início rápido
### 1. Copy the config
### 1. Copie a configuração
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.
Vá até **Settings > AI > More > MCP Server** no Twenty. Escolha seu método de autenticação (OAuth ou Chave de API), copie o trecho de JSON (ele já usará o URL do seu espaço de trabalho) e cole-o no arquivo de configuração do seu cliente MCP.
| 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 |
| Cliente | Local do arquivo de configuração |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| **Claude Code** | `~/.claude.json` (usuário) ou `.mcp.json` (projeto) |
| **Cursor** | `.cursor/mcp.json` no seu projeto, ou `~/.cursor/mcp.json` globalmente |
| **ChatGPT** | Ative o Modo Desenvolvedor em **Settings > Apps & Connectors > Advanced settings** e, em seguida, use **Create** em **Settings > Apps & Connectors** para adicionar o servidor MCP |
### 2. Connect
### 2. Conectar
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.
Reinicie seu cliente MCP (ou recarregue a configuração). Se estiver usando OAuth, você será redirecionado ao Twenty para autorizar o acesso. Se estiver usando uma chave de API, a conexão é imediata.
### 3. Start using it
### 3. Comece a usá-lo
Ask your AI assistant to interact with your CRM:
Peça ao seu assistente de IA para interagir com seu 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"*
* *"Mostre-me as 5 empresas criadas mais recentemente"*
* *"Crie uma nova pessoa chamada Jane Doe na Acme Corp"*
* *"Encontre todas as oportunidades em aberto com valor superior a $10k"*
## Available Tools
## Ferramentas disponíveis
Once connected, the MCP server exposes tools that mirror the Twenty API. The recommended workflow is:
Depois de conectado, o servidor MCP expõe ferramentas que refletem a API do Twenty. O fluxo de trabalho recomendado é:
1. **`get_tool_catalog`** — discover all available tools
2. **`learn_tools`** — get the input schema for specific tools
3. **`execute_tool`** — run a tool
1. **`get_tool_catalog`** — descobrir todas as ferramentas disponíveis
2. **`learn_tools`** — obter o esquema de entrada para ferramentas específicas
3. **`execute_tool`** — executar uma ferramenta
You don't need to remember tool names. Ask your AI assistant what it can do and it will call `get_tool_catalog` automatically.
Você não precisa se lembrar dos nomes das ferramentas. Pergunte ao seu assistente de IA o que ele pode fazer e ele chamará `get_tool_catalog` automaticamente.
## 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:
As conexões MCP herdam as permissões do usuário autenticado (OAuth) ou da função atribuída à chave de API. Para restringir o que o servidor MCP pode fazer:
* **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).
* **OAuth**: Aplica-se à função do espaço de trabalho do usuário.
* **Chave de API**: Atribua uma função à chave de API em **Settings > Roles**. Veja [Permissões](/l/pt/user-guide/permissions-access/capabilities/permissions).
## Self-Hosted Configuration
## Configuração auto-hospedada
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.
Para instâncias auto-hospedadas, substitua `{your-workspace-url}` pelo URL do seu servidor. Certifique-se de que `SERVER_URL` no seu ambiente corresponda ao URL público da sua instância do Twenty — isso é usado para gerar os metadados de descoberta do OAuth.
```bash
SERVER_URL=https://twenty.yourcompany.com
```
The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.
O endpoint do MCP, os endpoints de OAuth e os metadados de descoberta derivam todos desse valor.
## Resolução de Problemas
**"Unauthorized" or 401 errors**
**Erros "Unauthorized" ou 401**
* 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: autorize novamente limpando os tokens armazenados no seu cliente MCP e reconectando.
* Chave de API: verifique se a chave é válida e não expirou. Gere-a novamente, se necessário.
**OAuth flow doesn't open a browser**
**O fluxo do OAuth não abre um navegador**
* Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn't.
* Garanta que seu cliente MCP ofereça suporte à Autorização MCP. Se não oferecer, utilize o método de Chave de API.
**Connection timeout**
**Tempo limite de conexão**
* 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.
* Confirme que o URL do endpoint MCP é acessível a partir da sua máquina. Para instâncias auto-hospedadas, verifique se o servidor está em execução e se `SERVER_URL` está definido corretamente.

2
packages/twenty-docs/l/ro/user-guide/ai/capabilities/mcp.mdx
View File

@@ -72,7 +72,7 @@ Dacă clientul tău MCP nu suportă OAuth sau preferi acreditări statice, furni
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.
Pentru a crea o cheie API, mergi la **Settings > APIs & Webhooks > + Create key**. Vezi [API-uri](/l/ro/developers/extend/api#create-an-api-key) pentru detalii.
## Pornire rapidă

114
packages/twenty-docs/l/ru/user-guide/ai/capabilities/mcp.mdx
View File

@@ -7,28 +7,28 @@ description: Подключайте ИИ-ассистентов к вашему
В настоящее время 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.
Twenty предоставляет сервер [MCP](https://modelcontextprotocol.io/), чтобы ИИ-ассистенты — Claude Desktop, Claude Code, Cursor, ChatGPT и другие — могли читать и записывать ваши данные CRM на естественном языке.
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:
Используйте **URL рабочей области** (URL, который вы используете для доступа к Twenty) в качестве конечной точки MCP. В Twenty Cloud URL вашей рабочей области может быть `https://{mycompany}.twenty.com` или собственный домен. Сервер доступен по адресу:
| Среда | MCP Endpoint |
| --------------------------- | ---------------------------------------------------------------------------- |
| **Облако** | `https://{your-workspace-url}/mcp` (e.g. `https://mycompany.twenty.com/mcp`) |
| **Самостоятельный хостинг** | `https://{your-domain}/mcp` |
| Среда | Конечная точка MCP |
| --------------------------- | --------------------------------------------------------------------------------- |
| **Облако** | `https://{your-workspace-url}/mcp` (например, `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**.
Есть два способа аутентифицировать ваш MCP-клиент: **OAuth** (рекомендуется) или **API Key**.
### Option A — OAuth (Recommended)
### Вариант A — OAuth (рекомендуется)
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 ваш MCP-клиент откроет окно браузера для входа в систему. Секреты не хранятся в файлах конфигурации, а токены обновляются автоматически.
<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.
Для OAuth требуется MCP-клиент, поддерживающий [спецификацию авторизации MCP](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Её поддерживают Claude Desktop, Claude Code, Cursor и ChatGPT.
</Note>
Add this to your MCP client configuration, replacing `{your-workspace-url}` with your workspace host (e.g. `mycompany.twenty.com`):
Добавьте это в конфигурацию вашего MCP-клиента, заменив `{your-workspace-url}` на хост вашей рабочей области (например, `mycompany.twenty.com`):
```json
{
@@ -41,18 +41,18 @@ Add this to your MCP client configuration, replacing `{your-workspace-url}` with
}
```
That's it — no API key needed. When the client connects for the first time it will:
Вот и всё — ключ API не требуется. При первом подключении клиент выполнит:
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
1. Обнаружит метаданные OAuth Twenty через `/.well-known/oauth-protected-resource` и `/.well-known/oauth-authorization-server`
2. Зарегистрирует себя как OAuth-клиент через динамическую регистрацию клиентов (RFC 7591)
3. Откроет браузер для авторизации доступа
4. Получит токены и подключится к серверу MCP
Subsequent connections reuse the stored tokens and refresh them automatically.
При последующих подключениях используются сохранённые токены, которые автоматически обновляются.
### Option B — API Key
### Вариант B — ключ API
If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the `Authorization` header:
Если ваш MCP-клиент не поддерживает OAuth или вы предпочитаете статические учётные данные, передайте ключ API в заголовке `Authorization`:
```json
{
@@ -69,74 +69,74 @@ If your MCP client does not support OAuth, or you prefer static credentials, pas
```
<Warning>
Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
Ваш ключ API предоставляет доступ к данным рабочей области. Не храните его в системе контроля версий и общих dotfiles.
</Warning>
To create an API key, go to **Settings > APIs & Webhooks > + Create key**. See [APIs](/l/ru/developers/extend/api) for details.
Чтобы создать ключ API, перейдите в **Settings > APIs & Webhooks > + Create key**. См. [API](/l/ru/developers/extend/api#create-an-api-key) для подробностей.
## Quick Start
## Быстрый старт
### 1. Copy the config
### 1. Скопируйте конфигурацию
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.
Перейдите в **Settings > AI > More > MCP Server** в Twenty. Выберите метод аутентификации (OAuth или ключ API), скопируйте фрагмент JSON (в нём уже будет использован URL вашей рабочей области) и вставьте его в файл конфигурации вашего MCP-клиента.
| 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 |
| Клиент | Расположение файла конфигурации |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **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 |
### 2. Connect
### 2. Подключение
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.
Перезапустите ваш MCP-клиент (или перезагрузите конфигурацию). Если используется OAuth, вы будете перенаправлены в Twenty для авторизации доступа. Если используется ключ API, подключение произойдёт сразу.
### 3. Start using it
### 3. Начните использовать
Ask your AI assistant to interact with your CRM:
Попросите вашего ИИ-ассистента взаимодействовать с вашей 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"*
* *"Покажи мне 5 последних созданных компаний"*
* *"Создай новый контакт по имени Jane Doe в компании Acme Corp"*
* *"Найди все открытые сделки стоимостью более $10 000"*
## Available Tools
## Доступные инструменты
Once connected, the MCP server exposes tools that mirror the Twenty API. The recommended workflow is:
После подключения сервер MCP предоставляет инструменты, отражающие API Twenty. Рекомендуемый рабочий процесс:
1. **`get_tool_catalog`** — discover all available tools
2. **`learn_tools`** — get the input schema for specific tools
3. **`execute_tool`** — run a tool
1. **`get_tool_catalog`** — получить список всех доступных инструментов
2. **`learn_tools`** — получить схему входных данных для конкретных инструментов
3. **`execute_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.
Вам не нужно запоминать названия инструментов. Спросите у вашего ИИ-ассистента, что он умеет, и он автоматически вызовет `get_tool_catalog`.
## Разрешения
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:
Подключения MCP наследуют разрешения аутентифицированного пользователя (OAuth) или роль, назначенную ключу API. Чтобы ограничить действия, доступные серверу MCP:
* **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).
* **OAuth**: Применяется роль пользователя в рабочей области.
* **API Key**: Назначьте ключу API роль в **Settings > Roles**. См. [Разрешения](/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.
Для экземпляров с самостоятельным хостингом замените `{your-workspace-url}` на URL вашего сервера. Убедитесь, что значение `SERVER_URL` в вашей среде соответствует публичному URL экземпляра Twenty — оно используется для генерации метаданных обнаружения OAuth.
```bash
SERVER_URL=https://twenty.yourcompany.com
```
The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.
Конечная точка MCP, конечные точки OAuth и метаданные обнаружения формируются на основе этого значения.
## Устранение неполадок
**"Unauthorized" or 401 errors**
**Ошибки "Unauthorized" или 401**
* 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: повторно авторизуйтесь, очистив сохранённые токены в вашем MCP-клиенте и переподключившись.
* API Key: убедитесь, что ключ действителен и не истёк. При необходимости сгенерируйте его заново.
**OAuth flow doesn't open a browser**
**Процесс OAuth не открывает браузер**
* Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn't.
* Убедитесь, что ваш MCP-клиент поддерживает MCP Authorization. Если нет — используйте метод с ключом API.
**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.
* Убедитесь, что URL конечной точки MCP доступен с вашего компьютера. Для экземпляров с самостоятельным хостингом проверьте, что сервер запущен и значение `SERVER_URL` установлено корректно.

110
packages/twenty-docs/l/tr/user-guide/ai/capabilities/mcp.mdx
View File

@@ -7,28 +7,28 @@ description: Model Context Protocol kullanarak yapay zeka asistanlarını Twenty
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.
Twenty, yapay zeka asistanlarının — Claude Desktop, Claude Code, Cursor, ChatGPT ve diğerlerinin — doğal dil aracılığıyla CRM verilerinizi okuması ve yazması için bir [MCP](https://modelcontextprotocol.io/) sunucusu sunar.
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 uç noktası olarak **çalışma alanı URL'nizi** (Twenty'ye erişmek için kullandığınız URL) kullanın. Twenty Cloud'da, çalışma alanı URL'niz `https://{mycompany}.twenty.com` ya da özel bir alan adı olabilir. Sunucu şu adreste kullanılabilir:
| Ortam | MCP Endpoint |
| Ortam | MCP Uç Noktası |
| ---------------------------- | ---------------------------------------------------------------------------- |
| **Bulut** | `https://{your-workspace-url}/mcp` (e.g. `https://mycompany.twenty.com/mcp`) |
| **Bulut** | `https://{your-workspace-url}/mcp` (örn. `https://mycompany.twenty.com/mcp`) |
| **Kendi Kendine Barındırma** | `https://{your-domain}/mcp` |
## Authentication Methods
## Kimlik Doğrulama Yöntemleri
You have two ways to authenticate your MCP client: **OAuth** (recommended) or **API Key**.
MCP istemcinizi kimlik doğrulamak için iki yolunuz var: **OAuth** (önerilir) veya **API Anahtarı**.
### Option A — OAuth (Recommended)
### Seçenek A — OAuth (Önerilir)
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 ile, MCP istemciniz oturum açmanız için bir tarayıcı penceresi açar. Gizli bilgiler yapılandırma dosyalarında saklanmaz ve belirteçler otomatik olarak yenilenir.
<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.
OAuth, [MCP Yetkilendirme belirtimi](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)ni destekleyen bir MCP istemcisi gerektirir. Claude Desktop, Claude Code, Cursor ve ChatGPT bunu destekler.
</Note>
Add this to your MCP client configuration, replacing `{your-workspace-url}` with your workspace host (e.g. `mycompany.twenty.com`):
Bunu MCP istemci yapılandırmanıza ekleyin; `{your-workspace-url}` öğesini çalışma alanınızın ana makine adıyla değiştirin (örn. `mycompany.twenty.com`):
```json
{
@@ -41,18 +41,18 @@ Add this to your MCP client configuration, replacing `{your-workspace-url}` with
}
```
That's it — no API key needed. When the client connects for the first time it will:
Hepsi bu — API anahtarı gerekmez. İstemci ilk kez bağlandığında şunları yapacaktır:
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
1. Twenty'nin OAuth üst verilerini `/.well-known/oauth-protected-resource` ve `/.well-known/oauth-authorization-server` üzerinden keşfeder
2. Dinamik istemci kaydı (RFC 7591) yoluyla kendisini bir OAuth istemcisi olarak kaydeder
3. Erişimi yetkilendirmek için tarayıcınızı açar
4. Belirteçleri alır ve MCP sunucusuna bağlanır
Subsequent connections reuse the stored tokens and refresh them automatically.
Sonraki bağlantılar, depolanan belirteçleri yeniden kullanır ve bunları otomatik olarak yeniler.
### Option B — API Key
### Seçenek B — API Anahtarı
If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the `Authorization` header:
MCP istemciniz OAuth'u desteklemiyorsa veya statik kimlik bilgilerini tercih ediyorsanız, `Authorization` üstbilgisinde bir API anahtarı gönderin:
```json
{
@@ -69,74 +69,74 @@ If your MCP client does not support OAuth, or you prefer static credentials, pas
```
<Warning>
Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
API anahtarınız çalışma alanı verilerine erişim sağlar. Sürüm kontrolünün ve paylaşılan dotfile'ların dışında tutun.
</Warning>
To create an API key, go to **Settings > APIs & Webhooks > + Create key**. See [APIs](/l/tr/developers/extend/api) for details.
Bir API anahtarı oluşturmak için **Settings > APIs & Webhooks > + Create key** bölümüne gidin. Ayrıntılar için [API'ler](/l/tr/developers/extend/api#create-an-api-key) bölümüne bakın.
## Quick Start
## Hızlı Başlangıç
### 1. Copy the config
### 1. Yapılandırmayı kopyalayın
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.
Twenty içinde **Settings > AI > More > MCP Server** bölümüne gidin. Kimlik doğrulama yöntemini (OAuth veya API Anahtarı) seçin, JSON parçacığını kopyalayın (çalışma alanı URL'nizi zaten kullanacaktır) ve MCP istemcinizin yapılandırma dosyasına yapıştırın.
| 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 |
| İstemci | Yapılandırma dosyasının konumu |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) veya `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| **Claude Code** | `~/.claude.json` (kullanıcı) veya `.mcp.json` (proje) |
| **Cursor** | Projenizde `.cursor/mcp.json` veya genel olarak `~/.cursor/mcp.json` |
| **ChatGPT** | Developer Mode'u **Settings > Apps & Connectors > Advanced settings** içinde açın, ardından MCP sunucusunu eklemek için **Settings > Apps & Connectors** içindeki **Create** seçeneğini kullanın |
### 2. Connect
### 2. Bağlan
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.
MCP istemcinizi yeniden başlatın (veya yapılandırmayı yeniden yükleyin). OAuth kullanıyorsanız, erişimi yetkilendirmek için Twenty'ye yönlendirileceksiniz. API anahtarı kullanıyorsanız, bağlantı anında kurulur.
### 3. Start using it
### 3. Kullanmaya başlayın
Ask your AI assistant to interact with your CRM:
Yapay zeka asistanınızdan CRM'inizle etkileşime geçmesini isteyin:
* *"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"*
* *"Bana en son oluşturulan 5 şirketi göster"*
* *"Acme Corp'ta Jane Doe adlı yeni bir kişi oluştur"*
* *"10.000 $'dan fazla değere sahip tüm açık fırsatları bul"*
## Available Tools
## Kullanılabilir Araçlar
Once connected, the MCP server exposes tools that mirror the Twenty API. The recommended workflow is:
Bağlandıktan sonra, MCP sunucusu Twenty API'sini yansıtan araçlar sunar. Önerilen iş akışı:
1. **`get_tool_catalog`** — discover all available tools
2. **`learn_tools`** — get the input schema for specific tools
3. **`execute_tool`** — run a tool
1. **`get_tool_catalog`** — mevcut tüm araçları keşfedin
2. **`learn_tools`** — belirli araçların girdi şemasını alın
3. **`execute_tool`** — bir aracı çalıştırın
You don't need to remember tool names. Ask your AI assistant what it can do and it will call `get_tool_catalog` automatically.
Araç adlarını hatırlamanıza gerek yok. Yapay zeka asistanınıza neler yapabileceğini sorun; `get_tool_catalog` çağrısını otomatik olarak yapacaktır.
## İ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:
MCP bağlantıları, kimliği doğrulanmış kullanıcının (OAuth) izinlerini veya API anahtarına atanan rolü devralır. MCP sunucusunun neler yapabileceğini kısıtlamak için:
* **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).
* **OAuth**: Kullanıcının çalışma alanı rolü geçerlidir.
* **API Anahtarı**: **Settings > Roles** altında API anahtarına bir rol atayın. Bkz. [İzinler](/l/tr/user-guide/permissions-access/capabilities/permissions).
## Self-Hosted Configuration
## Öz Barındırmalı Yapılandırma
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.
Öz barındırmalı kurulumlarda `{your-workspace-url}` değerini sunucunuzun URL'siyle değiştirin. Ortamınızdaki `SERVER_URL` değerinin Twenty örneğinizin genel URL'siyle eşleştiğinden emin olun — bu, OAuth keşif üst verilerini oluşturmak için kullanılır.
```bash
SERVER_URL=https://twenty.yourcompany.com
```
The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.
MCP uç noktası, OAuth uç noktaları ve keşif üst verilerinin tümü bu değerden türetilir.
## Sorun Giderme
**"Unauthorized" or 401 errors**
**"Unauthorized" veya 401 hataları**
* 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: MCP istemcinizde depolanan belirteçleri temizleyip yeniden bağlanarak yeniden yetkilendirin.
* API Anahtarı: anahtarın geçerli olduğunu ve süresinin dolmadığını doğrulayın. Gerekirse yeniden oluşturun.
**OAuth flow doesn't open a browser**
**OAuth akışı bir tarayıcı açmıyor**
* Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn't.
* MCP istemcinizin MCP Yetkilendirmeyi desteklediğinden emin olun. Desteklemiyorsa API Anahtarı yöntemine geri dönün.
**Connection timeout**
**Bağlantı zaman aşımı**
* 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.
* MCP uç noktası URL'sine makinenizden erişilebildiğini doğrulayın. Öz barındırmalı kurulumlar için, sunucunun çalıştığını ve `SERVER_URL` değerinin doğru ayarlandığını kontrol edin.

114
packages/twenty-docs/l/zh/user-guide/ai/capabilities/mcp.mdx
View File

@@ -7,28 +7,28 @@ description: 使用 Model Context Protocol 将 AI 助手连接到你的 Twenty
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.
Twenty 提供一个 [MCP](https://modelcontextprotocol.io/) 服务器，使 AI 助手——Claude Desktop、Claude Code、Cursor、ChatGPT 等——能够通过自然语言读取和写入您的 CRM 数据。
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:
将您的**工作区 URL**（用于访问 Twenty 的 URL）用作 MCP 端点。 在 Twenty Cloud 上，您的工作区 URL 可能是 `https://{mycompany}.twenty.com`，也可能是自定义域名。 服务器可通过以下地址访问：
| 环境 | MCP Endpoint |
| ------- | ---------------------------------------------------------------------------- |
| **云端** | `https://{your-workspace-url}/mcp` (e.g. `https://mycompany.twenty.com/mcp`) |
| **自托管** | `https://{your-domain}/mcp` |
| 环境 | MCP 端点 |
| ------- | -------------------------------------------------------------------------- |
| **云端** | `https://{your-workspace-url}/mcp` (例如 `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**.
您可以通过两种方式对 MCP 客户端进行身份验证：**OAuth**（推荐）或 **API 密钥**。
### Option A — OAuth (Recommended)
### 选项 A — OAuth（推荐）
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 时，您的 MCP 客户端会打开浏览器窗口供您登录。 不会在配置文件中存储任何机密，令牌会自动刷新。
<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.
OAuth 需要支持[MCP 授权规范](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)的 MCP 客户端。 Claude Desktop、Claude Code、Cursor 和 ChatGPT 均支持它。
</Note>
Add this to your MCP client configuration, replacing `{your-workspace-url}` with your workspace host (e.g. `mycompany.twenty.com`):
将以下内容添加到 MCP 客户端配置中，并将 `{your-workspace-url}` 替换为您的工作区主机（例如 `mycompany.twenty.com`）：
```json
{
@@ -41,18 +41,18 @@ Add this to your MCP client configuration, replacing `{your-workspace-url}` with
}
```
That's it — no API key needed. When the client connects for the first time it will:
就这样——无需 API 密钥。 客户端首次连接时将：
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
1. 通过 `/.well-known/oauth-protected-resource` 和 `/.well-known/oauth-authorization-server` 发现 Twenty 的 OAuth 元数据
2. 通过动态客户端注册（RFC 7591）将自身注册为 OAuth 客户端
3. 打开您的浏览器以授权访问
4. 接收令牌并连接到 MCP 服务器
Subsequent connections reuse the stored tokens and refresh them automatically.
后续连接会重用已存储的令牌并自动刷新。
### Option B — API Key
### 选项 B — API 密钥
If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the `Authorization` header:
如果您的 MCP 客户端不支持 OAuth，或您更喜欢静态凭据，请在 `Authorization` 请求头中传递 API 密钥：
```json
{
@@ -69,74 +69,74 @@ If your MCP client does not support OAuth, or you prefer static credentials, pas
```
<Warning>
Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
您的 API 密钥可访问工作区数据。 请不要将其纳入版本控制，也不要放入共享的 dotfiles。
</Warning>
To create an API key, go to **Settings > APIs & Webhooks > + Create key**. See [APIs](/l/zh/developers/extend/api) for details.
要创建 API 密钥，请前往 **Settings > APIs & Webhooks > + Create key**。 详见[API](/l/zh/developers/extend/api#create-an-api-key)。
## Quick Start
## 快速开始
### 1. Copy the config
### 1. 复制配置
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.
在 Twenty 中前往 **Settings > AI > More > MCP Server**。 选择您的身份验证方式（OAuth 或 API 密钥），复制 JSON 片段（其中已包含您的工作区 URL），并将其粘贴到 MCP 客户端的配置文件中。
| 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 |
| 客户端 | 配置文件位置 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **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** 中开启开发者模式，然后在 **Settings > Apps & Connectors** 中使用 **Create** 添加 MCP 服务器 |
### 2. Connect
### 2. 连接
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.
重启您的 MCP 客户端（或重新加载配置）。 如果使用 OAuth，您将被重定向到 Twenty 以授权访问。 如果使用 API 密钥，连接会立即建立。
### 3. Start using it
### 3. 开始使用
Ask your AI assistant to interact with your CRM:
让您的 AI 助手与您的 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"*
* *"给我展示最近创建的 5 家公司"*
* *"在 Acme Corp 新建一位名为 Jane Doe 的联系人"*
* *"查找所有价值超过 $10k 的未关闭商机"*
## Available Tools
## 可用工具
Once connected, the MCP server exposes tools that mirror the Twenty API. The recommended workflow is:
连接后，MCP 服务器会提供与 Twenty API 一一对应的工具。 推荐的工作流程是：
1. **`get_tool_catalog`** — discover all available tools
2. **`learn_tools`** — get the input schema for specific tools
3. **`execute_tool`** — run a tool
1. **`get_tool_catalog`** — 发现所有可用工具
2. **`learn_tools`** — 获取特定工具的输入模式
3. **`execute_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.
您无需记住工具名称。 询问您的 AI 助手它能做什么，它会自动调用 `get_tool_catalog`。
## 权限
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:
MCP 连接将继承已通过身份验证的用户（OAuth）的权限，或继承分配给 API 密钥的角色。 要限制 MCP 服务器的操作范围：
* **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).
* **OAuth**：生效的是该用户在工作区中的角色。
* **API 密钥**：在 **Settings > Roles** 下为该 API 密钥分配角色。 参见[权限](/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.
对于自托管实例，请将 `{your-workspace-url}` 替换为您的服务器 URL。 请确保您环境中的 `SERVER_URL` 与 Twenty 实例的公共 URL 一致——该值用于生成 OAuth 发现元数据。
```bash
SERVER_URL=https://twenty.yourcompany.com
```
The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.
MCP 端点、OAuth 端点以及发现元数据都基于该值生成。
## 故障排除
**"Unauthorized" or 401 errors**
**"Unauthorized" 或 401 错误**
* 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：清除 MCP 客户端中存储的令牌并重新连接以重新授权。
* API 密钥：验证该密钥有效且未过期。 如有需要，请重新生成。
**OAuth flow doesn't open a browser**
**OAuth 流程未打开浏览器**
* Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn't.
* 确保您的 MCP 客户端支持 MCP 授权。 如果不支持，请改用 API 密钥方法。
**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.
* 确认从您的机器可以访问 MCP 端点 URL。 对于自托管实例，请检查服务器是否正在运行，并确认 `SERVER_URL` 设置正确。