РазделИнструменты для ИИ

Инструменты для ИИ

Какие действия в Syncra доступны подключённому ИИ-приложению: все группы инструментов и общие правила для ссылок, дат, удаления и постраничного чтения.

Инструмент — это одно действие, которое подключённое ИИ-приложение выполняет в Syncra: прочитать канал, отправить сообщение, создать задачу, найти страницу. Приложение вызывает инструменты по MCP (Model Context Protocol) — открытому стандарту, по которому ИИ-приложения работают с внешними сервисами. Сейчас сервер Syncra отдаёт 193 инструмента. Каждый вызов выполняется от имени человека, который подключил приложение, и с его правами. Пользоваться инструментами может любой участник рабочего пространства, который подключил приложение по инструкции Подключить свой ИИ. Инструменты, которые управляют ботами, участниками и настройками рабочего пространства, работают только у владельца и администратора.

Как вызвать инструмент

Claude, ChatGPT и Cursor вызывают инструменты сами. Если вы пишете свою программу, которая подключается к Syncra, все вызовы идут на один адрес.

POST /api/mcp

Принимает один запрос в формате JSON-RPC 2.0: список инструментов или вызов инструмента.

Параметр Тип Обязателен Описание
jsonrpc строка да Всегда "2.0"
id число или строка да Ваш номер запроса, вернётся в ответе
method строка да tools/list — получить список инструментов, tools/call — вызвать инструмент
params.name строка для tools/call Имя инструмента, например list_tasks
params.arguments объект для tools/call Параметры инструмента. Их описание приходит в ответе tools/list

Заголовки: Authorization: Bearer syncat_..., Content-Type: application/json и Accept: application/json, text/event-stream.

curl -X POST "https://ai-syncra.ru/api/mcp" \
  -H "Authorization: Bearer syncat_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tasks","arguments":{"projectId":"<id проекта>","limit":50,"offset":0}}}'

Ответ 200:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "..." }
    ]
  }
}

В поле text лежит ответ Syncra в виде строки с JSON. Её нужно разобрать ещё раз.

Если инструмент не сработал, код ответа тоже 200, а в результате стоит признак isError и текст ошибки:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "Error: HTTP 403: This module is turned off in this workspace (GET /api/wiki/pages/<id>)" }
    ],
    "isError": true
  }
}

В примере база знаний выключена в рабочем пространстве. Когда Syncra отказывает в действии, текст собран так: слово Error:, код HTTP, сообщение, а в скобках запрос, который не прошёл.

Актуальный список инструментов и их параметров всегда отдаёт tools/list. Таблицы ниже объясняют, что есть в каждой группе.

Общие правила

Ссылки на объекты

Инструмент принимает либо внутренний идентификатор, либо короткую ссылку вида КЛЮЧ-номер, например SYN-298. Такую ссылку человек видит в Syncra у задачи.

  • Короткие ссылки есть у задач, эпиков, страниц базы знаний, встреч, сделок, контактов и компаний.
  • Три ключа общие для всего рабочего пространства, а не для одного проекта: EVT — встречи, CNT — контакты, CMP — компании.
  • Задача, которую перенесли в другой проект, откликается и на старую ссылку.
  • Инструмент resolve_ref находит объект по ссылке или идентификатору.
  • Рабочее пространство указывают параметром workspaceSlug: это короткое имя пространства из его адреса.
  • По названию объект выбрать нельзя. Сначала поиск, например search_workspace или search_tasks, затем действие по идентификатору или ссылке из ответа.

Даты и время

Даты читаются в часовом поясе человека, от имени которого работает приложение.

  • Дата без времени, 2026-11-20, — это полночь этого дня по времени человека.
  • Дата со временем без смещения, 2026-11-20T15:00, — это 15:00 на часах человека.
  • Только явное смещение или Z означает точный момент: 2026-11-20T15:00:00+03:00.
  • В фильтрах по периоду (from и to, dateFrom и dateTo) дата без времени в конце периода включает весь этот день.

Пустое значение ничего не стирает

Пустая строка или пробелы в необязательном текстовом поле считаются так, будто поле не передали. Так Syncra защищает данные: ИИ-модель часто подставляет пустую строку в поля, которые не собиралась менять.

  • Чтобы оставить поле как есть, не передавайте его.
  • Чтобы очистить поле, передайте слово none. Подходят также clear, нет, очисти и очистить. Так очищаются не все поля, а только эти: описание, сроки, эпик и исполнитель задачи; описание, заметка о статусе, сроки и ответственные эпика; сумма, дата закрытия, ответственный и компания сделки; описание встречи. У таких полей в описании из tools/list сказано, что их очищает none.

