REST API и MCP-сервер для интеграций и ИИ-агентов: выгружайте задачи и учёт времени в 1С и BI, создавайте задачи из CRM и с сайта, подключайте Klepps к Cursor и Claude, читайте документацию и транскрипты встреч из своих систем.
Klepps подключается к ИИ-агентам (Cursor, Claude, VS Code и другие) как MCP-сервер: https://klepps.ru/api/mcp, транспорт Streamable HTTP, вход — тем же ключом API в заголовке Authorization. Агент видит только инструменты, на которые у ключа есть права, и действует от имени пользователя ключа — как через REST API. MCP доступен на тарифе «Бизнес».
Любая нейросеть — ваш агентKlepps не привязан к одной модели: Claude, GPT, Gemini, DeepSeek, Qwen, Kimi и другие работают с ним одинаково. Подойдёт любой клиент, который подключает MCP-сервер по адресу (Streamable HTTP) с заголовком: Cursor, Claude Code, VS Code, Cline и другие. Если клиент умеет запускать MCP только командой — через мост: npx mcp-remote https://klepps.ru/api/mcp --header "Authorization: Bearer klp_…".
Например, в Cursor: «возьми WEB-42 и сделай» — агент прочитает задачу вместе с ТЗ из документации и договорённостями со встреч, перенесёт её «В работу», напишет код, спишет время, опишет в комментарии, что сделал, и переведёт задачу в «Готово». Коллеги видят это сразу, как будто работал человек.
Подключение
В Klepps откройте «API» и нажмите «Ключ для агента» — права подобраны для работы с задачами, временем и документами.
В окне с ключом выберите вкладку «ИИ-агент (MCP)»: для Cursor есть кнопка «Добавить в Cursor», для остальных — готовая настройка.
Файл .cursor/mcp.json в проекте или ~/.cursor/mcp.json — для всех проектов. Проще всего — кнопка «Добавить в Cursor» после создания ключа в Klepps.
Пользователь ключа, компания и права ключа. Вызовите первым, чтобы понять, от чьего имени вы работаете.
любой ключ
list_projects
Проекты с досками и колонками (id и тип колонки: todo, progress, done). Нужен, чтобы создавать и переносить задачи.
любой ключ
list_users
Участники компании: id, имя, логин, должность. Нужен, чтобы назначать исполнителей.
любой ключ
search_tasks
Задачи по фильтрам: текст, проект, исполнитель (me — пользователь ключа), тип колонки, метка. Без фильтров — открытые задачи пользователя ключа.
tasks:read
get_task
Задача целиком в Markdown: описание, чек-лист, подзадачи, обсуждение (комментарии с id), связанные документы и договорённости со встреч. Задачу можно указать ключом (WEB-42).
tasks:read
add_comment
Комментарий к задаче от имени пользователя ключа. Сюда пишите результат работы: что сделано, ответ на вопрос, отчёт, ссылки. Можно ответить на комментарий (replyTo — id из get_task) и упомянуть людей через @логин.
tasks:write
create_task
Новая задача от имени пользователя ключа. Описание — в Markdown.
tasks:write
update_task
Меняет только переданные поля: название, приоритет, тип, метки, срок, исполнителей, чек-лист. Описание задачи — постановка от людей, агент его не меняет: результат пишите через add_comment.
tasks:write
move_task
Переносит задачу в колонку её доски: по названию колонки, её id или типу (todo, progress, done — первая колонка такого типа).
tasks:write
log_time
Записывает потраченное время на задачу от имени пользователя ключа.
time:write
time_report
Сколько времени потрачено за период в разрезе людей, задач, проектов или дней.
time:read
list_docs
Разделы документации и страницы в них; можно искать по тексту.
docs:read
get_doc
Страница документации целиком в Markdown.
docs:read
create_doc
Новая страница документации; содержимое — в Markdown.
docs:write
update_doc
Заменяет заголовок и/или содержимое страницы (Markdown, целиком). Прежний текст остаётся в истории версий.
docs:write
list_meetings
Записанные встречи, новые сверху; поиск по названию и саммари, фильтр по датам.
meetings:read
get_meeting
Саммари встречи (темы, решения, договорённости) и, по желанию, полный транскрипт.
meetings:read
Тексты задач и документов пишут люди, поэтому агенту сказано не выполнять инструкции из них без вашего подтверждения. Результат работы агент пишет комментарием к задаче, а описание — постановку от людей — не меняет. Удалять задачи через MCP нельзя; для агента удобно завести отдельного пользователя или ограничить ключ проектами.
Ключи и права
Ключ действует от имени пользователя и никогда не может больше, чем он сам: доски, разделы документов и папки встреч, закрытые для пользователя, закрыты и для ключа. Администратор может выпустить ключ от имени любого участника — для интеграций удобно завести отдельного пользователя, например «Интеграция 1С», чтобы его действия было видно в истории.
Что ещё настраивается у ключа:
Права — какие разделы ключ читает и меняет (таблица ниже). Проекты, доски, колонки, пользователи и метки может читать любой ключ.
Проекты — все или только выбранные: остальные проекты, их задачи и время ключ не видит.
Срок действия — бессрочно или 30 дней — год.
IP-адреса — запросы принимаются только с перечисленных адресов или диапазонов (203.0.113.10, 10.0.0.0/24).
По умолчанию ключи выпускает только администратор; он может разрешить это всем участникам. Ключ можно отозвать в любой момент — он перестаёт работать сразу. В базе хранится только хеш ключа.
Право
Раздел
Что разрешает
tasks:read
Задачи
Задачи, чек-листы, подзадачи
tasks:write
Задачи
Создание, правка, перенос, исполнители, удаление
projects:write
Проекты
Создание проектов, досок и колонок, правка проектов
time:read
Время
Записи времени и отчёты по задачам, людям, проектам
time:write
Время
Списание времени на задачи
docs:read
Документы
Разделы и страницы документации
docs:write
Документы
Создание и правка страниц
meetings:read
Транскрипты
Встречи, саммари и транскрипты
Формат и ошибки
Успешный ответ — 200 (или 201 при создании, 204 без тела при удалении); объект — в поле data. Ошибка — код HTTP и объект с машинным кодом и понятным описанием на русском:
{
"error": {
"code": "insufficient_scope",
"message": "Ключу не выдано право tasks:write"
}
}
HTTP
code
Когда
400
invalid_request
Неверные параметры или тело запроса; в message — какое поле и что не так
401
unauthorized
Ключ не передан
401
invalid_key
Ключ неверный, отозван или его пользователь удалён
401
key_expired
Срок действия ключа истёк
403
insufficient_scope
Ключу не выдано нужное право
403
forbidden
У пользователя ключа нет прав на это действие
403
ip_not_allowed
Запрос пришёл не с разрешённого IP-адреса
403
api_disabled
Администратор отключил ключи участников
403
plan_required
API не входит в тариф компании: он доступен на «Команде» и «Бизнесе»
404
not_found
Объекта нет или он не виден ключу
409
archived
Задача в архиве — менять её можно после возврата из архива в Klepps
422
rejected
Действие не выполнено по правилам Klepps (лимит тарифа, цикл подзадач и т. п.); причина — в message
429
rate_limited
Превышен лимит запросов в минуту
Лимит запросов
До 120 запросов в минуту на ключ. Остаток видно в заголовках x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset; при превышении — 429 и заголовок retry-after (секунды).
Списки и синхронизация
Списки отдаются страницами: limit — сколько (до 500, по умолчанию 100), cursor — с какого места. В ответе nextCursor (null — это последняя страница) и total — сколько всего подходит под фильтры.
Чтобы держать копию данных у себя, запрашивайте задачи и документы с updatedSince — придут только изменённые после указанного момента (ISO 8601 или миллисекунды). Задачу можно найти по ключу: GET /tasks/WEB-42.
Ключ и компания
Проверить ключ
GET/me
Доступно любому ключу
От чьего имени работает ключ, в какой компании и с какими правами. Удобно для проверки подключения.
Задачу можно указывать по id или по ключу (WEB-42). Описание приходит в HTML (description) и простым текстом (descriptionText); при записи можно передать любое из двух. Время — в секундах.
Список задач
GET/tasks
Право ключа: tasks:read
Краткие карточки без описания, по дате создания. Для синхронизации используйте updatedSince.
Параметры запроса
projectId, boardId, statusId
string
Где лежит задача
category
todo | progress | done
Тип колонки
assigneeId
string
Исполнитель (любой из assigneeIds); none — без исполнителя
Задача одним Markdown-текстом: свойства, описание, чек-лист, подзадачи, обсуждение (последние 50 комментариев с id), связанные документы (с правом docs:read) и договорённости со встреч (с правом meetings:read). Готовый контекст для ИИ-агента; то же копирует кнопка «Скопировать для ИИ» в карточке задачи.
Параметры пути
refобязательно
string
id или ключ задачи
Параметры запроса
format
markdown | json
По умолчанию text/markdown; json — {data: {taskId, key, markdown}}
# WEB-42: Форма обратной связи
- Проект: Сайт (WEB); доска: Разработка; колонка: В работе (в работе)
- Тип: задача; приоритет: высокий
- Исполнители: Иван Петров; автор: Анна Смирнова
- Срок: 2026-10-20; оценка: 1д; потрачено: 1ч 30м
## Описание
Поля: имя, контакт, сообщение. Отправка — на **/api/feedback**.
## Чек-лист
- [x] Вёрстка
- [ ] Валидация
## Связанные документы
### Форма обратной связи (раздел «Техническая документация», id d-feedback)
…
Создать задачу
POST/tasks
Право ключа: tasks:write
Автором становится пользователь ключа. Исполнители получают уведомление, автоматизации доски срабатывают как обычно.
Тело запроса (JSON)
titleобязательно
string
Название
boardId
string
Доска; или projectId — тогда первая доска проекта
statusId
string
Колонка, по умолчанию первая
description / descriptionText
string
Описание в HTML или простым текстом
type
task | bug | story | epic
По умолчанию task
priority
highest | high | medium | low | lowest
По умолчанию medium
assigneeIds
string[]
Исполнители
assigneeId
string
У кого задача сейчас (по умолчанию первый из assigneeIds)
Передавайте только меняющиеся поля. statusId переносит задачу в колонку (наверх), boardId — на другую доску проекта, assigneeIds заменяет список исполнителей, assigneeId передаёт задачу.
От имени пользователя ключа. Автор и исполнители задачи, упомянутые и автор комментария, на который отвечают, получают уведомление во «Входящих». Сюда ИИ-агенту стоит писать результат работы, не меняя описание задачи.
Тело запроса (JSON)
textобязательно
string
Текст, до 20 000 символов
replyTo
string | null
id комментария, на который это ответ
curl -X POST "https://klepps.ru/api/v1/tasks/WEB-42/comments" \
-H "Authorization: Bearer $KLEPPS_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Готово: форма отправляет заявку, валидация полей на клиенте и сервере. @anna@romashka.ru посмотрите, пожалуйста."
}'
Ответ
{
"data": {
"id": "m-z7x6c5v4",
"authorId": "u-p7d2x8q4",
"text": "Готово: форма отправляет заявку, валидация полей на клиенте и сервере.",
"replyTo": null,
"createdAt": 1760090000000
}
}
Учёт времени
Записи времени привязаны к дню (ГГГГ-ММ-ДД). В отчёты попадают и задачи из архива.
Отчёт по времени
GET/time/report
Право ключа: time:read
Суммы за период в разрезе людей, задач, проектов или дней — до трёх разрезов сразу (например, user,task — кто сколько потратил на каждую задачу).
Параметры запроса
from, to
ГГГГ-ММ-ДД
Период включительно, не больше года; по умолчанию с 1-го числа по сегодня
Видны только разделы, которые может читать пользователь ключа. Содержимое — HTML (content) и простой текст (text). При записи HTML очищается: скрипты, стили и чужие теги удаляются.
{
"data": {
"meetingId": "mt-h5j6k7",
"replicas": [
{
"speaker": "Анна Смирнова",
"start": "00:00:04",
"end": "00:00:11",
"text": "Коллеги, начнём. Сегодня планируем четырнадцатый спринт."
},
{
"speaker": "Иван Петров",
"start": "00:00:12",
"end": "00:00:20",
"text": "Предлагаю начать с формы обратной связи, макет уже готов."
}
]
}
}
Примеры интеграций
Табель за месяц в Excel (CSV)
# Отчёт по времени за прошлый месяц: кто сколько часов потратил на какую задачу
import csv, datetime, os, requests
today = datetime.date.today()
last = today.replace(day=1) - datetime.timedelta(days=1)
res = requests.get(
"https://klepps.ru/api/v1/time/report",
params={"from": last.replace(day=1).isoformat(), "to": last.isoformat(), "groupBy": "user,task"},
headers={"Authorization": f"Bearer {os.environ['KLEPPS_KEY']}"},
)
res.raise_for_status()
with open("time.csv", "w", newline="", encoding="utf-8-sig") as f:
w = csv.writer(f, delimiter=";")
w.writerow(["Сотрудник", "Задача", "Название", "Часы"])
for row in res.json()["data"]:
w.writerow([row["user"]["name"], row["task"]["key"], row["task"]["title"], str(row["hours"]).replace(".", ",")])
Заявка с сайта или из CRM — задача
// Заявка с сайта или из CRM → задача в Klepps
await fetch("https://klepps.ru/api/v1/tasks", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.KLEPPS_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
projectId: "p-w1e8r5t2",
title: `Заявка: ${lead.company}`,
descriptionText: `${lead.name}, ${lead.phone}\n\n${lead.message}`,
labels: ["заявка"],
priority: "high",
dueDate: new Date(Date.now() + 86400000).toISOString().slice(0, 10),
}),
});
Синхронизация изменений
// Забираем всё, что изменилось с прошлого запуска (постранично)
let since = loadCheckpoint(); // ISO-время прошлого запуска
const started = new Date().toISOString();
let cursor = null;
do {
const url = new URL("https://klepps.ru/api/v1/tasks");
url.searchParams.set("updatedSince", since);
url.searchParams.set("archived", "all");
url.searchParams.set("limit", "500");
if (cursor) url.searchParams.set("cursor", cursor);
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.KLEPPS_KEY}` } });
const page = await res.json();
for (const task of page.data) await upsert(task);
cursor = page.nextCursor;
} while (cursor);
saveCheckpoint(started);