Настройка MCP-сервера Ogma

MCP-сервер Ogma (ogma-mcp) позволяет совместимым ИИ-помощникам изучать контекст проекта и, при включении, управлять встроенным браузером, отправлять запросы, запускать рабочие процессы и собирать доказательства. Инструменты заметок и задач используют блокнот сессии MCP в памяти, отдельный от постоянной страницы заметок приложения.

MCP предназначен для внешних инструментов, таких как Codex, Claude Code, Cursor и другие клиенты Model Context Protocol. Это отдельная функция, отличная от встроенного ИИ-помощника рабочего пространства.

Полный список см. в Ресурсы и инструменты MCP.

Быстрый старт: десктопное приложение

1. Запустите Ogma и откройте проект для анализа агентом.
2. Откройте Настройки > MCP, выберите разрешения и сохраните. Для браузера нужно разрешение Повторная отправка.
3. Нажмите Запустить и скопируйте адрес, обычно http://127.0.0.1:3000/mcp.
4. Добавьте его в MCP-клиент как сервер Streamable HTTP.
5. Попросите агента вызвать ogma_explain_capabilities и прочитать ogma://project/current для проверки соединения и проекта.

Отдельная сборка бинарного файла не нужна. Переходы, формы, сценарии входа и диагностику см. в Автоматизация браузера через MCP.

Адреса подключения

Интерфейс	Адрес по умолчанию	Назначение
Транспорт MCP	http://127.0.0.1:3000/mcp	Подключение нативных MCP-клиентов.
REST API сервера	http://127.0.0.1:8181	--api-url отдельного MCP и маршруты управления и моста ниже.
Слушатель прокси	127.0.0.1:8080	Запись трафика браузера; это не адрес MCP.

Десктопные экземпляры могут динамически назначать порт API. Для stdio/REST используйте фактический адрес работающего экземпляра, для нативного MCP — адрес настроек. Облачный чат не достигает loopback без локального клиента или коннектора.

HTTP-адрес сохраняет состояние: предоставьте клиенту управление инициализацией и заголовками сессии. Отдельного устаревшего адреса /sse нет. Собственные клиенты должны следовать спецификации транспорта MCP.

Когда использовать MCP

Используйте MCP, если внешний помощник должен:

• Обобщать записанный трафик.
• Анализировать и классифицировать результаты проверки безопасности.
• Составлять текст отчёта по доказательствам.
• Проверять рабочие процессы и сессии Replay.
• Готовить действия в заданной области, которые вы явно одобряете.

Для встроенного окна помощника используйте ИИ в рабочем пространстве.

Требования отдельного процесса

Используйте stdio, если клиент запускает локальный исполняемый файл вместо подключения к встроенному HTTP.