Удаление с подтверждением

Восемь инструментов удаляют данные и требуют обязательный параметр confirmed: delete_workspace, delete_project, delete_epic, delete_task, delete_label, delete_wiki_page, destroy_wiki_page и delete_bot.

При confirmed: false ничего не удаляется. Инструмент возвращает объект с полем "needsConfirmation": true и описанием того, что будет удалено. Приложение должно спросить человека и вызвать инструмент ещё раз с confirmed: true.

Постраничное чтение

Списки листаются по-разному, вариантов три.

Вариант Как листать Инструменты
Смещение и размер страницы offset и limit. В ответе есть общее число записей или признак, что записи ещё остались list_tasks (до 500 на страницу), list_bookmarks (до 200), list_deals, list_contacts, list_companies (до 100, по умолчанию 50), list_meeting_notes (до 100, по умолчанию 20), get_meeting_transcript (до 500, по умолчанию 100), list_wiki_page_comments (до 200, по умолчанию 50), list_wiki_favorites, list_wiki_recents, list_wiki_shared (до 200), get_transcript (segmentLimit до 2000 и segmentOffset)
Курсор limit и метка последней записи с предыдущей страницы get_channel_messages (cursor), get_thread_replies (after), get_user_activity, get_task_activity, get_workspace_activity (before)
Без страниц Возвращают всё сразу или первые результаты search_tasks (до 100, по умолчанию 20), search_workspace, list_wiki_pages, list_projects, list_channels и другие короткие списки

Файлы

send_message и create_task_comment принимают параметр files: до 10 файлов, каждый — объект с полями name (от 1 до 255 символов), content (до 5 000 000 символов) и encoding (utf8 или base64).

Путь к файлу на компьютере передать нельзя: сервер работает не на вашей машине. Поэтому инструмент upload_task_attachment и параметр attachmentPaths через этот адрес не работают.

Длина текста

Поле Предел
Текст сообщения 4000 символов
Название задачи 300 символов
Описание задачи 10 000 символов
Название страницы базы знаний 300 символов

Группы инструментов

Аккаунт и профиль

Инструмент Что делает
get_current_user Профиль человека, от имени которого работает приложение
get_current_auth_user То же самое под другим именем: кто сейчас подключён
update_current_user Меняет имя, описание и аватар в своём профиле
get_user_profile Профиль другого участника: имя, почта, часовой пояс, описание
get_user Короткие сведения об участнике по идентификатору
get_user_activity Что участник сделал в рабочем пространстве: события задач, комментарии, правки страниц. Сначала новое

В списке есть ещё четыре служебных инструмента для страницы входа: get_auth_config, forgot_password, reset_password и resend_verification_email. Подключённому приложению они не нужны.

Рабочие пространства и участники

Инструмент Что делает
list_workspaces Рабочие пространства, в которых состоит человек
create_workspace Создаёт рабочее пространство с каналом #general
get_workspace Рабочее пространство по workspaceSlug и роль человека в нём
update_workspace Меняет название, адрес, язык или значок. Только владелец и администратор
delete_workspace Удаляет рабочее пространство целиком. Только владелец, нужен confirmed
list_workspace_members Участники с ролями, статусом и признаком «в сети»
add_workspace_member Добавляет человека с выбранной ролью. Только владелец и администратор
update_workspace_member Меняет роль или команду участника. Только владелец и администратор
remove_workspace_member Исключает участника. Только владелец и администратор
leave_workspace Выходит из рабочего пространства. Единственный владелец выйти не может
set_workspace_status Ставит свой статус: эмодзи, текст, срок действия, пауза уведомлений
clear_workspace_status Убирает свой статус
get_workspace_presence Кто из участников сейчас в сети
send_presence_heartbeat Обновляет собственную отметку «в сети»
get_workspace_member_count Число участников
get_workspace_unread_counts Число непрочитанных сообщений и упоминаний по каналам
get_workspace_activity Личная лента человека: упоминания, реакции, уведомления

Каналы и личные сообщения

