---
url: https://docs.ogmabox.com/ru/mcp-setup.md
description: >-
  Подключайте ИИ-агентов к Ogma через Streamable HTTP или stdio, настраивайте
  разрешения и используйте локальные конечные точки управления MCP.
---

# Настройка MCP-сервера Ogma {#ogma-mcp-server-setup}

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

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

Полный список см. в [Ресурсы и инструменты MCP](./reference/mcp-tools.md).

## Быстрый старт: десктопное приложение {#quick-start-desktop-app}

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

Отдельная сборка бинарного файла не нужна. Переходы, формы, сценарии входа и диагностику см. в [Автоматизация браузера через MCP](./guide/mcp-browser.md).

### Адреса подключения {#connection-addresses}

| Интерфейс | Адрес по умолчанию | Назначение |
| --- | --- | --- |
| Транспорт 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](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports).

## Когда использовать MCP {#when-to-use-mcp}

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

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

Для встроенного окна помощника используйте [ИИ в рабочем пространстве](./guide/workspace-ai.md).

## Требования отдельного процесса {#standalone-requirements}

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

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

## Сборка {#build}

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

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

## Запуск {#run}

```bash
# 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-discovery}

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

Для большого каталога начните с `ogma_explain_capabilities` и `ogma_find_tools` вместо угадывания входов. Найдите кандидатов по ключевым словам, затем запросите точное имя для изучения контракта. Диспетчеры браузера и поиска — удобные точки входа; отдельные инструменты остаются доступны напрямую. См. [Поиск и диспетчеризация инструментов](./reference/mcp-tools.md#tool-discovery-and-dispatch).

## Настройки MCP в приложении {#in-app-mcp-settings}

Пакетные сборки 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-статус успехом инструмента.

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

```json
{
  "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-code}

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

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

Если адрес другой, используйте показанный Ogma. Области конфигурации и stdio см. в [настройке MCP Claude Code](https://code.claude.com/docs/en/mcp). Проверьте вопросом: «Какие проекты есть в Ogma?»

## Cursor {#cursor}

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

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

Включите соединение в настройках MCP Cursor. См. [документацию MCP Cursor](https://cursor.com/docs/mcp).

### Настройка клиента stdio {#stdio-client-configuration}

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

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

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

## Разрешения {#permissions}

Все шесть привилегированных возможностей по умолчанию отключены. Читайте текущие значения из `ogma://mcp/permissions`. Объявленный инструмент может отклонять выполнение до включения возможности. Полная таблица флагов и переменных — в [справочнике CLI](./reference/cli.md#standalone-ogma-mcp-flags).

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

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

## Режим только чтения {#read-only-mode}

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

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

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

## Инструменты записи результатов проверки безопасности {#finding-write-tools}

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

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

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

```bash
OGMA_MCP_ALLOW_WRITE_FINDINGS=true ./ogma-mcp
```

### Доступные инструменты записи {#write-tools-available}

| Инструмент | Описание |
|------|-------------|
| `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. Эти действия см. в [каталоге инструментов](./reference/mcp-tools.md).

### Пример создания результата с ИИ {#example-ai-assisted-finding-creation}

С `--allow-write-findings`:

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

### Что недоступно только с записью результатов {#still-not-available-with-finding-writes-only}

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

## Инструменты экспорта {#export-tools}

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

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

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

```bash
OGMA_MCP_ALLOW_EXPORT_DATA=true ./ogma-mcp
```

### Доступные инструменты экспорта {#export-tools-available}

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

### Поддерживаемые виды и форматы {#supported-export-kinds-and-formats}

| Вид | Описание | Форматы |
|------|-------------|---------|
| `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`.

### Предупреждение безопасности {#security-warning}

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

### Что недоступно только с экспортом {#still-not-available-with-export-permissions-only}

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

## Повторная отправка запросов {#replay-request-sending}

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

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

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

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

```bash
OGMA_MCP_ALLOW_SEND_REQUESTS=true ./ogma-mcp
```

### Условия {#prerequisites}

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

### Инструменты отправки {#send-tools}

| Инструмент | Разрешение | Описание |
|------|-----------|-------------|
| `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 | Замена `{{FUZZ}}` значениями словаря |
| `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` | Нет | Список сессий |

### Двухшаговый рабочий процесс {#two-step-workflow}

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

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

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

### Пример сессии {#example-session}

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

### Что недоступно только с отправкой запросов {#still-not-available-with-request-sending-permissions-only}

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

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

## Управление перехватом {#intercept-control}

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

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

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

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

```bash
OGMA_MCP_ALLOW_INTERCEPT_CONTROL=true ./ogma-mcp
```

### Инструменты перехвата {#intercept-tools}

| Инструмент | Разрешение | Описание |
|------|-----------|-------------|
| `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 | Ожидание подходящего элемента, изменение и передача |

## Выполнение сценариев {#workflow-execution}

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

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

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

### Инструменты выполнения {#workflow-execution-tools}

| Инструмент | Разрешение | Описание |
|------|-----------|-------------|
| `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 выполняется через инструменты сессий и запусков с **разрешением отправки запросов**, а не запуска рабочих процессов. Список и просмотр существующих запусков не требуют отправки.

### Сочетания разрешений {#cross-permission-requirements}

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

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

### Пояснение к классификации безопасности {#safety-classification-advisory-note}

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

### Что недоступно только с рабочими процессами {#still-not-available-with-workflow-permissions-only}

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

## Примеры запросов {#example-prompts}

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

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

## Решение проблем {#troubleshooting}

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

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

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

**Браузер недоступен или действие не удалось:** держите десктопное приложение запущенным. Проверьте `ogma_browser_health`, диалоги и [восстановление браузера](./guide/mcp-browser.md#recover-from-errors). Один сервер без интерфейса не предоставляет десктопный мост.

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

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