--- metadata: - name: generator content: Diplodoc Platform v5.66.1 - property: og:type content: article - property: article:section content: Интеграция с другими сервисами - property: og:title content: Подключить MCP Трекера к ИИ-агенту - property: article:tag content: Техническая инструкция alternate: - https://yandex.ru/support/tracker/en/user/mcp-server.md - https://yandex.ru/support/tracker/ru/user/mcp-server.md - href: https://yandex.ru/support/tracker/ru/user/mcp-server.md type: text/markdown title: Markdown version - href: https://yandex.ru/support/tracker/ru/llms.txt?revision=r22077802 rel: describedby --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/support/tracker/ru/llms.txt?revision=r22077802 # Подключить MCP Трекера к ИИ-агенту MCP (Model Context Protocol) — стандартный протокол для подключения внешних инструментов к ИИ-ассистентам. Подключите MCP-сервер Трекера, чтобы дать ассистенту доступ к задачам, проектам и целям вашей организации. Сервер выполняет запросы от имени владельца токена и с его правами. У сервера нет собственной учетной записи: он передает учетные данные в API Яндекс Трекера без изменений. ## Возможности MCP-сервера {#capabilities} Через MCP-сервер ассистент может: - работать с задачами: искать, читать, создавать, изменять поля, переводить в другой статус и просматривать историю изменений; - просматривать, создавать и удалять связи между задачами и ссылки на объекты в других приложениях; - читать, добавлять, изменять и удалять комментарии; - работать с учетом времени: читать, создавать, изменять и удалять списания; - работать с досками и спринтами: получать список досок, просматривать спринты, создавать, изменять и удалять спринты; - искать, читать, создавать, изменять и удалять проекты, портфели и цели, а также работать с их связями и комментариями, чек-листами проектов и портфелей и ключевыми результатами целей; - получать справочные данные: очереди, приоритеты, типы задач, резолюции, доступные переходы, формы очереди и пользователей; - получать список вложений, их метаданные и временную ссылку на скачивание, а также загружать и удалять файлы; - настраивать триггеры очереди; - выполнять массовое изменение полей, перевод статуса и перенос задач между очередями, а также массовое изменение полей проектов, портфелей и целей. ## Как подключить {#connection} Чтобы подключить MCP-сервер Трекера к ИИ-ассистенту: 1. Получите OAuth-токен или IAM-токен для доступа к API. Подробнее читайте в разделе [Доступ к API](https://yandex.ru/support/tracker/ru/api/access.md). IAM-токен используется для организации в Yandex Cloud и действует до 12 часов. 1. Откройте страницу [**Администрирование → Организации**](https://tracker.yandex.ru/admin/orgs) и скопируйте значение поля **Идентификатор** в карточке организации. Если карточка называется **Яндекс 360 для бизнеса**, передавайте идентификатор в заголовке `X-Org-ID`, если **Yandex Cloud Organization** — в заголовке `X-Cloud-Org-ID`. 1. Добавьте конфигурацию MCP-сервера в настройки ИИ-ассистента. Укажите URL и заголовки из таблицы ниже. 1. Проверьте подключение. Например, в Codex выполните команду `/mcp`: сервер и его инструменты должны появиться в списке. Список инструментов загружается без проверки токена, поэтому затем попросите ассистента выполнить простой запрос, например показать список очередей. Параметры подключения: | **Параметр** | **Значение** | | --- | --- | | URL | `https://mcp.tracker.yandex.net/mcp` | | Транспорт | Streamable HTTP, метод `POST`. Сессии не используются. | | Заголовок `Authorization` | `OAuth ` или `Bearer `. Сервер передает заголовок в API без изменений. | | Идентификатор организации | Заголовок `X-Org-ID` или `X-Cloud-Org-ID` в зависимости от карточки организации, см. шаг 2. | | Заголовок `Accept` | `application/json, text/event-stream`. MCP-клиенты обычно передают его сами. Без него сервер отвечает `406 Not Acceptable`. | ## Примеры подключения {#connection-examples} Способ добавления MCP-конфигурации зависит от ИИ-инструмента. Обычно достаточно указать URL сервера и обязательные заголовки. В примерах используется заголовок `X-Org-ID`. Если идентификатор скопирован из карточки **Yandex Cloud Organization**, укажите вместо него `X-Cloud-Org-ID`. ### Настройка для Codex {#codex} Для OAuth-токена используйте схему `OAuth`. Параметр `--bearer-token-env-var` не подходит: он передает значение в схеме `Bearer`. Укажите заголовок `Authorization` целиком. Для IAM-токена задайте в переменной значение `Bearer `. Добавьте в файл `~/.codex/config.toml`: ```toml [mcp_servers.tracker] url = "https://mcp.tracker.yandex.net/mcp" env_http_headers = { Authorization = "TRACKER_MCP_AUTHORIZATION", "X-Org-ID" = "TRACKER_MCP_ORG_ID" } default_tools_approval_mode = "writes" ``` Перед запуском Codex задайте переменные окружения: ```bash export TRACKER_MCP_AUTHORIZATION="OAuth " export TRACKER_MCP_ORG_ID="" codex ``` ### Настройка для Claude Code {#claude-code} В одинарных кавычках ссылка на переменную окружения сохранится в файле `.mcp.json`, а не будет заменена значением токена. Имя сервера и URL укажите перед параметрами `--header`, иначе команда завершится с ошибкой: ```bash export TRACKER_OAUTH_TOKEN="" claude mcp add \ --transport http \ --scope project \ tracker \ https://mcp.tracker.yandex.net/mcp \ --header 'Authorization: OAuth ${TRACKER_OAUTH_TOKEN}' \ --header 'X-Org-ID: ' ``` ### Настройка для другого MCP-клиента {#other-client} Укажите тип сервера `http`, URL и обязательные заголовки. Например: ```json { "mcpServers": { "tracker": { "type": "http", "url": "https://mcp.tracker.yandex.net/mcp", "headers": { "Authorization": "OAuth ", "X-Org-ID": "", "Accept": "application/json, text/event-stream" } } } } ``` Если клиент поддерживает подстановку переменных окружения, укажите в заголовке `Authorization` ссылку на переменную, а не токен. ## Ограничения {#limitations} - Ассистент не получает данные части задач, даже если вы видите их в веб-интерфейсе. Это происходит, если в настройках очереди для опции **Доступ для AI инструментов** выбрано значение **Запретить**. Вместо данных сервер возвращает ключ задачи и признак `restricted`. Изменять такие задачи ассистент может. - Содержимое вложений не передается. Ассистент получает метаданные и ссылку на скачивание, которая действует 5 минут. Размер загружаемого через MCP файла не должен превышать 256 КиБ; более крупные файлы добавляйте через веб-интерфейс. - Массовые операции выполняются асинхронно. После отправки операции ассистент должен дождаться ее завершения, проверяя статус. - Каталог инструментов передается клиенту при подключении и занимает контекст ассистента. Отключайте ненужные инструменты средствами клиента. - Формы очереди можно только читать: отправить форму через MCP-сервер нельзя. - При чтении триггера сервер не возвращает учетные данные вебхуков. При изменении действий триггера укажите их заново. ## Безопасность {#security} - Выдавайте токену минимально необходимые права: ассистент сможет выполнить все действия, доступные владельцу токена. - Включите подтверждение вызовов, которые изменяют данные. Среди инструментов есть необратимое удаление объектов и массовые операции. - Храните в конфигурации клиента только ссылку на переменную окружения, а не токен. Файлы `.mcp.json` и `.codex/config.toml` могут попасть в репозиторий. - Токены, тексты задач и комментариев не записываются в логи сервера. В логи попадают адреса и параметры запросов к API: например, ключи задач, имена загружаемых файлов и строки поиска. ## Если не работает {#troubleshooting} | **Симптом** | **Причина и решение** | | --- | --- | | При вызове инструментов появляется ошибка `403 Organization is not available, not ready or not found` | Не передан идентификатор организации или он передан не в том заголовке. Для идентификатора из карточки **Яндекс 360 для бизнеса** используйте `X-Org-ID`, из карточки **Yandex Cloud Organization** — `X-Cloud-Org-ID`. | | На все запросы приходит `404` | Для публичного сервера указан путь `/api/mcp`. Используйте `https://mcp.tracker.yandex.net/mcp`. | | При вызове инструментов появляется ошибка `401` | Токен не передан, истек или выбрана неверная схема авторизации. Для OAuth используйте `OAuth `, для IAM-токена — `Bearer `. | | Приходит `406 Not Acceptable` | Клиент не передал заголовок `Accept`. Добавьте заголовок `Accept: application/json, text/event-stream`. | | Задача видна в веб-интерфейсе, но сервер возвращает `restricted` | В настройках очереди запрещен доступ для AI инструментов. См. [Ограничения](#limitations). | | В ответе есть `applied: null` | Трекер не подтвердил запись. Проверьте результат чтением и не повторяйте вызов вслепую: например, списание времени может задвоиться. | ## См. также {#see-also} - [Работать с задачами из командной строки](https://yandex.ru/support/tracker/ru/user/cli.md)