Инструмент Что делает
list_channels Каналы, в которых состоит человек
browse_channels Открытые каналы рабочего пространства: можно посмотреть и вступить
create_channel Создаёт открытый или закрытый канал
update_channel Меняет название, описание и тему, архивирует, переводит из открытого в закрытый и обратно
list_channel_members Участники канала
join_channel Вступает в открытый канал или добавляет в канал другого участника
leave_channel Выходит из канала. Из личной переписки выйти нельзя
remove_channel_member Убирает участника из канала. Нужны права администратора канала или рабочего пространства
update_channel_member Назначает или снимает администратора канала
list_dms Личные и групповые переписки, сначала свежие
open_dm Открывает личную переписку с участником или находит уже существующую
create_group_dm Создаёт групповую переписку: человек и ещё от 2 до 7 участников

Сообщения

Инструмент Что делает
get_channel_messages Сообщения канала, по страницам
get_message Одно сообщение по идентификатору
send_message Отправляет сообщение в канал или ответ в тред, с упоминаниями и файлами
edit_message Правит текст своего сообщения
delete_message Удаляет сообщение. Может автор или администратор рабочего пространства
forward_message Пересылает сообщение в другой канал с комментарием
add_reaction Ставит реакцию-эмодзи
remove_reaction Снимает свою реакцию
pin_message Закрепляет сообщение в канале. Нужны права администратора канала или рабочего пространства
unpin_message Открепляет сообщение
get_pinned_messages Закреплённые сообщения канала
bookmark_message Добавляет сообщение в сохранённые
unbookmark_message Убирает сообщение из сохранённых
list_bookmarks Сохранённые сообщения человека
mark_channel_read Отмечает канал прочитанным до сообщения, которое человеку показали
mark_mention_read Отмечает прочитанным упоминание человека в сообщении
send_typing_indicator Показывает или убирает в канале признак «печатает»
complete_message_action Выполняет действие, предложенное под сообщением: создать задачу, сохранить в базу знаний, запомнить или записать решение
dismiss_message_action Скрывает предложенное действие у всех

Отправка сообщения ничего не отмечает прочитанным. Непрочитанное у человека остаётся непрочитанным, пока он сам его не увидит.

Треды

Инструмент Что делает
get_thread_replies Ответы в треде, по страницам
post_thread_reply Отвечает в тред. Ответ можно продублировать в канал
get_thread_summary Сведения о треде: число ответов, время последнего, участники
subscribe_thread Подписывает человека на тред
unsubscribe_thread Отписывает от треда

Сообщение, с которого начался тред, передают параметром rootId или threadRootId. Нужен один из двух.

Проекты и колонки

Инструмент Что делает
list_projects Проекты рабочего пространства
get_project Проект с его колонками и пространством базы знаний
create_project Создаёт проект с колонками по умолчанию и своим пространством базы знаний
update_project Меняет название, описание, цвет, значок, вид по умолчанию, указания для ИИ. Архивирует проект
delete_project Удаляет проект. Может создатель проекта или администратор, нужен confirmed
create_project_section Добавляет колонку в конец
update_project_section Переименовывает или переставляет колонку
delete_project_section Удаляет колонку. Её задачи остаются без колонки
list_project_members Кто исключён из проекта
toggle_project_member_exclusion Исключает участника из проекта или возвращает его. Только владелец и администратор

Эпики

Инструмент Что делает
list_epics Эпики проекта и ход работы по каждому
create_epic Создаёт эпик: название, описание, цвет, ответственные, сроки
update_epic Меняет поля эпика
delete_epic Удаляет эпик. Задачи остаются. Нужен confirmed

Задачи

Инструмент Что делает
list_tasks Задачи проекта, по страницам
get_task Задача целиком: подзадачи, метки, подписчики
get_my_tasks Задачи человека, разложенные по срокам: просрочено, сегодня, впереди, без срока, выполнено
search_tasks Поиск по названиям и описаниям задач
resolve_ref Находит объект по короткой ссылке или идентификатору
create_task Создаёт задачу: достаточно названия, остальные поля по желанию
update_task Меняет название, описание, приоритет, сроки, эпик, исполнителя
complete_task Отмечает задачу выполненной или возвращает в работу
move_task Переносит задачу в другую колонку или меняет её место в колонке
delete_task Удаляет задачу. Может создатель, исполнитель или администратор, нужен confirmed
restore_task Восстанавливает удалённую задачу
follow_task Подписывает человека на изменения задачи
unfollow_task Отписывает от изменений задачи
link_subtask Делает существующую задачу подзадачей другой
unlink_subtask Отвязывает подзадачу, она снова самостоятельная
get_task_source Откуда появилась задача: сообщение в чате или итоги созвона
get_task_activity История задачи: кто, что и когда менял
list_task_revisions Прежние версии названия, описания, приоритета и срока
restore_task_revision Возвращает задачу к выбранной версии

