github-actions[bot]
ddedecbb36
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
143 lines
10 KiB
Plaintext
143 lines
10 KiB
Plaintext
---
|
||
title: Сервер MCP
|
||
description: Подключайте ИИ-ассистентов к вашему рабочему пространству Twenty с помощью протокола Model Context Protocol.
|
||
---
|
||
|
||
<Warning>
|
||
В настоящее время MCP находится на стадии **alpha** и доступен только в некоторых рабочих пространствах. В вашем рабочем пространстве он может быть ещё не включён.
|
||
</Warning>
|
||
|
||
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 > 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` установлено корректно.
|