Подключить MCP Трекера к ИИ-агенту

MCP (Model Context Protocol) — стандартный протокол для подключения внешних инструментов к ИИ-ассистентам. Подключите MCP-сервер Трекера, чтобы дать ассистенту доступ к задачам, проектам и целям вашей организации.

Сервер выполняет запросы от имени владельца токена и с его правами. У сервера нет собственной учетной записи: он передает учетные данные в API Яндекс Трекера без изменений.

Возможности MCP-сервера

Через MCP-сервер ассистент может:

• работать с задачами: искать, читать, создавать, изменять поля, переводить в другой статус и просматривать историю изменений;
• просматривать, создавать и удалять связи между задачами и ссылки на объекты в других приложениях;
• читать, добавлять, изменять и удалять комментарии;
• работать с учетом времени: читать, создавать, изменять и удалять списания;
• работать с досками и спринтами: получать список досок, просматривать спринты, создавать, изменять и удалять спринты;
• искать, читать, создавать, изменять и удалять проекты, портфели и цели, а также работать с их связями и комментариями, чек-листами проектов и портфелей и ключевыми результатами целей;
• получать справочные данные: очереди, приоритеты, типы задач, резолюции, доступные переходы, формы очереди и пользователей;
• получать список вложений, их метаданные и временную ссылку на скачивание, а также загружать и удалять файлы;
• настраивать триггеры очереди;
• выполнять массовое изменение полей, перевод статуса и перенос задач между очередями, а также массовое изменение полей проектов, портфелей и целей.

Как подключить

Чтобы подключить MCP-сервер Трекера к ИИ-ассистенту:

1. Получите OAuth-токен или IAM-токен для доступа к API. Подробнее читайте в разделе Доступ к API. IAM-токен используется для организации в Yandex Cloud и действует до 12 часов.
2. Откройте страницу Администрирование → Организации и скопируйте значение поля Идентификатор в карточке организации. Если карточка называется Яндекс 360 для бизнеса, передавайте идентификатор в заголовке X-Org-ID, если Yandex Cloud Organization — в заголовке X-Cloud-Org-ID.
3. Добавьте конфигурацию MCP-сервера в настройки ИИ-ассистента. Укажите URL и заголовки из таблицы ниже.
4. Проверьте подключение. Например, в Codex выполните команду /mcp: сервер и его инструменты должны появиться в списке. Список инструментов загружается без проверки токена, поэтому затем попросите ассистента выполнить простой запрос, например показать список очередей.

Параметры подключения:

Примеры подключения

Способ добавления MCP-конфигурации зависит от ИИ-инструмента. Обычно достаточно указать URL сервера и обязательные заголовки.

В примерах используется заголовок X-Org-ID. Если идентификатор скопирован из карточки Yandex Cloud Organization, укажите вместо него X-Cloud-Org-ID.

Настройка для Codex

Для OAuth-токена используйте схему OAuth. Параметр --bearer-token-env-var не подходит: он передает значение в схеме Bearer. Укажите заголовок Authorization целиком. Для IAM-токена задайте в переменной значение Bearer <IAM_token>.

Добавьте в файл ~/.codex/config.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 задайте переменные окружения:

export TRACKER_MCP_AUTHORIZATION="OAuth <token>"
export TRACKER_MCP_ORG_ID="<organization_id>"
codex

Настройка для Claude Code

В одинарных кавычках ссылка на переменную окружения сохранится в файле .mcp.json, а не будет заменена значением токена. Имя сервера и URL укажите перед параметрами --header, иначе команда завершится с ошибкой:

export TRACKER_OAUTH_TOKEN="<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: <organization_id>'

Настройка для другого MCP-клиента

Укажите тип сервера http, URL и обязательные заголовки. Например:

{
  "mcpServers": {
    "tracker": {
      "type": "http",
      "url": "https://mcp.tracker.yandex.net/mcp",
      "headers": {
        "Authorization": "OAuth <token>",
        "X-Org-ID": "<organization_id>",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Если клиент поддерживает подстановку переменных окружения, укажите в заголовке Authorization ссылку на переменную, а не токен.

Ограничения

• Ассистент не получает данные части задач, даже если вы видите их в веб-интерфейсе. Это происходит, если в настройках очереди для опции Доступ для AI инструментов выбрано значение Запретить. Вместо данных сервер возвращает ключ задачи и признак restricted. Изменять такие задачи ассистент может.
• Содержимое вложений не передается. Ассистент получает метаданные и ссылку на скачивание, которая действует 5 минут. Размер загружаемого через MCP файла не должен превышать 256 КиБ; более крупные файлы добавляйте через веб-интерфейс.
• Массовые операции выполняются асинхронно. После отправки операции ассистент должен дождаться ее завершения, проверяя статус.
• Каталог инструментов передается клиенту при подключении и занимает контекст ассистента. Отключайте ненужные инструменты средствами клиента.
• Формы очереди можно только читать: отправить форму через MCP-сервер нельзя.
• При чтении триггера сервер не возвращает учетные данные вебхуков. При изменении действий триггера укажите их заново.

Безопасность

• Выдавайте токену минимально необходимые права: ассистент сможет выполнить все действия, доступные владельцу токена.
• Включите подтверждение вызовов, которые изменяют данные. Среди инструментов есть необратимое удаление объектов и массовые операции.
• Храните в конфигурации клиента только ссылку на переменную окружения, а не токен. Файлы .mcp.json и .codex/config.toml могут попасть в репозиторий.
• Токены, тексты задач и комментариев не записываются в логи сервера. В логи попадают адреса и параметры запросов к API: например, ключи задач, имена загружаемых файлов и строки поиска.

Если не работает

См. также

• Работать с задачами из командной строки