upstream-twenty/packages/twenty-docs/l/ru/user-guide/ai/capabilities/mcp.mdx

---
title: Сервер MCP
description: Подключайте ИИ-ассистентов к вашему рабочему пространству 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.
</Note>

Добавьте это в конфигурацию вашего 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"
      }
    }
  }
}
```

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

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

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

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

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

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

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

* **OAuth**: Применяется роль пользователя в рабочей области.
* **API Key**: Назначьте ключу API роль в **Settings → Members → 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` установлено корректно.