Налаштування сервера Ogma MCP

Сервер Ogma MCP (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, коли зовнішній помічник має допомогти вам:

• Узагальнити перехоплений трафік.
• Оцінити й упорядкувати знахідки.
• Підготувати текст звіту на основі доказів.
• Переглянути робочі процеси й сеанси повторного надсилання.
• Підготувати дії в межах визначеної області, які ви явно схвалюєте.

Використовуйте ШІ робочого простору, якщо потрібне вбудоване вікно помічника в Ogma.

Вимоги для окремого запуску

Використовуйте 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. Налаштуйте клієнт MCP на запуск цієї команди; 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 для активного екземпляра.

Використовуйте окремий виконуваний файл ogma-mcp, якщо ШІ-клієнт має запускати сервер MCP безпосередньо.

Збереження налаштувань автоматично перезапускає активний вбудований процес MCP. Після цього перепідключіть клієнти; старі ідентифікатори сеансів і токени підтвердження не можна використати повторно. Діагностика виконання показує останні вихідні повідомлення процесу.

Ogma також надає керування MCP через локальний 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-статус успіхом інструмента.

Стандартна збережена конфігурація MCP:

{
  "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) окремо дозволяє отримувати незамасковані значення змінних середовища.

Сервер не має квот активності за хвилину чи за сеанс. Окремі інструменти все ж перевіряють розміри вхідних даних і пакетів, області тестування та тайм-аути. Старі прапорці квот надсилання й робочих процесів більше не підтримуються.

Режим лише для читання

За замовчуванням сервер MCP працює лише для читання. Ці операції недоступні, доки їх явно не дозволено:

• Надсилання запитів (Повторне надсилання)
• Керування вбудованим браузером, краулером, захопленням автентифікації та допоміжними засобами активних перевірок
• Виконання робочих процесів
• Створення або зміна знахідок
• Зміна областей тестування чи правил пошуку й заміни
• Зміна або пропускання перехопленого трафіку
• Видалення даних
• Доступ до секретних значень змінних середовища
• Експорт даних

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

Інструменти запису знахідок

Щоб дозволити створення знахідок за допомогою ШІ, перезапустіть 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-запису, спроби повторного надсилання, результату автоматизації або повідомлення WS до знахідки
ogma_delete_finding	Видалення однієї знахідки
ogma_export_findings_report	Генерування звіту HTML, Markdown або PDF

Поточна реалізація також використовує дозвіл запису знахідок для спільних інструментів запису, як-от оновлення змінних середовища, анотацій історії, вибору області тестування й змін правил пошуку та заміни. Про ці дії див. каталог інструментів.

Приклад: створення знахідки за допомогою ШІ

Із --allow-write-findings:

1. «Проаналізуй HTTP-запис {id} на проблеми безпеки. Якщо знайдеш справжню проблему, використай ogma_create_finding, щоб задокументувати її».
2. ШІ викличе ogma_get_http_entry, щоб переглянути запит
3. Якщо докази підтверджують знахідку, він викличе ogma_create_finding із прив’язаними доказами

Що залишається недоступним із самим дозволом запису знахідок

• Надсилання повторних запитів
• Виконання робочих процесів
• Створення експорту
• Керування чергою перехоплення
• Перемикання проєктів

Інструменти експорту

Щоб дозволити створення завдань експорту за допомогою ШІ, перезапустіть 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	Результати сеансу автоматизації	json, csv

Примітка: формат raw_http допустимий лише для видів http_history і search.

Попередження щодо безпеки

Файли експорту можуть містити повні тіла HTTP-запитів і відповідей, зокрема паролі, токени й персональні дані. Поводьтеся з файлами експорту з належною обережністю.

Що залишається недоступним із самим дозволом експорту

• Видалення файлів експорту
• Перейменування файлів експорту
• Потокове передавання вмісту експорту через MCP
• Надсилання повторних запитів
• Виконання робочих процесів

Надсилання повторних запитів

Попередження: це дозволяє надсилати справжній вихідний HTTP-трафік через розділ «Повторне надсилання» Ogma.

Щоб увімкнути:

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

Або через змінні середовища:

OGMA_MCP_ALLOW_SEND_REQUESTS=true ./ogma-mcp

Передумови

1. Проксі Ogma має працювати
2. Для повторного надсилання з перевірками безпеки в розділі Область тестування має бути налаштована активна область
3. Цільовий хост має належати до активної області тестування

Інструменти надсилання

Інструмент	Дозвіл	Опис
ogma_preview_replay_send	send_requests	Підготовка надсилання й отримання токена підтвердження
ogma_send_replay_request	send_requests	Надсилання з токеном підтвердження
ogma_create_replay_session_from_history	send_requests	Створення сеансу повторного надсилання
ogma_create_replay_session_raw	send_requests	Створення сеансу повторного надсилання з визначення необробленого запиту
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	Підключення до URL 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	Немає	Список сеансів повторного надсилання

Двоетапний процес

Пара повторного надсилання з підтвердженням використовує два виклики:

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

Токени підтвердження діють 5 хвилин, є одноразовими й належать сеансу MCP, який їх створив. Повторіть попередній перегляд після зміни запиту або перезапуску MCP. Це двоетапне правило не стосується кожного інструмента надсилання: прямі HTTP-інструменти, допоміжні засоби повторення й дії браузера можуть надсилати одразу, якщо дозволені.

Приклад сеансу

User: Resend HTTP entry abc123 and check the response
AI: (calls ogma_preview_replay_send with http_entry_id="abc123")
    - shows request preview, confirmation token, scope status --
AI: (calls ogma_send_replay_request with confirmation_token and request_hash)
    - shows response status, timing, response preview --

Що залишається недоступним із самим дозволом надсилання запитів

• Виконання робочих процесів
• Створення або оновлення знахідок
• Видалення

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

Керування перехопленням

Попередження: керування перехопленням дає клієнту 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 для робочого процесу перетворення або trigger_entry_id для перехоплених вхідних даних активного робочого процесу. Запускайте з отриманими confirmation_token і definition_hash; для робочих процесів перетворення також потрібні input_hash і ті самі input. Токени діють п’ять хвилин і є одноразовими. Прочитайте результат виконання через ogma_get_workflow_run.

Виконання автоматизації доступне через її інструменти сеансів і запусків із дозволом надсилання запитів, а не дозволом виконання робочих процесів. Перегляд списку й наявних виконань не потребує дозволу надсилання.

Вимоги до кількох дозволів

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

Виявлення ґрунтується на статичному аналізі тексту — див. застереження нижче.

Застереження щодо класифікації безпеки

Класифікація безпеки робочих процесів перевіряє текст вихідного коду JavaScript на шаблони на кшталт sdk.requests.send. Це виявлення не є вичерпним: обфусковані або динамічно сформовані виклики методів SDK можуть залишитися непоміченими. Завжди переглядайте вихідний код JavaScript перед запуском робочих процесів із недовірених джерел.

Що залишається недоступним із самим дозволом робочих процесів

• Ручний запуск пасивного робочого процесу
• Видалення
• Зміна змінних середовища

Приклади запитів

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

• «Покажи останні 20 HTTP-запитів до example.com»
• «Чи є в цьому проєкті знахідки високого або критичного рівня критичності?»
• «Які робочі процеси зараз увімкнено?»
• «Перевір, чи допустимий запит HTTPQL req.method.eq:\"POST\"»
• «Підсумуй стан безпеки поточного проєкту»
• «Проаналізуй HTTP-запис {id} на проблеми безпеки»

Усунення проблем

У підключенні відмовлено: спочатку запустіть Ogma (ogma --data-dir ./ogma-data).

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

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

Браузер недоступний або дія не вдалася: тримайте настільну програму запущеною. Перевірте ogma_browser_health, діалогові вікна та відновлення браузера. Сам бекенд без графічного інтерфейсу не надає мосту настільного браузера.

На знімку екрана немає читабельного тексту: використовуйте клієнт із підтримкою нативного вмісту зображень MCP або перегляньте семантичний знімок.

Порожні результати: Ogma спочатку має перехопити трафік. Переглядайте сайти з проксі, налаштованим на пересилання трафіку через Ogma.