Комментарии, вложения и метки задач

Инструмент Что делает
list_task_comments Комментарии к задаче по порядку
create_task_comment Пишет комментарий, с упоминаниями и файлами
update_task_comment Правит свой комментарий
delete_task_comment Удаляет свой комментарий
list_task_attachments Вложения задачи
add_task_attachment Прикрепляет к задаче уже загруженный файл
upload_task_attachment Загружает файл по пути на компьютере. Через адрес сервера не работает
delete_task_attachment Убирает вложение
list_labels Метки рабочего пространства
create_label Создаёт метку. Если метка с таким названием есть, возвращает её
delete_label Удаляет метку и снимает её со всех задач. Нужен confirmed
add_task_label Ставит метку на задачу
remove_task_label Снимает метку с задачи

База знаний

В именах инструментов база знаний называется wiki. Страницы лежат в пространствах: пространство базы знаний — это раздел со страницами одного проекта. Не путайте его с рабочим пространством.

Инструмент Что делает
list_wiki_spaces Пространства базы знаний в рабочем пространстве
get_wiki_space Одно пространство
update_wiki_space Меняет название, описание и значок пространства
get_wiki_space_tree Дерево страниц пространства с уровнями вложенности
list_wiki_pages Страницы пространства: только названия и служебные данные, без текста
get_wiki_page Страница с текстом. С metadataOnly — без текста
create_wiki_page Создаёт страницу, в том числе из шаблона
update_wiki_page Меняет текст и свойства страницы. expectedRevision защищает от записи поверх чужой правки
move_wiki_page Переносит страницу вместе с вложенными: под другую страницу, на другое место или в другое пространство
duplicate_wiki_page Создаёт копию страницы рядом с ней
delete_wiki_page Отправляет страницу в корзину, откуда её можно вернуть. Нужен confirmed
list_wiki_trash Страницы в корзине пространства
restore_wiki_page Возвращает страницу из корзины
destroy_wiki_page Удаляет страницу навсегда вместе с вложенными и их версиями. Нужен confirmed
export_wiki_page Выгружает страницу в Markdown
list_wiki_page_comments Обсуждения на странице, по страницам
list_wiki_page_revisions Список версий страницы, без текста
get_wiki_page_revision Одна версия страницы с текстом
restore_wiki_page_revision Возвращает страницу к выбранной версии
get_wiki_page_backlinks Страницы, которые ссылаются на эту
favorite_wiki_page Добавляет страницу в избранное человека
unfavorite_wiki_page Убирает страницу из избранного
list_wiki_favorites Избранные страницы человека
list_wiki_recents Страницы, которые человек недавно открывал
list_wiki_shared Страницы, опубликованные по открытой ссылке
list_wiki_templates Шаблоны страниц
save_wiki_page_as_template Сохраняет страницу как шаблон

Встречи в календаре

Инструмент Что делает
list_meetings Встречи за период, с фильтром по участнику и каналу
get_meeting Встреча с участниками и их ответами на приглашение
create_meeting Назначает встречу: название, начало, конец, канал, участники
update_meeting Меняет название, описание, время и состав участников
cancel_meeting Отменяет встречу. Может организатор или администратор

У повторяющейся встречи параметр scope говорит, что менять: single — только эту, following — эту и следующие, series — всю серию.

Записанные встречи (Syncra Notes)

Syncra Notes — это записанные или загруженные встречи, у которых уже есть расшифровка и итоги.

Инструмент Что делает
list_meeting_notes Записанные встречи, которые человек может читать. Есть поиск и фильтр по датам
get_meeting_notes Итоги одной встречи: краткое содержание, решения, договорённости с ответственными и сроками
get_meeting_transcript Расшифровка встречи, по страницам

Эти инструменты принимают идентификатор из ответа list_meeting_notes. Короткая ссылка вида EVT-12 относится к встрече в календаре и сюда не подходит.

CRM

