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

Интеграция 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-токен

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

Рекомендуется: используйте CLI-команду

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

Затем авторизуйтесь:

OAuth Flow
# После добавления авторизуйтесь в claude:
/mcp
# → Выберите "moira"
# → Нажмите "Authenticate"
# → Откроется браузер для OAuth
Альтернатива: ручная настройка JSON
{
  "mcpServers": {
    "moira": {
      "url": "https://moira-mcp.com/mcp"
    }
  }
}
Аутентификация без OAuth

Для CI/CD, Docker или окружений без браузера — используйте API токен вместо OAuth.

1. Войдите в веб-интерфейс Moira → Настройки → API Токены
2. Создайте токен (начинается с moira_)
3. Замените moira_YOUR_TOKEN ниже на ваш токен
~/.config/claude/mcp.json
{
  "mcpServers": {
    "moira": {
      "url": "https://moira-mcp.com/mcp",
      "headers": {
        "Authorization": "Bearer moira_YOUR_TOKEN"
      }
    }
  }
}

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

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

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

Основной цикл выглядит как list → start prepare → start execute → повторные вызовы step; session используется для просмотра и возобновления выполнений, а 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. Перейдите в Settings → API Tokens 3. Нажмите Create Token, введите имя и срок действия 4. Скопируйте токен (показывается один раз, начинается с moira_) 5. Настройте клиент с токеном в качестве Bearer-авторизации

Пример конфигурации для пользовательского MCP-клиента:

{
  "mcpServers": {
    "moira": {
      "url": "YOUR_MCP_ENDPOINT",
      "headers": {
        "Authorization": "Bearer moira_your_token_here"
      }
    }
  }
}

Замените YOUR_MCP_ENDPOINT на ваш MCP endpoint Moira: https://moira-mcp.com/mcp. API-токены полностью обходят OAuth-поток — используйте их, когда клиент не может открыть браузер для аутентификации.

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

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

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

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

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

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

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

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

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

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

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

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

{
  "method": "tools/call",
  "params": {
    "name": "step",
    "arguments": {
      "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
{
  "mcpServers": {
    "moira": {
      "url": "https://your-server.com/mcp"
    }
  }
}

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

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

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

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

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

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

  • Очистите сохраненные токены
  • Проверьте конфигурацию OAuth
  • Проверьте redirect URI

Связанное