Перейти к содержимому

Интеграция MCP клиентов

Moira работает с любым клиентом, поддерживающим Model Context Protocol (MCP). Это руководство описывает настройку распространённых MCP-клиентов.

Обзор протокола MCP

Moira предоставляет инструменты через MCP Streamable HTTP:

  • Endpoint: https://moira-mcp.com/mcp
  • Транспорт: Streamable HTTP; успешные ответы могут передаваться потоком SSE
  • Аутентификация: OAuth 2.1 или API-токен

Конфигурация клиентов

Выполните команду в своём проекте. По умолчанию подключение доступно только вам в этом проекте; добавьте --scope user для всех проектов. Ручная альтернатива .mcp.json ниже действует на уровне проекта; перед включением проверьте доверие. Объединяйте записи с существующим файлом, сохраняя другие серверы.

Terminal
claude mcp add --transport http moira 'https://moira-mcp.com/mcp'

Если нужна авторизация, следуйте приглашению в браузере или выполните команду входа. Для удалённого терминала claude mcp login moira --no-browser печатает ссылку. Не повторяйте вход для уже работающего подключения.

Terminal
claude mcp login moira
Ручная настройка
.mcp.json
{
  "mcpServers": {
    "moira": {
      "type": "http",
      "url": "https://moira-mcp.com/mcp"
    }
  }
}
Альтернатива: API-токен

Используйте статический API-токен, если выбираете этот способ вместо OAuth через браузер. Храните токен в секрете.

Войдите в Moira → Настройки → API Токены и создайте токен. Замените moira_YOUR_TOKEN ниже на этот токен. Объедините альтернативу с конфигурацией клиента, не добавляя вторую запись Moira.

.mcp.json
{
  "mcpServers": {
    "moira": {
      "type": "http",
      "url": "https://moira-mcp.com/mcp",
      "headers": {
        "Authorization": "Bearer moira_YOUR_TOKEN"
      }
    }
  }
}

Выполните claude mcp list или откройте /mcp в Claude Code и проверьте подключение Moira и её инструменты. Затем попросите агента вызвать инструмент Moira list, который только читает данные, и показать доступные процессы. Сохранённая конфигурация сама по себе не подтверждает подключение.

Официальная документация клиента

Собственный клиент

Для собственных MCP-клиентов используйте MCP SDK с URL: https://moira-mcp.com/mcp

Доступные инструменты

Используйте workflow с action: "list", затем execution с действиями prepare, execute и повторными step. Та же группа execution служит для просмотра и возобновления выполнений, а help — для runtime-документации. Справочник MCP-инструментов является источником полного актуального каталога, точных входных схем, действий и примеров.

Аутентификация

Moira поддерживает два метода аутентификации:

OAuth 2.1 (по умолчанию)

  1. Клиент подключается к MCP endpoint.
  2. Сервер запрашивает аутентификацию.
  3. Клиент открывает OAuth в браузере.
  4. Пользователь входит в Moira.
  5. Клиент получает токен доступа.
  6. Последующие запросы передают этот токен.

Обновление OAuth-токена обрабатывается автоматически и сохраняет состояние каталога, принятое предыдущим токеном доступа. Обновление каталога после изменения серверного контракта — отдельная MCP-инициализация, описанная ниже. При истечении учётных данных может потребоваться повторная аутентификация.

API-токены

Для MCP-клиентов, которые не поддерживают OAuth (пользовательские скрипты, CI/CD пайплайны, headless-окружения), используйте API-токены:

  1. Войдите в веб-интерфейс Moira.
  2. Откройте Настройки → Приложения и токены → API-токены.
  3. Выберите Create Token, задайте имя и срок действия.
  4. Скопируйте токен: он показывается один раз и начинается с moira_.
  5. Настройте Bearer-авторизацию клиента; токен не должен попадать в Git или логи.

Используйте пример токена выбранного клиента выше. JSON-, YAML- и TOML-клиенты размещают авторизацию по-разному; не копируйте формат другого клиента. В собственном SDK-клиенте задайте Authorization: Bearer moira_... в HTTP-транспорте для https://moira-mcp.com/mcp.

API-токены полностью обходят OAuth. Используйте выбранный endpoint https://moira-mcp.com/mcp и сохраняйте другие серверы при объединении конфигурации с токеном. Уже работающее подключение не требует нового токена или входа.

Обновление статического каталога

Описания и схемы инструментов входят в статический каталог, поставляемый с сервером Moira. Клиент принимает этот каталог во время MCP-handshake initialize. Это правило одинаково для OAuth-токенов доступа и API-токенов.

