> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Сервер MCP

> Подключайте ИИ-ассистентов к вашему рабочему пространству Twenty с помощью протокола Model Context Protocol.

## Обзор

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 Key**.

### Вариант A — OAuth (рекомендуется)

При использовании OAuth ваш MCP-клиент откроет окно браузера для входа в систему. Секреты не хранятся в файлах конфигурации, а токены обновляются автоматически.

> [!NOTE]
>
> Для 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 theme={null}
{
  "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

При последующих подключениях используются сохранённые токены, которые автоматически обновляются.

### Вариант B — ключ API

Если ваш MCP-клиент не поддерживает OAuth или вы предпочитаете статические учётные данные, передайте ключ API в заголовке `Authorization`:

```json theme={null}
{
  "mcpServers": {
    "twenty": {
      "type": "streamable-http",
      "url": "https://{your-workspace-url}/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

> [!WARNING]
>
> Ваш ключ API предоставляет доступ к данным рабочей области. Не храните его в системе контроля версий и общих dotfiles.

Чтобы создать ключ API, перейдите в **Settings → Developers → API → + Create key**. См. [API](https://docs.twenty.com/ru/developers/extend/api.md#create-an-api-key) для подробностей.

## Быстрый старт

### 1. Скопируйте конфигурацию

Перейдите в **Settings → AI → MCP** в 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. |

### 2. Подключение

Перезапустите ваш MCP-клиент (или перезагрузите конфигурацию). Если используется OAuth, вы будете перенаправлены в Twenty для авторизации доступа. Если используется ключ API, подключение произойдёт сразу.

### 3. Начните использовать

Попросите вашего ИИ-ассистента взаимодействовать с вашей CRM:

* *"Покажи мне 5 последних созданных компаний"*
* *"Создай новый контакт по имени Jane Doe в компании Acme Corp"*
* *"Найди все открытые сделки стоимостью более \$10 000"*

## Доступные инструменты

После подключения сервер MCP предоставляет инструменты, отражающие API Twenty. Рекомендуемый рабочий процесс:

1. **`learn_tools`** — получить схему входных данных для конкретных инструментов
2. **`execute_tool`** — запустить инструмент

Вам не нужно запоминать названия инструментов. Спросите у вашего ИИ-ассистента, что он умеет, и он автоматически вызовет `learn_tools`.

Имена операций с записями следуют грамматике, поэтому ассистент может формировать их без вызова для обнаружения: `find_many_companies`, `find_one_person`, `update_one_opportunity`. Если имя указано неверно, `learn_tools` сообщает о нем в `notFound` вместе с наиболее близкими совпадающими именами.

Для всего остального `get_tool_catalog` просматривает оставшиеся инструменты по одной категории за раз. Это запасной вариант: нефильтрованный вызов возвращает сотни операций, и большинство ассистентов сократят ответ.

`/mcp?mode=direct` напрямую перечисляет каждый инструмент и требует клиента, который загружает инструменты по запросу.

## Разрешения

Подключения MCP наследуют разрешения аутентифицированного пользователя (OAuth) или роль, назначенную ключу API. Чтобы ограничить действия, доступные серверу MCP:

* **OAuth**: Применяется роль пользователя в рабочей области.
* **API Key**: Назначьте ключу API роль в **Settings → Members → Roles**. См. [Разрешения](https://docs.twenty.com/ru/user-guide/permissions-access/capabilities/permissions.md).

## Конфигурация для самостоятельного хостинга

Для экземпляров с самостоятельным хостингом замените `{your-workspace-url}` на URL вашего сервера. Убедитесь, что значение `SERVER_URL` в вашей среде соответствует публичному URL экземпляра Twenty — оно используется для генерации метаданных обнаружения OAuth.

```bash theme={null}
SERVER_URL=https://twenty.yourcompany.com
```

Конечная точка MCP, конечные точки OAuth и метаданные обнаружения формируются на основе этого значения.

## Устранение неполадок

**Ошибки "Unauthorized" или 401**

* OAuth: повторно авторизуйтесь, очистив сохранённые токены в вашем MCP-клиенте и переподключившись.
* API Key: убедитесь, что ключ действителен и не истёк. При необходимости сгенерируйте его заново.

**Процесс OAuth не открывает браузер**

* Убедитесь, что ваш MCP-клиент поддерживает MCP Authorization. Если нет — используйте метод с ключом API.

**Тайм-аут подключения**

* Убедитесь, что URL конечной точки MCP доступен с вашего компьютера. Для экземпляров с самостоятельным хостингом проверьте, что сервер запущен и значение `SERVER_URL` установлено корректно.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.