---
url: https://docs.ogmabox.com/ko/mcp-setup.md
description: >-
  Streamable HTTP 또는 stdio로 AI 에이전트를 Ogma에 연결하고, 권한을 설정하며, 로컬 MCP 관리 엔드포인트를
  사용합니다.
---

# Ogma MCP 서버 설정 {#ogma-mcp-server-setup}

Ogma MCP 서버(`ogma-mcp`)를 사용하면 호환되는 AI 어시스턴트가 프로젝트 컨텍스트를 확인할 수 있으며, 관련 기능을 활성화하면 내장 브라우저 제어, 요청 전송, 워크플로 실행 및 증거 수집도 할 수 있습니다. 메모/할 일 도구는 메모리에 저장되는 MCP 세션용 임시 메모장이며, 앱의 영구 저장 메모 페이지와 별개입니다.

MCP는 Codex, Claude Code, Cursor 및 기타 Model Context Protocol 클라이언트 같은 외부 도구를 위한 기능입니다. 앱 내 작업 공간 AI 어시스턴트와는 다른 기능입니다.

전체 리소스 및 도구 목록은 [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` | 독립 실행 MCP의 `--api-url`과 아래 관리/브리지 라우트에 사용합니다. |
| 프록시 리스너 | `127.0.0.1:8080` | 브라우저 트래픽을 캡처하며, MCP 엔드포인트가 아닙니다. |

데스크톱 인스턴스는 백엔드 API 포트를 동적으로 할당할 수 있습니다. stdio/REST 통합에는 실제 실행 중인 인스턴스의 주소를 사용하고, 네이티브 MCP에는 설정에 표시된 엔드포인트를 사용하세요. 로컬 클라이언트/커넥터 없이는 클라우드 채팅 서비스가 루프백 주소에 접근할 수 없습니다.

HTTP 엔드포인트는 상태를 유지하므로 초기화와 세션 헤더 처리는 클라이언트에 맡기세요. 별도의 레거시 `/sse` 엔드포인트는 없습니다. 사용자 지정 클라이언트는 MCP [전송 명세](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)를 따라야 합니다.

## MCP를 사용하는 경우 {#when-to-use-mcp}

외부 어시스턴트의 도움으로 다음 작업을 수행하려면 MCP를 사용하세요.

* 캡처된 트래픽 요약.
* 발견 사항 분류 및 우선순위 평가.
* 증거에 기반한 보고서 문안 작성.
* 워크플로 및 재전송 세션 검토.
* 명시적으로 승인할 범위 내 작업 준비.

Ogma 내부의 내장 어시스턴트 창을 사용하려면 [작업 공간 AI](./guide/workspace-ai.md)를 사용하세요.

## 독립 실행 요구 사항 {#standalone-requirements}

클라이언트가 내장 HTTP 엔드포인트에 연결하는 대신 로컬 실행 파일을 시작해야 하는 경우 stdio를 사용하세요.

* 실제 API 주소에서 실행 중인 Ogma 백엔드(CLI 기본값: `http://127.0.0.1:8181`)
* `ogma-mcp` 바이너리(소스에서 빌드)

## 빌드 {#build}

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

Cargo 대상 디렉터리를 별도로 설정하지 않았다면 기본 출력은 `target/release/ogma-mcp`입니다(Windows에서는 `ogma-mcp.exe`).

## 실행 {#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
```

Ogma API에 연결할 수 없으면 서버가 종료됩니다. MCP 클라이언트가 이 명령을 실행하도록 설정하세요. 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를 관리할 수 있습니다. 활성 인스턴스의 내장 MCP 프로세스를 Ogma가 시작하거나 중지하도록 하려면 설정 화면을 사용하세요.

AI 클라이언트가 MCP 서버를 직접 실행하는 방식이라면 독립 실행 `ogma-mcp` 바이너리를 사용하세요.

설정을 저장하면 실행 중인 내장 MCP 프로세스가 자동으로 재시작됩니다. 이후 클라이언트를 다시 연결하세요. 이전 세션 ID와 확인 토큰은 재사용할 수 없습니다. **런타임 진단**에는 최근 프로세스 출력이 표시됩니다.

Ogma는 로컬 REST API를 통해서도 MCP 관리 기능을 제공합니다. 이 라우트는 전용 MCP 포트가 아닌 **백엔드 API 포트**에 있으며, 설정 화면과 앱 내 AI 브리지에서 사용합니다.

| 엔드포인트 | 용도 |
| --- | --- |
| `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가 실행 중이면 재시작합니다. 수락된 설정 또는 오류를 반환합니다. 루프백 바인딩 호스트만 허용됩니다. |
| `GET /mcp/tools` | 각 도구의 `inputSchema`를 포함한 `{ tools, config }`를 반환합니다. 이 REST 도구 목록은 페이지로 나뉘지 않습니다. |
| `POST /mcp/tools/call` | `{ "name": "ogma_explain_capabilities", "arguments": {} }`로 도구 하나를 호출합니다. `{ "result": "..." }`를 반환하며, 이 텍스트를 도구의 JSON 응답 형식으로 파싱하세요. 이미지 블록을 포함하는 네이티브 MCP 결과가 아닙니다. |

REST 브리지는 저장된 권한을 사용하지만 별도의 HTTP MCP 자식 프로세스를 시작할 필요는 없습니다. 백엔드/설정에 대해 하나의 브리지 세션을 공유합니다. 격리된 클라이언트 세션과 이미지 출력에는 네이티브 MCP를 권장합니다.

브리지 호출이 실패하면 `result`를 파싱한 값은 직렬화된 오류 응답을 담은 `{ "error": "..." }`입니다. HTTP 성공 상태를 도구 성공으로 간주하지 말고 이 값을 확인하세요.

기본 저장 MCP 설정:

```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 옵션은 [Claude Code의 MCP 설정](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"
    }
  }
}
```

Cursor의 MCP 설정에서 연결을 활성화하세요. [Cursor의 MCP 문서](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}

MCP 서버는 기본적으로 읽기 전용입니다. 명시적으로 활성화하지 않으면 다음 작업을 사용할 수 없습니다.

* 요청 전송(재전송)
* 내장 브라우저, 크롤러, 인증 캡처 및 능동형 프로브 도우미 제어
* 워크플로 실행
* 발견 사항 생성 또는 수정
* 점검 범위 또는 찾아 바꾸기 규칙 수정
* 가로챈 트래픽 수정 또는 전달
* 데이터 삭제
* 비밀 환경 변수 값 접근
* 데이터 내보내기

본문 미리보기 기본값은 512바이트입니다. `--body-preview-bytes`로 미리보기를 조정할 수 있으며 최솟값은 1입니다. 모든 도구의 출력 크기를 제한하는 것은 아닙니다. 전체 HTTP 본문 또는 특정 본문 검색에는 `ogma_get_http_entry_body`를, 전체 WebSocket 메시지에는 `ogma_get_ws_message`를 사용하세요.

## 발견 사항 쓰기 도구 {#finding-write-tools}

AI를 통한 발견 사항 생성을 활성화하려면 쓰기 권한으로 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 항목, 재전송 시도, 자동화 결과 또는 WS 메시지를 발견 사항에 연결 |
| `ogma_delete_finding` | 발견 사항 하나 삭제 |
| `ogma_export_findings_report` | HTML, Markdown 또는 PDF 보고서 생성 |

현재 구현에서는 환경 변수 업데이트, 기록 주석, 점검 범위 선택 및 찾아 바꾸기 변경 같은 공용 쓰기 도구에도 발견 사항 쓰기 권한을 사용합니다. 해당 작업은 [도구 목록](./reference/mcp-tools.md)을 확인하세요.

### 예제: AI를 통한 발견 사항 생성 {#example-ai-assisted-finding-creation}

`--allow-write-findings` 사용 시:

1. "HTTP 항목 {id}의 보안 문제를 분석해 줘. 실제 문제가 발견되면 ogma\_create\_finding으로 기록해 줘."
2. AI가 `ogma_get_http_entry`를 호출하여 요청을 확인합니다.
3. 증거가 발견 사항을 뒷받침하면 증거를 연결하여 `ogma_create_finding`을 호출합니다.

### 발견 사항 쓰기 권한만으로는 사용할 수 없는 기능 {#still-not-available-with-finding-writes-only}

* 재전송 요청 전송
* 워크플로 실행
* 내보내기 생성
* 가로채기 대기열 제어
* 프로젝트 전환

## 내보내기 도구 {#export-tools}

AI를 통한 내보내기 작업 생성을 활성화하려면 내보내기 권한으로 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` | 자동화 세션 결과 | json, csv |

참고: `raw_http` 형식은 `http_history` 및 `search` 종류에만 사용할 수 있습니다.

### 보안 경고 {#security-warning}

내보낸 파일에는 전체 HTTP 요청 및 응답 본문이 포함될 수 있으며, 비밀번호, 토큰 및 개인 정보가 들어 있을 수 있습니다. 내보낸 파일은 적절한 주의를 기울여 취급하세요.

### 내보내기 권한만으로는 사용할 수 없는 기능 {#still-not-available-with-export-permissions-only}

* 내보낸 파일 삭제
* 내보낸 파일 이름 변경
* MCP를 통한 내보내기 내용 스트리밍
* 재전송 요청 전송
* 워크플로 실행

## 재전송 요청 보내기 {#replay-request-sending}

경고: 이 기능을 활성화하면 Ogma 재전송을 통해 실제 외부 HTTP 트래픽을 보낼 수 있습니다.

활성화 방법:

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

또는 환경 변수 사용:

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

### 사전 요구 사항 {#prerequisites}

1. Ogma 프록시가 실행 중이어야 합니다.
2. 보호된 재전송 요청을 보내려면 **점검 범위**에 활성 범위가 설정되어 있어야 합니다.
3. 대상 호스트가 활성 범위 안에 있어야 합니다.

### 전송 도구 {#send-tools}

| 도구 | 권한 | 설명 |
|------|-----------|-------------|
| `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 | `{{FUZZ}}` 자리표시자를 단어 목록의 값으로 대체 |
| `ogma_multipart_upload` | send\_requests | 업로드 테스트용 multipart form-data 요청 전송 |
| `ogma_websocket_connect` | send\_requests | WebSocket URL에 연결하고 메시지 교환 |
| `ogma_login_replay_auto` | send\_requests | 브라우저 로그인 폼을 제출하고 인증 프로필 캡처 |
| `ogma_auth_capture_profile` | send\_requests | 브라우저 쿠키, 저장소, 인증 토큰 및 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 | 원시 TCP를 통해 CL.TE 및 TE.CL 요청 동기화 불일치 프로브 전송 |
| `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}

확인 기반 재전송 도구 쌍은 두 번의 호출을 사용합니다.

1. `ogma_preview_replay_send` - 요청을 검토하고 확인 토큰을 받습니다.
2. `ogma_send_replay_request` - 토큰으로 확인 후 전송합니다.

확인 토큰은 5분 후 만료되고 한 번만 사용할 수 있으며, 생성한 MCP 세션에 속합니다. 요청을 변경하거나 MCP를 재시작한 후에는 다시 미리보기를 수행하세요. 이 두 단계 규칙은 모든 전송 도구에 적용되지 않습니다. 직접 HTTP 도구, 반복 도우미 및 브라우저 동작은 활성화되면 즉시 전송할 수 있습니다.

### 세션 예제 {#example-session}

```
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 --
```

### 요청 전송 권한만으로는 사용할 수 없는 기능 {#still-not-available-with-request-sending-permissions-only}

* 워크플로 실행
* 발견 사항 생성 또는 업데이트
* 삭제

이 도구를 활성화하기 전에 활성 점검 범위를 좁게 유지하세요. 범위 확인은 보호된 전송 경로에 적용됩니다. 범위를 임의의 브라우저 JavaScript나 모든 직접 가져오기 도우미에 적용되는 범용 방화벽으로 간주하지 마세요.

## 가로채기 제어 {#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` 또는 캡처된 능동형 워크플로 입력의 `trigger_entry_id`를 사용합니다. 반환된 `confirmation_token`과 `definition_hash`로 실행하며, 변환 워크플로에는 `input_hash`와 동일한 `input`도 필요합니다. 토큰은 오 분 후 만료되며 한 번만 사용할 수 있습니다. 실행 결과는 `ogma_get_workflow_run`으로 읽습니다.

자동화 실행은 세션/실행 도구를 통해 사용할 수 있으며, 워크플로 실행 권한이 아닌 **요청 전송 권한**이 필요합니다. 기존 실행 기록을 조회하거나 확인하는 데 전송 권한은 필요하지 않습니다.

### 추가로 필요한 권한 {#cross-permission-requirements}

`sdk.requests.send`를 사용하는 워크플로에는 `--allow-send-requests`도 필요합니다.
`sdk.findings.create`를 사용하는 워크플로에는 `--allow-write-findings`도 필요합니다.

감지는 정적 텍스트 분석에 기반합니다. 아래 주의 사항을 확인하세요.

### 안전성 분류 관련 주의 사항 {#safety-classification-advisory-note}

워크플로 안전성 분류는 JavaScript 소스 코드 텍스트에서 `sdk.requests.send` 같은 패턴을 확인합니다. 이 감지는 완전하지 않으며, 난독화되거나 동적으로 구성된 SDK 메서드 호출을 감지하지 못할 수 있습니다. 신뢰할 수 없는 워크플로를 실행하기 전에 반드시 워크플로 JavaScript 소스를 검토하세요.

### 워크플로 권한만으로는 사용할 수 없는 기능 {#still-not-available-with-workflow-permissions-only}

* 수동형 워크플로의 수동 실행
* 삭제
* 환경 변수 변경

## 프롬프트 예제 {#example-prompts}

연결 후:

* "example.com으로 보낸 최근 20개의 HTTP 요청을 보여 줘"
* "이 프로젝트에 심각도가 높음 또는 치명적인 발견 사항이 있나요?"
* "현재 활성화된 워크플로는 무엇인가요?"
* "HTTPQL 쿼리 `req.method.eq:\"POST\"`가 유효한지 확인해 줘"
* "현재 프로젝트의 보안 상태를 요약해 줘"
* "HTTP 항목 {id}의 보안 문제를 분석해 줘"

## 문제 해결 {#troubleshooting}

**연결 거부:** 먼저 Ogma를 시작하세요(`ogma --data-dir ./ogma-data`).

**MCP 클라이언트에 도구가 표시되지 않음:** 전송 URL 또는 실행 파일 경로를 확인하세요. 클라이언트는 모든 `tools/list` 커서를 따라야 하며, 각 페이지에는 최대 40개의 도구가 포함됩니다. 클라이언트 측 필터와 설치한 릴리스에 누락된 도구가 포함되어 있는지 확인하세요.

**세션 또는 확인 토큰이 유효하지 않음:** 재시작 후 다시 연결하고 새 미리보기 토큰을 생성하세요.

**브라우저를 사용할 수 없거나 동작 실패:** 데스크톱 앱을 실행 상태로 유지하세요. `ogma_browser_health`, 대화상자 및 [브라우저 복구](./guide/mcp-browser.md#recover-from-errors)를 확인하세요. 헤드리스 백엔드만으로는 데스크톱 브라우저 브리지가 제공되지 않습니다.

**스크린샷에 읽을 수 있는 텍스트가 없음:** 네이티브 MCP 이미지 콘텐츠를 지원하는 클라이언트를 사용하거나 의미 기반 스냅샷을 확인하세요.

**결과가 비어 있음:** 먼저 Ogma에서 트래픽을 캡처해야 합니다. 트래픽이 Ogma를 통해 전달되도록 프록시를 설정한 뒤 브라우저로 접속하세요.