---
title: Сервер MCP
description: Подключайте ИИ-ассистентов к вашему рабочему пространству Twenty с помощью протокола Model Context Protocol.
---
В настоящее время MCP находится на стадии **alpha** и доступен только в некоторых рабочих пространствах. В вашем рабочем пространстве он может быть ещё не включён.
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-клиент откроет окно браузера для входа в систему. Секреты не хранятся в файлах конфигурации, а токены обновляются автоматически.
Для 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
При последующих подключениях используются сохранённые токены, которые автоматически обновляются.
### Вариант B — ключ 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**. См. [API](/l/ru/developers/extend/api#create-an-api-key) для подробностей.
## Быстрый старт
### 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 |
### 2. Подключение
Перезапустите ваш MCP-клиент (или перезагрузите конфигурацию). Если используется OAuth, вы будете перенаправлены в Twenty для авторизации доступа. Если используется ключ API, подключение произойдёт сразу.
### 3. Начните использовать
Попросите вашего ИИ-ассистента взаимодействовать с вашей CRM:
* *"Покажи мне 5 последних созданных компаний"*
* *"Создай новый контакт по имени Jane Doe в компании Acme Corp"*
* *"Найди все открытые сделки стоимостью более $10 000"*
## Доступные инструменты
После подключения сервер MCP предоставляет инструменты, отражающие API Twenty. Рекомендуемый рабочий процесс:
1. **`get_tool_catalog`** — получить список всех доступных инструментов
2. **`learn_tools`** — получить схему входных данных для конкретных инструментов
3. **`execute_tool`** — запустить инструмент
Вам не нужно запоминать названия инструментов. Спросите у вашего ИИ-ассистента, что он умеет, и он автоматически вызовет `get_tool_catalog`.
## Разрешения
Подключения MCP наследуют разрешения аутентифицированного пользователя (OAuth) или роль, назначенную ключу API. Чтобы ограничить действия, доступные серверу MCP:
* **OAuth**: Применяется роль пользователя в рабочей области.
* **API Key**: Назначьте ключу API роль в **Settings > Roles**. См. [Разрешения](/l/ru/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 Authorization. Если нет — используйте метод с ключом API.
**Тайм-аут подключения**
* Убедитесь, что URL конечной точки MCP доступен с вашего компьютера. Для экземпляров с самостоятельным хостингом проверьте, что сервер запущен и значение `SERVER_URL` установлено корректно.