• Сервер Ogma, работающий по фактическому адресу API (по умолчанию CLI: http://127.0.0.1:8181)
• Бинарный файл ogma-mcp (собранный из исходников)

Сборка

cargo build --locked --bin ogma-mcp --release

Стандартный результат — target/release/ogma-mcp (ogma-mcp.exe на Windows), если целевой каталог Cargo не изменён.

Запуск

# Connect to Ogma running on the default port
./ogma-mcp

# Connect to a custom address
./ogma-mcp --api-url http://127.0.0.1:9090

# Use a larger body preview
./ogma-mcp --body-preview-bytes 2048

Сервер завершается, если API Ogma недоступен. Настройте клиент на запуск команды; stdout передаёт MCP, stderr — диагностику. Разрешения stdio задаются его флагами, а не настройками встроенного MCP.

Поиск инструментов

Текущий сервер всегда объявляет полный каталог. В настройках нет выбора профиля инструментов. Старые --tool-profile, --mcp-tool-profile и OGMA_MCP_TOOL_PROFILE принимаются для совместимости, но не скрывают инструменты и не выдают разрешения.

Для большого каталога начните с ogma_explain_capabilities и ogma_find_tools вместо угадывания входов. Найдите кандидатов по ключевым словам, затем запросите точное имя для изучения контракта. Диспетчеры браузера и поиска — удобные точки входа; отдельные инструменты остаются доступны напрямую. См. Поиск и диспетчеризация инструментов.

Настройки MCP в приложении

Пакетные сборки Ogma управляют MCP через Настройки > MCP. Используйте экран настроек для запуска и остановки встроенного процесса активного экземпляра.

Используйте отдельный ogma-mcp, если ИИ-клиент должен запускать сервер напрямую.

Сохранение настроек автоматически перезапускает работающий встроенный MCP. Переподключите клиентов; старые ID сессий и токены подтверждения недействительны. Диагностика выполнения показывает недавний вывод процесса.

Ogma также предоставляет управление через локальный REST API. Эти маршруты находятся на порту серверного API, а не выделенном порту MCP. Их используют настройки и встроенный мост ИИ:

Конечная точка	Назначение
GET /mcp/status	Возвращает { running, pid, endpoint, config, diagnostics }. endpoint равен null при остановке; диагностика содержит недавние { stream, message }.
POST /mcp/start	Запускает встроенный MCP с сохранёнными настройками и возвращает статус. Без тела. При уже работающем процессе возвращает конфликт.
POST /mcp/stop	Останавливает дочерний процесс MCP.
GET /settings/mcp	Возвращает сохранённую конфигурацию MCP.
PUT /settings/mcp	Принимает полный объект конфигурации, сохраняет и перезапускает работающий MCP. Возвращает принятую конфигурацию или ошибку. Только loopback-адреса.
GET /mcp/tools	Возвращает { tools, config }, включая inputSchema каждого инструмента. REST-каталог не разбит на страницы.
POST /mcp/tools/call	Вызывает инструмент с { "name": "ogma_explain_capabilities", "arguments": {} }. Возвращает { "result": "..." }; разберите текст как JSON-оболочку инструмента. Это не нативный результат MCP с блоками изображений.

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

При сбоях моста разбор result даёт { "error": "..." } с сериализованной оболочкой ошибки. Проверяйте значение, не считая успешный HTTP-статус успехом инструмента.

Сохранённая конфигурация по умолчанию:

{
  "bind_host": "127.0.0.1",
  "port": 3000,
  "allow_write_findings": false,
  "allow_export_data": false,
  "allow_read_secrets": false,
  "allow_send_requests": false,
  "allow_run_workflows": false,
  "allow_intercept_control": false,
  "tool_profile": "full"
}

Разрешены 127.0.0.1, localhost и ::1; порты от 1024 до 65535. Эта сборка не настраивает аутентификацию сетевого MCP, поэтому публичная привязка отклоняется. Устаревшие allow_public_bind и acknowledge_write_tool_risk не отменяют ограничение.

Claude Code

Для работающего десктопного адреса:

claude mcp add --transport http ogma http://127.0.0.1:3000/mcp

Если адрес другой, используйте показанный Ogma. Области конфигурации и stdio см. в настройке MCP Claude Code. Проверьте вопросом: «Какие проекты есть в Ogma?»

Cursor

Добавьте запись в .cursor/mcp.json проекта или пользовательский ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ogma": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Включите соединение в настройках MCP Cursor. См. документацию MCP Cursor.

Настройка клиента stdio

Клиенты, запускающие исполняемый файл, могут использовать эту запись, изменив расположение конфигурации по необходимости:

{
  "mcpServers": {
    "ogma": {
      "command": "/absolute/path/to/ogma-mcp",
      "args": ["--api-url", "http://127.0.0.1:8181"]
    }
  }
}

На Windows задайте полный путь и экранируйте обратные косые черты в JSON. Некоторые клиенты требуют "type": "stdio". Добавляйте флаги разрешений в args по необходимости.

Разрешения

Все шесть привилегированных возможностей по умолчанию отключены. Читайте текущие значения из ogma://mcp/permissions. Объявленный инструмент может отклонять выполнение до включения возможности. Полная таблица флагов и переменных — в справочнике CLI.

Взаимодействие с браузером, управление контекстами, переключение проектов и все вызовы сценариев аутентификации требуют --allow-send-requests. Инструменты наблюдения могут изучать уже работающий браузер без включения инструментов управления. --allow-read-secrets (или OGMA_MCP_ALLOW_READ_SECRETS=true) отдельно разрешает чтение незамаскированных значений переменных окружения.

У сервера нет поминутных или посессионных квот активности. Инструменты сохраняют ограничения входных и пакетных размеров, проверки области и тайм-ауты. Старые флаги квот отправки и рабочих процессов больше не поддерживаются.

Режим только чтения

По умолчанию сервер работает только для чтения. Без явного включения недоступны:

• Отправка запросов (Replay)
• Управление браузером, обходчиком, захватом аутентификации и активными пробами
• Запуск рабочих процессов
• Создание и изменение результатов
• Изменение области или правил замены
• Изменение и передача перехваченного трафика
• Удаление данных
• Доступ к секретным значениям переменных
• Экспорт данных

Предпросмотр тела по умолчанию — 512 байт. --body-preview-bytes меняет предпросмотр и должен быть не меньше 1; он не ограничивает вывод всех инструментов. Для полного HTTP-тела или целевого поиска используйте ogma_get_http_entry_body, для полного сообщения WebSocket — ogma_get_ws_message.

Инструменты записи результатов проверки безопасности

Для создания результатов проверки безопасности с ИИ перезапустите ogma-mcp с разрешением записи:

./ogma-mcp --allow-write-findings

Или задайте переменную:

OGMA_MCP_ALLOW_WRITE_FINDINGS=true ./ogma-mcp

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

Инструмент	Описание
ogma_preview_finding_from_evidence	Предпросмотр черновика по HTTP-записи (только чтение, всегда доступен)
ogma_create_finding	Создание с критичностью, статусом, тегами и доказательствами
ogma_update_finding	Обновление результата
ogma_add_finding_tag	Добавление тегов без замены существующих
ogma_link_finding_evidence	Привязка HTTP-записи, попытки Replay, результата Automate или сообщения WS
ogma_delete_finding	Удаление одного результата
ogma_export_findings_report	Отчёт HTML, Markdown или PDF

Текущая реализация также использует разрешение записи результатов для общих изменений: переменных, аннотаций истории, выбора области и Match & Replace. Эти действия см. в каталоге инструментов.

Пример создания результата с ИИ

С --allow-write-findings:

1. «Проанализируй HTTP-запись {id} на проблемы безопасности. Если найдёшь реальную проблему, задокументируй её через ogma_create_finding».
2. ИИ вызовет ogma_get_http_entry для просмотра запроса
3. Если доказательства подтверждают результат, вызовет ogma_create_finding с привязкой доказательств

Что недоступно только с записью результатов

• Отправка Replay
• Выполнение рабочих процессов
• Создание экспорта
• Управление очередью перехвата
• Переключение проектов

Инструменты экспорта

Для создания заданий экспорта с ИИ перезапустите ogma-mcp с разрешением:

./ogma-mcp --allow-export-data

Или задайте переменную:

OGMA_MCP_ALLOW_EXPORT_DATA=true ./ogma-mcp

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

Инструмент	Разрешение	Описание
ogma_preview_export_plan	Нет (чтение)	Предпросмотр состава экспорта
ogma_list_export_jobs	Нет (чтение)	Недавние задания
ogma_get_export_job	Нет (чтение)	Статус задания
ogma_get_export_download_info	Нет (чтение)	URL скачивания завершённого экспорта
ogma_create_export_job	export_data	Создание задания

Поддерживаемые виды и форматы

Вид	Описание	Форматы
http_history	Все HTTP-запросы через прокси	json, csv, raw_http
search	Отфильтрованные HTTP-запросы	json, csv, raw_http
findings	Результаты проверки безопасности	json, csv
automate_results	Результаты сессии Automate	json, csv

Примечание: raw_http допустим только для http_history и search.

Предупреждение безопасности

Файлы экспорта могут содержать полные тела HTTP-запросов и ответов с паролями, токенами и персональными данными. Обращайтесь с ними осторожно.

Что недоступно только с экспортом

• Удаление файлов экспорта
• Переименование файлов экспорта
• Потоковая передача экспорта через MCP
• Отправка Replay
• Выполнение рабочих процессов

Повторная отправка запросов

Предупреждение: это разрешает реальный исходящий HTTP-трафик через Ogma Replay.

Для включения:

./ogma-mcp --allow-send-requests

Или через переменную:

OGMA_MCP_ALLOW_SEND_REQUESTS=true ./ogma-mcp

Условия

1. Прокси Ogma должен работать
2. В разделе Область тестирования должна быть активная область для отправок Replay с проверкой области
3. Целевой хост должен входить в неё

Инструменты отправки

Инструмент	Разрешение	Описание
ogma_preview_replay_send	send_requests	Подготовка отправки и токен подтверждения
ogma_send_replay_request	send_requests	Отправка с токеном
ogma_create_replay_session_from_history	send_requests	Создание сессии Replay
ogma_create_replay_session_raw	send_requests	Сессия из определения запроса в полном HTTP-формате
ogma_browser_form_to_replay	send_requests	Сессия из формы на открытой странице
ogma_create_scope_preset	send_requests	Сохранение набора области; активация отдельно через ogma_set_active_scope
ogma_repeat_request	send_requests	Повтор записанного запроса с необязательными изменениями
ogma_replay_with_modifications	send_requests	Повтор с переопределением полей
ogma_http_request	send_requests	Прямой HTTP-запрос
ogma_fetch_url	send_requests	Загрузка URL со статусом, заголовками и предпросмотром
ogma_follow_redirect	send_requests	Цепочка перенаправлений с каждым переходом
ogma_bulk_send_requests	send_requests	Ограниченный пакет запросов
ogma_fuzz_parameter	send_requests	Замена значениями словаря
ogma_multipart_upload	send_requests	Multipart form-data для тестов загрузки
ogma_websocket_connect	send_requests	Подключение WebSocket и обмен сообщениями
ogma_login_replay_auto	send_requests	Отправка формы входа и захват профиля
ogma_auth_capture_profile	send_requests	Захват cookie, хранилищ, токенов и кандидатов CSRF
ogma_auth_apply_profile	send_requests	Применение профиля к браузеру
ogma_auth_refresh_csrf	send_requests	Обновление кандидатов CSRF из браузера
ogma_authz_matrix_test	send_requests	Повтор одного запроса с несколькими профилями
ogma_run_active_probe_workflow	send_requests	Ограниченные активные пробы конкретных уязвимостей
ogma_test_race	send_requests	Параллельная отправка запроса и ответы, с кодом статуса, отличающимся от наиболее частого
ogma_test_smuggling	send_requests	Пробы CL.TE и TE.CL напрямую через TCP
ogma_test_hpp	send_requests	Варианты загрязнения параметров HTTP
ogma_run_nuclei	send_requests	Запуск одного встроенного или заданного шаблона сканера для URL
ogma_browser_navigate и инструменты взаимодействия	send_requests	Управление браузером и запись трафика
ogma_crawl_site	send_requests	Обход цели в области через браузер
ogma_get_replay_session	Нет	Метаданные сессии
ogma_get_replay_attempt	Нет	Метаданные попытки
ogma_list_replay_sessions	Нет	Список сессий

Двухшаговый рабочий процесс

Пара Replay с подтверждением использует два вызова:

1. ogma_preview_replay_send — проверка запроса и получение токена
2. ogma_send_replay_request — подтверждение и отправка с токеном

Токены истекают через 5 минут, одноразовые и принадлежат создавшей их сессии MCP. Повторите предпросмотр после изменения запроса или перезапуска MCP. Это правило не применяется ко всем отправкам: прямой HTTP, помощники повтора и браузер могут отправлять сразу после включения.

Пример сессии

Пользователь: Повтори HTTP-запись abc123 и проверь ответ
ИИ: (вызывает ogma_preview_replay_send с http_entry_id="abc123")
    - показывает предпросмотр запроса, токен подтверждения и состояние области --
ИИ: (вызывает ogma_send_replay_request с confirmation_token и request_hash)
    - показывает статус ответа, время и предпросмотр ответа --

Что недоступно только с отправкой запросов

• Выполнение рабочих процессов
• Создание или обновление результатов
• Удаление

Перед включением этих инструментов задайте узкую активную область. Проверки области действуют в тех механизмах отправки, где предусмотрен этот контроль; область не является универсальным межсетевым экраном для произвольного JavaScript браузера или всех инструментов прямой загрузки URL.

Управление перехватом

Предупреждение: управление позволяет MCP-клиенту передавать, отбрасывать и менять текущий трафик, удерживаемый в очереди перехвата Ogma.

Для включения:

./ogma-mcp --allow-intercept-control

Или через переменную:

OGMA_MCP_ALLOW_INTERCEPT_CONTROL=true ./ogma-mcp

Инструменты перехвата

Инструмент	Разрешение	Описание
ogma_get_intercept_status	intercept_control	Состояния перехвата запросов, ответов и WebSocket
ogma_set_intercept_enabled	intercept_control	Включение и отключение режимов
ogma_list_intercept_queue	intercept_control	Список удерживаемых элементов
ogma_get_intercept_item	intercept_control	Просмотр элемента
ogma_forward_intercept_item	intercept_control	Передача с необязательными изменениями
ogma_drop_intercept_item	intercept_control	Отбрасывание
ogma_intercept_and_modify	intercept_control	Ожидание подходящего элемента, изменение и передача

Выполнение сценариев

Предупреждение: выполнение запускает логику рабочего процесса. Некоторые рабочие процессы отправляют HTTP или создают результаты.

Для включения:

./ogma-mcp --allow-run-workflows

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

Инструмент	Разрешение	Описание
ogma_get_workflow_safety	Нет (чтение)	Классификация побочных эффектов
ogma_preview_workflow_run	run_workflows	Предпросмотр и токен
ogma_run_workflow	run_workflows	Выполнение с токеном
ogma_cancel_workflow_run	run_workflows	Отмена активного рабочего процесса

Для предпросмотра задайте workflow_id и input для Convert либо trigger_entry_id для записанного входа активного рабочего процесса. Запускайте с полученными confirmation_token и definition_hash; Convert также требует input_hash и тот же input. Токены истекают через пять минут и одноразовые. Читайте результат через ogma_get_workflow_run.

Automate выполняется через инструменты сессий и запусков с разрешением отправки запросов, а не запуска рабочих процессов. Список и просмотр существующих запусков не требуют отправки.

Сочетания разрешений

Рабочие процессы с sdk.requests.send также требуют --allow-send-requests. Рабочие процессы с sdk.findings.create также требуют --allow-write-findings.

Обнаружение основано на статическом анализе текста — см. пояснение ниже.

Пояснение к классификации безопасности

Классификация изучает текст JavaScript на шаблоны вроде sdk.requests.send. Обнаружение не исчерпывающее: замаскированные или динамически построенные вызовы могут остаться незамеченными. Всегда проверяйте исходники JavaScript перед запуском недоверенного рабочего процесса.

Что недоступно только с рабочими процессами

• Ручной запуск пассивного рабочего процесса
• Удаление
• Изменение переменных окружения

Примеры запросов

После подключения:

• «Покажи последние 20 HTTP-запросов к example.com»
• «Есть ли в проекте результаты проверки безопасности с высокой или критической критичностью?»
• «Какие рабочие процессы сейчас включены?»
• «Проверь корректность HTTPQL req.method.eq:\"POST\"»
• «Обобщи состояние безопасности текущего проекта»
• «Проанализируй HTTP-запись {id} на проблемы безопасности»

Решение проблем

Соединение отклонено: сначала запустите Ogma (ogma --data-dir ./ogma-data).

Клиент не показывает инструменты: проверьте транспортный URL или путь исполняемого файла. Клиенты должны проходить все курсоры tools/list; страница содержит до 40 инструментов. Проверьте фильтрацию клиента и наличие инструмента в установленном релизе.

Недействительная сессия или токен: переподключитесь после перезапуска и создайте новый токен предпросмотра.

Браузер недоступен или действие не удалось: держите десктопное приложение запущенным. Проверьте ogma_browser_health, диалоги и восстановление браузера. Один сервер без интерфейса не предоставляет десктопный мост.

Скриншот без читаемого текста: используйте клиент с нативными изображениями MCP или семантический снимок.

Пустые результаты: сначала запишите трафик. Откройте страницы с прокси, настроенным на Ogma.