CRM — учёт продаж в Syncra: сделки на доске проекта, контакты и компании.

Инструмент Что делает
list_deals Сделки на доске проекта, с фильтрами по статусу, этапу, ответственному и компании
get_deal Сделка с контактами, связанными встречами и причиной проигрыша
create_deal Создаёт сделку и возвращает её короткую ссылку
update_deal Меняет название, сумму, ожидаемую дату закрытия, ответственного и компанию
move_deal_stage Переносит открытую сделку на другой этап
close_deal Закрывает сделку как выигранную или проигранную
reopen_deal Возвращает закрытую сделку на доску
list_lost_reasons Справочник причин проигрыша
list_contacts Контакты: люди
create_contact Создаёт контакт
list_companies Компании
create_company Создаёт компанию

Поиск

Инструмент Что делает
search_workspace Ищет по сообщениям, страницам базы знаний, задачам, комментариям, людям и созвонам. Есть фильтры по типу, каналу, автору и датам
search_wiki_space Ищет по страницам одного пространства базы знаний
prioritize_inbox Расставляет записи личной ленты по срочности с помощью ИИ: высокая, обычная, низкая

Боты

Управлять ботами могут только владелец и администратор рабочего пространства. Список ботов и список слеш-команд доступен любому участнику. Что такое бот, описано на странице Боты.

Инструмент Что делает
list_bots Боты рабочего пространства, без секретов
get_bot Бот целиком: системный промпт и каналы, в которых он состоит
create_bot Создаёт бота
update_bot Меняет профиль и настройки бота, включает и выключает его
delete_bot Удаляет бота со всеми его ключами, вебхуками, подписками и командами. Нужен confirmed
list_bot_tokens Ключи бота, включая отозванные
create_bot_token Создаёт ключ бота. Полное значение приходит один раз
revoke_bot_token Отзывает ключ
list_bot_webhooks Входящие вебхуки бота
create_bot_webhook Создаёт входящий вебхук для канала. Бот сам вступает в этот канал
delete_bot_webhook Удаляет входящий вебхук
list_bot_subscriptions Подписки бота на события, с секретами подписи
create_bot_subscription Создаёт подписку: адрес и список событий
update_bot_subscription Меняет адрес и события подписки, включает и выключает её
delete_bot_subscription Удаляет подписку и её журнал отправок
test_bot_subscription Отправляет на адрес подписки тестовое событие с подписью
list_bot_deliveries Последние отправки событий
list_bot_task_runs 20 последних запусков исполнителя задач
list_bot_commands Слеш-команды бота, с секретами подписи
create_bot_command Регистрирует слеш-команду
update_bot_command Меняет название, описание и адрес команды, включает и выключает её
delete_bot_command Удаляет слеш-команду
list_workspace_commands Все включённые слеш-команды рабочего пространства
invoke_slash_command Вызывает слеш-команду в канале, где состоит человек

Созвоны и расшифровки

Инструмент Что делает
get_call_status Идёт ли созвон в канале и кто в нём
get_incoming_call Входящий звонок человеку, если он есть
start_call Создаёт в канале карточку начатого созвона
end_call Отмечает созвон завершённым, если в нём не осталось людей. После этого готовятся итоги
ring_call Звонит собеседникам в личной или групповой переписке
invite_to_call Зовёт участников в идущий созвон
cancel_call Отменяет свой звонок, пока на него не ответили
decline_call Отклоняет входящий звонок
get_call_token Выдаёт ключ для входа в комнату созвона
get_transcript Расшифровка созвона по идентификатору, по страницам

Что закрыто для подключённого приложения

  • Адреса Syncra, которые требуют входа и начинаются с /auth/, /api/auth/ (вход в аккаунт), /api/oauth/ (выдача доступа приложениям) или /api/_internal/ (служебная панель команды Syncra). Запрос к ним возвращает 403 с кодом mcp_forbidden.
  • Части продукта, выключенные в рабочем пространстве. Если задачи, база знаний или CRM выключены, их инструменты возвращают 403 с кодом module_disabled.
  • Файлы на компьютере человека. Сервер не читает пути к файлам, содержимое передают в параметре files.
  • Всё, чего не видит сам человек: закрытые каналы, в которых его нет, и чужие личные переписки.

Отказ приходит как ошибка инструмента в том же виде, что в примере выше: признак isError и текст с кодом HTTP.