После изменения каталога обычный запрос с учётными данными, которые ещё не инициализировали текущий каталог, получает HTTP 426 с upgrade_required. Переподключите или повторно инициализируйте MCP-сервер с теми же учётными данными. Успешный initialize обновляет каталог для этих учётных данных; создавать новый API-токен не требуется. OAuth-токены доступа могут независимо заменяться при автоматическом обновлении, сохраняя актуальное, устаревшее или ещё не инициализированное состояние каталога.

Клиент может сначала отправить server/discover. После проверки авторизации этот запрос достигает SDK до принятия каталога. SDK Moira обслуживает прежний протокол и возвращает ответ о неподдерживаемом методе или версии, чтобы совместимый клиент перешёл к initialize. Само обнаружение не принимает каталог и не разрешает вызовы инструментов. Поддержка stateless-протокола 2026 года этим не объявляется.

Проверки аутентификации и состояния учётной записи выполняются до обновления каталога. Отозванные или истёкшие учётные данные и учётная запись без доступа к MCP по-прежнему получают обычную ошибку аутентификации или доступа.

Примеры вызова инструментов

Список воркфлоу

{
"method": "tools/call",
"params": {
"name": "workflow",
"arguments": { "action": "list" }
}
}

Подготовка запуска воркфлоу

{
"method": "tools/call",
"params": {
"name": "execution",
"arguments": {
"action": "prepare",
"workflowId": "moira/software-development-flow",
"parentExecutionId": "none"
}
}
}

Подготовка возвращает startAttemptId, не создавая execution. Выполните его вторым вызовом:

{
"method": "tools/call",
"params": {
"name": "execution",
"arguments": {
"action": "execute",
"startAttemptId": "start-attempt-current"
}
}
}

Выполнение шага

{
"method": "tools/call",
"params": {
"name": "execution",
"arguments": {
"action": "step",
"processId": "abc-123",
"attemptId": "attempt-current",
"input": {
"result": "Задача выполнена успешно",
"details": { "files": ["main.ts", "utils.ts"] }
}
}
}
}

Обработка ошибок

Типичные ответы об ошибках:

ОшибкаПричинаРешение
UNAUTHORIZEDНедействительный/истекший токенПовторная аутентификация
NOT_FOUNDНедействительный ID воркфлоу/процессаПроверьте ID
FORBIDDENНет доступа к ресурсуПроверьте права
upgrade_requiredТребуется обновить каталог MCPПереподключитесь с теми же учётными данными
VALIDATION_ERRORНедействительный вводПроверьте input schema
ATTEMPT_PROCESSINGДубликат ещё выполняетсяПовторите ту же попытку и ввод
ATTEMPT_STALEПредъявление больше не текущееПрочитайте current_step; согласуйте намерение до отправки
ATTEMPT_CONFLICTПопытка связана с другим вводомПрочитайте current_step; отбросьте старый ввод
ATTEMPT_INVALID_OR_EXPIRED (шаг)Попытка недоступнаПрочитайте current_step; отбросьте попытку
ATTEMPT_OUTCOME_UNKNOWNЭффект мог уже произойтиНайдите возвращённый Process ID

Настройка self-hosted

Полные различия восстановления приведены в Решении проблем. Новое предъявление не разрешает переносить старый ответ в другой шаг; неизвестный исход читается, а не повторяется автоматически.

Для self-hosted Moira:

  1. Разверните сервер Moira
  2. Настройте URL MCP endpoint
  3. Настройте аутентификацию и доступ учётной записи
  4. Обновите конфигурацию клиента с вашим endpoint

Устранение неполадок

Таймаут подключения

  • Проверьте сетевое подключение
  • Проверьте URL endpoint
  • Убедитесь, что SSE не блокируется файрволом

Инструменты не появляются

  • Переподключите MCP-сервер Moira, чтобы клиент снова выполнил initialize
  • Сохраните текущий OAuth- или API-токен, если он не отозван и не истёк
  • Проверьте формат конфигурации и диагностику выбранного клиента по его официальной инструкции выше
  • Проверьте логи клиента на наличие ошибок

Цикл аутентификации

  • Проверьте выбранный URL сервера, аккаунт и состояние клиента до изменения учётных данных
  • Отличайте отказ авторизации от HTTP 426: последний требует инициализации с теми же учётными данными
  • Изучите диагностику клиента и официальную инструкцию OAuth, включая требования к redirect
  • Повторяйте вход, только если текущие учётные данные недействительны или истекли и refresh не восстанавливает доступ; не очищайте другие подключения

Связанное