Skip to main content

​
Обзор

Twenty предоставляет сервер MCP, чтобы ИИ-ассистенты — Claude Desktop, Claude Code, Cursor, ChatGPT и другие — могли читать и записывать ваши данные CRM на естественном языке. Используйте URL рабочей области (URL, который вы используете для доступа к Twenty) в качестве конечной точки MCP. В Twenty Cloud URL вашей рабочей области может быть https://{mycompany}.twenty.com или собственный домен. Сервер доступен по адресу:

​
Методы аутентификации

Есть два способа аутентифицировать ваш MCP-клиент: OAuth (рекомендуется) или API Key.

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

При использовании OAuth ваш MCP-клиент откроет окно браузера для входа в систему. Секреты не хранятся в файлах конфигурации, а токены обновляются автоматически.
Для OAuth требуется MCP-клиент, поддерживающий спецификацию авторизации MCP. Её поддерживают Claude Desktop, Claude Code, Cursor и ChatGPT.
Добавьте это в конфигурацию вашего MCP-клиента, заменив {your-workspace-url} на хост вашей рабочей области (например, mycompany.twenty.com):
Вот и всё — ключ 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:
Ваш ключ API предоставляет доступ к данным рабочей области. Не храните его в системе контроля версий и общих dotfiles.
Чтобы создать ключ API, перейдите в Settings → Developers → API → + Create key. См. API для подробностей.

​
Быстрый старт

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

Перейдите в Settings → AI → MCP в Twenty. Выберите метод аутентификации (OAuth или ключ API), скопируйте фрагмент JSON (в нём уже будет использован URL вашей рабочей области) и вставьте его в файл конфигурации вашего 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. См. Разрешения.

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

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

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

Ошибки “Unauthorized” или 401
  • OAuth: повторно авторизуйтесь, очистив сохранённые токены в вашем MCP-клиенте и переподключившись.
  • API Key: убедитесь, что ключ действителен и не истёк. При необходимости сгенерируйте его заново.
Процесс OAuth не открывает браузер
  • Убедитесь, что ваш MCP-клиент поддерживает MCP Authorization. Если нет — используйте метод с ключом API.
Тайм-аут подключения
  • Убедитесь, что URL конечной точки MCP доступен с вашего компьютера. Для экземпляров с самостоятельным хостингом проверьте, что сервер запущен и значение SERVER_URL установлено корректно.