---
url: https://docs.ogmabox.com/vi/mcp-setup.md
description: >-
  Kết nối tác nhân AI với Ogma qua Streamable HTTP hoặc stdio, cấu hình quyền và
  sử dụng các điểm cuối quản lý MCP cục bộ.
---

# Thiết lập máy chủ MCP của Ogma {#ogma-mcp-server-setup}

Máy chủ MCP của Ogma (`ogma-mcp`) cho phép các trợ lý AI tương thích xem xét ngữ cảnh dự án và, khi được bật, điều khiển trình duyệt tích hợp, gửi yêu cầu, chạy quy trình và thu thập bằng chứng. Các công cụ ghi chú và việc cần làm là sổ nháp trong bộ nhớ của phiên MCP, tách biệt với trang Ghi chú được lưu bền vững của ứng dụng.

MCP dành cho các công cụ bên ngoài như Codex, Claude Code, Cursor và các máy khách Model Context Protocol khác. Đây không phải cùng một tính năng với trợ lý AI không gian làm việc trong ứng dụng.

Để xem danh sách đầy đủ các tài nguyên và công cụ, hãy xem [Tài nguyên và công cụ MCP](/vi/reference/mcp-tools.md).

## Bắt đầu nhanh: ứng dụng máy tính {#quick-start-desktop-app}

1. Khởi động Ogma và mở dự án mà tác nhân cần xem xét.
2. Mở **Cài đặt > MCP**, chọn các quyền cần thiết và lưu. Tương tác với trình duyệt yêu cầu quyền **Gửi từ Replay**.
3. Nhấp **Bắt đầu** và sao chép điểm cuối được hiển thị, thường là `http://127.0.0.1:3000/mcp`.
4. Thêm điểm cuối này vào máy khách MCP dưới dạng máy chủ **Streamable HTTP**.
5. Yêu cầu tác nhân gọi `ogma_explain_capabilities` và đọc `ogma://project/current` để kiểm tra kết nối và dự án đang hoạt động.

Cách này không cần biên dịch một tệp thực thi riêng. Để tìm hiểu cách điều hướng trang, sử dụng biểu mẫu, các hành trình đăng nhập và khắc phục sự cố, hãy xem [Tự động hóa trình duyệt với MCP](/vi/guide/mcp-browser.md).

### Địa chỉ kết nối {#connection-addresses}

| Giao diện | Địa chỉ mặc định | Mục đích |
| --- | --- | --- |
| Kênh truyền MCP | `http://127.0.0.1:3000/mcp` | Máy khách MCP gốc kết nối tại đây. |
| API REST của backend | `http://127.0.0.1:8181` | `--api-url` của MCP độc lập và các tuyến quản lý/cầu nối bên dưới. |
| Bộ lắng nghe proxy | `127.0.0.1:8080` | Thu lưu lượng trình duyệt; đây không phải điểm cuối MCP. |

Các phiên proxy của ứng dụng máy tính có thể gán động cổng API của backend. Hãy dùng địa chỉ thực tế của phiên proxy đang chạy cho tích hợp stdio/REST và điểm cuối hiển thị trong Cài đặt cho MCP gốc. Dịch vụ trò chuyện trên đám mây không thể truy cập địa chỉ loopback của bạn nếu không có máy khách hoặc trình kết nối cục bộ.

Điểm cuối HTTP có trạng thái: hãy để máy khách xử lý khởi tạo và các header phiên. Không có điểm cuối cũ `/sse` riêng biệt. Máy khách tùy chỉnh cần tuân theo [đặc tả kênh truyền](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) của MCP.

## Khi nào nên dùng MCP {#when-to-use-mcp}

Dùng MCP khi bạn cần trợ lý bên ngoài hỗ trợ:

* Tóm tắt lưu lượng đã thu.
* Phân loại và ưu tiên các phát hiện.
* Soạn nội dung báo cáo dựa trên bằng chứng.
* Xem xét quy trình và phiên Replay.
* Chuẩn bị các hành động trong phạm vi mà bạn phê duyệt rõ ràng.

Hãy dùng [AI không gian làm việc](/vi/guide/workspace-ai.md) nếu bạn muốn sử dụng cửa sổ trợ lý tích hợp bên trong Ogma.

## Yêu cầu cho máy chủ độc lập {#standalone-requirements}

Dùng stdio khi máy khách cần khởi chạy một tệp thực thi cục bộ thay vì kết nối với điểm cuối HTTP tích hợp.

* Backend Ogma đang chạy tại địa chỉ API thực tế (mặc định của CLI: `http://127.0.0.1:8181`)
* Tệp thực thi `ogma-mcp` (được biên dịch từ mã nguồn)

## Biên dịch {#build}

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

Đầu ra mặc định là `target/release/ogma-mcp` (`ogma-mcp.exe` trên Windows), trừ khi bạn tùy chỉnh thư mục đích của Cargo.

## Chạy {#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
```

Máy chủ thoát nếu không thể truy cập API của Ogma. Cấu hình máy khách MCP để khởi chạy lệnh này; stdout truyền các thông điệp MCP và stderr chứa thông tin chẩn đoán. Quyền của stdio đến từ các cờ riêng, không phải cài đặt MCP tích hợp.

## Khám phá công cụ {#tool-discovery}

Máy chủ hiện tại luôn công bố toàn bộ danh mục công cụ. Không có bộ chọn hồ sơ công cụ trong Cài đặt. Các giá trị cũ `--tool-profile`, `--mcp-tool-profile` và `OGMA_MCP_TOOL_PROFILE` được chấp nhận để tương thích nhưng không ẩn công cụ hay cấp quyền.

Với danh mục lớn, hãy bắt đầu bằng `ogma_explain_capabilities` và `ogma_find_tools` thay vì đoán đầu vào. Tìm kiếm theo từ khóa tác vụ để chọn công cụ phù hợp, sau đó truy vấn tên chính xác của công cụ để xem đặc tả cách gọi. Các bộ điều phối trình duyệt và tìm kiếm cung cấp điểm vào thuận tiện; công cụ chuyên biệt vẫn có thể được gọi trực tiếp. Xem [Khám phá và điều phối công cụ](/vi/reference/mcp-tools.md#tool-discovery-and-dispatch).

## Cài đặt MCP trong ứng dụng {#in-app-mcp-settings}

Các bản Ogma đóng gói có thể quản lý MCP từ **Cài đặt > MCP**. Dùng màn hình cài đặt khi bạn muốn Ogma khởi động hoặc dừng tiến trình MCP tích hợp cho phiên proxy đang hoạt động.

Dùng tệp thực thi độc lập `ogma-mcp` khi máy khách AI cần trực tiếp khởi chạy máy chủ MCP.

Lưu cài đặt sẽ tự động khởi động lại tiến trình MCP tích hợp đang chạy. Sau đó hãy kết nối lại máy khách; không thể dùng lại ID phiên và token xác nhận cũ. **Chẩn đoán khi chạy** hiển thị đầu ra gần đây của tiến trình.

Ogma cũng cung cấp khả năng quản lý MCP qua API REST cục bộ. Các tuyến này nằm trên **cổng API của backend**, không phải cổng MCP chuyên dụng. Màn hình cài đặt và cầu nối AI trong ứng dụng sử dụng chúng:

| Điểm cuối | Mục đích |
| --- | --- |
| `GET /mcp/status` | Trả về `{ running, pid, endpoint, config, diagnostics }`. `endpoint` là null khi đã dừng; thông tin chẩn đoán chứa các bản ghi `{ stream, message }` gần đây. |
| `POST /mcp/start` | Khởi động MCP tích hợp bằng cài đặt đã lưu và trả về trạng thái. Không có thân yêu cầu. Trả về lỗi xung đột nếu đã chạy. |
| `POST /mcp/stop` | Dừng tiến trình con MCP tích hợp. |
| `GET /settings/mcp` | Trả về cấu hình MCP đã lưu bền vững. |
| `PUT /settings/mcp` | Nhận đối tượng cấu hình đầy đủ, lưu và khởi động lại MCP nếu đang chạy. Trả về cấu hình được chấp nhận hoặc lỗi. Chỉ cho phép host liên kết loopback. |
| `GET /mcp/tools` | Trả về `{ tools, config }`, bao gồm `inputSchema` của từng công cụ. Danh mục REST này không phân trang. |
| `POST /mcp/tools/call` | Gọi một công cụ với `{ "name": "ogma_explain_capabilities", "arguments": {} }`. Trả về `{ "result": "..." }`; phân tích văn bản đó như đối tượng bao JSON của công cụ. Đây không phải kết quả MCP gốc có các khối hình ảnh. |

Cầu nối REST sử dụng quyền đã lưu nhưng không yêu cầu khởi động tiến trình con HTTP MCP riêng. Nó dùng chung một phiên cầu nối cho backend/cấu hình. Ưu tiên MCP gốc khi cần các phiên máy khách tách biệt và đầu ra hình ảnh.

Khi cầu nối gặp lỗi, phân tích `result` sẽ cho `{ "error": "..." }` chứa đối tượng bao lỗi đã được tuần tự hóa. Hãy kiểm tra giá trị đó thay vì coi trạng thái HTTP thành công là công cụ đã thành công.

Cấu hình MCP mặc định được lưu bền vững:

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

Các host liên kết được cho phép là `127.0.0.1`, `localhost` và `::1`; cổng phải từ `1024` đến `65535`. Bản này không cấu hình xác thực cho MCP công khai trên mạng nên từ chối địa chỉ liên kết công cộng. Các trường cũ `allow_public_bind` và `acknowledge_write_tool_risk` không ghi đè hạn chế này.

## Claude Code {#claude-code}

Với điểm cuối của ứng dụng máy tính đang chạy:

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

Dùng điểm cuối Ogma hiển thị nếu khác địa chỉ trên. Xem [cấu hình MCP của Claude Code](https://code.claude.com/docs/en/mcp) để biết phạm vi cấu hình và tùy chọn stdio. Kiểm tra bằng câu hỏi: "Ogma có những dự án nào?"

## Cursor {#cursor}

Gộp mục này vào `.cursor/mcp.json` của dự án hoặc `~/.cursor/mcp.json` ở cấp người dùng:

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

Bật kết nối trong cài đặt MCP của Cursor. Xem [tài liệu MCP của Cursor](https://cursor.com/docs/mcp).

### Cấu hình máy khách stdio {#stdio-client-configuration}

Máy khách khởi chạy tệp thực thi có thể dùng mục máy chủ này, điều chỉnh vị trí tệp cấu hình theo nhu cầu:

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

Trên Windows, dùng đường dẫn đầy đủ đến tệp thực thi và thêm ký tự thoát cho dấu gạch chéo ngược trong JSON. Một số máy khách cũng yêu cầu `"type": "stdio"`. Thêm cờ quyền vào `args` khi cần.

## Quyền {#permissions}

Cả sáu khả năng đặc quyền đều bị tắt theo mặc định. Đọc giá trị hiện tại từ `ogma://mcp/permissions`. Công cụ được liệt kê vẫn có thể từ chối thực thi cho đến khi khả năng tương ứng được bật. Bảng đầy đủ các cờ và biến môi trường nằm trong [tài liệu tham chiếu CLI](/vi/reference/cli.md#standalone-ogma-mcp-flags).

Tương tác với trình duyệt, quản lý ngữ cảnh, chuyển dự án và tất cả lời gọi hành trình xác thực đều yêu cầu `--allow-send-requests`. Công cụ quan sát trình duyệt có thể xem xét trình duyệt đang chạy mà không bật các công cụ điều khiển. `--allow-read-secrets` (hoặc `OGMA_MCP_ALLOW_READ_SECRETS=true`) cho phép riêng việc đọc giá trị biến môi trường không bị che.

Máy chủ **không có hạn ngạch hoạt động theo phút hoặc theo phiên**. Mỗi công cụ vẫn áp dụng giới hạn kích thước đầu vào, kích thước lô, kiểm tra phạm vi và thời gian chờ. Các cờ hạn ngạch gửi/chạy quy trình cũ không còn được hỗ trợ.

## Chế độ chỉ đọc {#read-only-mode}

Theo mặc định, máy chủ MCP chỉ đọc. Các thao tác sau không khả dụng trừ khi được bật rõ ràng:

* Gửi yêu cầu (Replay)
* Điều khiển trình duyệt tích hợp, trình thu thập, tính năng thu thông tin xác thực và công cụ hỗ trợ thăm dò chủ động
* Chạy quy trình
* Tạo hoặc sửa phát hiện
* Sửa phạm vi hoặc quy tắc tìm và thay thế
* Sửa hoặc chuyển tiếp lưu lượng bị chặn bắt
* Xóa dữ liệu
* Truy cập giá trị bí mật của biến môi trường
* Xuất dữ liệu

Bản xem trước thân mặc định là 512 byte. `--body-preview-bytes` điều chỉnh bản xem trước và phải ít nhất là 1; nó không giới hạn đầu ra của mọi công cụ. Dùng `ogma_get_http_entry_body` để lấy toàn bộ thân HTTP hoặc tìm kiếm có mục tiêu trong thân, và `ogma_get_ws_message` để lấy thông điệp WebSocket đầy đủ.

## Công cụ ghi phát hiện {#finding-write-tools}

Để bật tạo phát hiện với AI hỗ trợ, hãy khởi động lại ogma-mcp với quyền ghi:

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

Hoặc đặt biến môi trường:

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

### Công cụ ghi khả dụng {#write-tools-available}

| Công cụ | Mô tả |
|------|-------------|
| `ogma_preview_finding_from_evidence` | Xem trước bản nháp phát hiện từ một mục HTTP (chỉ đọc, luôn khả dụng) |
| `ogma_create_finding` | Tạo phát hiện với mức độ nghiêm trọng, trạng thái, thẻ và liên kết bằng chứng |
| `ogma_update_finding` | Cập nhật phát hiện hiện có |
| `ogma_add_finding_tag` | Thêm thẻ vào phát hiện mà không thay thế thẻ hiện có |
| `ogma_link_finding_evidence` | Liên kết mục HTTP, lần thử Replay, kết quả Automate hoặc thông điệp WS với phát hiện |
| `ogma_delete_finding` | Xóa một phát hiện |
| `ogma_export_findings_report` | Tạo báo cáo HTML, Markdown hoặc PDF |

Triển khai hiện tại cũng dùng quyền ghi phát hiện cho các công cụ ghi dùng chung như cập nhật biến môi trường, chú thích lịch sử, chọn phạm vi và sửa Tìm và thay thế. Xem [danh mục công cụ](/vi/reference/mcp-tools.md) để biết các hành động đó.

### Ví dụ: tạo phát hiện với AI hỗ trợ {#example-ai-assisted-finding-creation}

Với `--allow-write-findings`:

1. "Phân tích mục HTTP {id} để tìm vấn đề bảo mật. Nếu tìm thấy vấn đề thực sự, hãy dùng ogma\_create\_finding để ghi lại."
2. AI sẽ gọi `ogma_get_http_entry` để xem xét yêu cầu
3. Nếu bằng chứng hỗ trợ một phát hiện, AI sẽ gọi `ogma_create_finding` với bằng chứng được liên kết

### Vẫn chưa khả dụng nếu chỉ có quyền ghi phát hiện {#still-not-available-with-finding-writes-only}

* Gửi từ Replay
* Thực thi quy trình
* Tạo bản xuất
* Điều khiển hàng đợi chặn bắt
* Chuyển dự án

## Công cụ xuất dữ liệu {#export-tools}

Để bật tạo tác vụ xuất dữ liệu với AI hỗ trợ, hãy khởi động lại ogma-mcp với quyền xuất dữ liệu:

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

Hoặc đặt biến môi trường:

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

### Công cụ xuất dữ liệu khả dụng {#export-tools-available}

| Công cụ | Quyền cần thiết | Mô tả |
|------|--------------------|-------------|
| `ogma_preview_export_plan` | Không cần (chỉ đọc) | Xem trước nội dung sẽ được đưa vào bản xuất |
| `ogma_list_export_jobs` | Không cần (chỉ đọc) | Liệt kê các tác vụ xuất gần đây |
| `ogma_get_export_job` | Không cần (chỉ đọc) | Kiểm tra trạng thái tác vụ xuất |
| `ogma_get_export_download_info` | Không cần (chỉ đọc) | Lấy URL tải xuống cho bản xuất đã hoàn tất |
| `ogma_create_export_job` | export\_data | Tạo tác vụ xuất dữ liệu |

### Loại và định dạng xuất được hỗ trợ {#supported-export-kinds-and-formats}

| Loại | Mô tả | Định dạng |
|------|-------------|---------|
| `http_history` | Tất cả yêu cầu HTTP đi qua proxy | json, csv, raw\_http |
| `search` | Yêu cầu HTTP đã lọc | json, csv, raw\_http |
| `findings` | Phát hiện bảo mật | json, csv |
| `automate_results` | Kết quả phiên Automate | json, csv |

Lưu ý: định dạng `raw_http` chỉ hợp lệ với các loại `http_history` và `search`.

### Cảnh báo bảo mật {#security-warning}

Tệp xuất có thể chứa toàn bộ thân yêu cầu và phản hồi HTTP, bao gồm cả mật khẩu, token và dữ liệu cá nhân. Hãy xử lý tệp xuất với sự thận trọng phù hợp.

### Vẫn chưa khả dụng nếu chỉ có quyền xuất dữ liệu {#still-not-available-with-export-permissions-only}

* Xóa tệp xuất
* Đổi tên tệp xuất
* Truyền nội dung xuất qua MCP
* Gửi từ Replay
* Thực thi quy trình

## Gửi yêu cầu Replay {#replay-request-sending}

Cảnh báo: tính năng này cho phép gửi lưu lượng HTTP thực sự ra ngoài qua Ogma Replay.

Để bật:

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

Hoặc qua biến môi trường:

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

### Điều kiện tiên quyết {#prerequisites}

1. Proxy Ogma phải đang chạy
2. Phải cấu hình phạm vi đang hoạt động trong **Phạm vi** cho các lần gửi Replay có kiểm soát
3. Host đích phải nằm trong phạm vi đang hoạt động

### Công cụ gửi {#send-tools}

| Công cụ | Quyền | Mô tả |
|------|-----------|-------------|
| `ogma_preview_replay_send` | send\_requests | Chuẩn bị gửi và lấy token xác nhận |
| `ogma_send_replay_request` | send\_requests | Thực hiện gửi với token xác nhận |
| `ogma_create_replay_session_from_history` | send\_requests | Tạo phiên Replay |
| `ogma_create_replay_session_raw` | send\_requests | Tạo phiên Replay từ định nghĩa yêu cầu thô |
| `ogma_browser_form_to_replay` | send\_requests | Tạo phiên Replay từ biểu mẫu trên trang đang mở |
| `ogma_create_scope_preset` | send\_requests | Lưu cấu hình phạm vi; kích hoạt riêng bằng `ogma_set_active_scope` |
| `ogma_repeat_request` | send\_requests | Lặp lại yêu cầu đã thu với thay đổi tùy chọn |
| `ogma_replay_with_modifications` | send\_requests | Phát lại yêu cầu đã thu với giá trị ghi đè ở cấp trường |
| `ogma_http_request` | send\_requests | Gửi yêu cầu HTTP trực tiếp |
| `ogma_fetch_url` | send\_requests | Truy xuất URL và trả về trạng thái, header và bản xem trước |
| `ogma_follow_redirect` | send\_requests | Theo chuỗi chuyển hướng và báo cáo từng bước |
| `ogma_bulk_send_requests` | send\_requests | Gửi một lô yêu cầu có giới hạn |
| `ogma_fuzz_parameter` | send\_requests | Thay thế chỗ giữ chỗ `{{FUZZ}}` bằng giá trị trong danh sách từ |
| `ogma_multipart_upload` | send\_requests | Gửi yêu cầu multipart form-data để kiểm thử tải lên |
| `ogma_websocket_connect` | send\_requests | Kết nối với URL WebSocket và trao đổi thông điệp |
| `ogma_login_replay_auto` | send\_requests | Gửi biểu mẫu đăng nhập trong trình duyệt và thu hồ sơ xác thực |
| `ogma_auth_capture_profile` | send\_requests | Thu cookie, dữ liệu lưu trữ, token xác thực và ứng viên CSRF của trình duyệt |
| `ogma_auth_apply_profile` | send\_requests | Áp dụng hồ sơ xác thực đã thu cho trình duyệt |
| `ogma_auth_refresh_csrf` | send\_requests | Cập nhật ứng viên CSRF từ trạng thái trình duyệt |
| `ogma_authz_matrix_test` | send\_requests | Phát lại một yêu cầu với nhiều hồ sơ xác thực |
| `ogma_run_active_probe_workflow` | send\_requests | Chạy thăm dò chủ động có giới hạn, chuyên biệt theo lỗ hổng |
| `ogma_test_race` | send\_requests | Gửi đồng thời một yêu cầu và báo cáo các phản hồi khác mã trạng thái phổ biến nhất |
| `ogma_test_smuggling` | send\_requests | Gửi thăm dò mất đồng bộ yêu cầu CL.TE và TE.CL qua TCP thô |
| `ogma_test_hpp` | send\_requests | Gửi các biến thể ô nhiễm tham số HTTP |
| `ogma_run_nuclei` | send\_requests | Chạy một mẫu của trình quét dựa trên mẫu, được đóng gói hoặc được cung cấp, với URL đích |
| `ogma_browser_navigate` và công cụ tương tác trình duyệt | send\_requests | Điều khiển trình duyệt tích hợp và thu lưu lượng phát sinh |
| `ogma_crawl_site` | send\_requests | Thu thập trang từ đích trong phạm vi qua trình duyệt tích hợp |
| `ogma_get_replay_session` | Không cần | Xem siêu dữ liệu phiên Replay |
| `ogma_get_replay_attempt` | Không cần | Xem siêu dữ liệu lần thử Replay |
| `ogma_list_replay_sessions` | Không cần | Liệt kê phiên Replay |

### Quy trình hai bước {#two-step-workflow}

Cặp công cụ Replay dựa trên xác nhận dùng hai lời gọi:

1. `ogma_preview_replay_send` - xem xét yêu cầu và lấy token xác nhận
2. `ogma_send_replay_request` - xác nhận và gửi bằng token

Token xác nhận hết hạn sau 5 phút, chỉ dùng một lần và thuộc phiên MCP đã tạo chúng. Hãy xem trước lại sau khi sửa yêu cầu hoặc khởi động lại MCP. Quy tắc hai bước này không áp dụng cho mọi công cụ gửi: công cụ HTTP trực tiếp, công cụ hỗ trợ lặp lại và hành động trình duyệt có thể gửi ngay khi được bật.

### Phiên ví dụ {#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 --
```

### Vẫn chưa khả dụng nếu chỉ có quyền gửi yêu cầu {#still-not-available-with-request-sending-permissions-only}

* Thực thi quy trình
* Tạo hoặc cập nhật phát hiện
* Xóa dữ liệu

Giữ phạm vi đang hoạt động đủ hẹp trước khi bật các công cụ này. Kiểm tra phạm vi áp dụng trên những đường gửi có kiểm soát; đừng coi phạm vi là tường lửa phổ quát cho JavaScript tùy ý trong trình duyệt hoặc mọi công cụ hỗ trợ truy xuất trực tiếp.

## Điều khiển chặn bắt {#intercept-control}

Cảnh báo: điều khiển chặn bắt cho phép máy khách MCP chuyển tiếp, loại bỏ hoặc sửa lưu lượng trực tiếp đang được giữ trong hàng đợi chặn bắt của Ogma.

Để bật:

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

Hoặc qua biến môi trường:

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

### Công cụ chặn bắt {#intercept-tools}

| Công cụ | Quyền | Mô tả |
|------|-----------|-------------|
| `ogma_get_intercept_status` | intercept\_control | Đọc trạng thái chặn bắt yêu cầu, phản hồi và WebSocket |
| `ogma_set_intercept_enabled` | intercept\_control | Bật hoặc tắt chế độ chặn bắt |
| `ogma_list_intercept_queue` | intercept\_control | Liệt kê các mục đang được giữ |
| `ogma_get_intercept_item` | intercept\_control | Xem xét một mục trong hàng đợi |
| `ogma_forward_intercept_item` | intercept\_control | Chuyển tiếp mục trong hàng đợi, có thể kèm sửa đổi |
| `ogma_drop_intercept_item` | intercept\_control | Loại bỏ mục trong hàng đợi |
| `ogma_intercept_and_modify` | intercept\_control | Chờ mục khớp điều kiện, sửa và chuyển tiếp |

## Thực thi quy trình {#workflow-execution}

Cảnh báo: thực thi quy trình sẽ chạy logic của quy trình. Một số quy trình gửi lưu lượng HTTP hoặc tạo phát hiện.

Để bật:

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

### Công cụ thực thi quy trình {#workflow-execution-tools}

| Công cụ | Quyền | Mô tả |
|------|-----------|-------------|
| `ogma_get_workflow_safety` | Không cần (chỉ đọc) | Phân loại tác động phụ của quy trình |
| `ogma_preview_workflow_run` | run\_workflows | Xem trước và lấy token xác nhận |
| `ogma_run_workflow` | run\_workflows | Thực thi với token xác nhận |
| `ogma_cancel_workflow_run` | run\_workflows | Hủy quy trình chủ động đang chạy |

Xem trước bằng `workflow_id`, thêm `input` cho quy trình chuyển đổi hoặc `trigger_entry_id` cho đầu vào đã thu của quy trình chủ động. Chạy với `confirmation_token` và `definition_hash` được trả về; quy trình chuyển đổi cũng cần `input_hash` và cùng `input`. Token hết hạn sau năm phút và chỉ dùng một lần. Đọc lần chạy kết quả bằng `ogma_get_workflow_run`.

Thực thi Automate khả dụng qua các công cụ phiên/lần chạy với **quyền gửi yêu cầu**, không phải quyền chạy quy trình. Liệt kê và xem xét các lần chạy hiện có không cần quyền gửi.

### Yêu cầu phối hợp quyền {#cross-permission-requirements}

Quy trình dùng `sdk.requests.send` cũng cần `--allow-send-requests`.
Quy trình dùng `sdk.findings.create` cũng cần `--allow-write-findings`.

Việc nhận diện dựa trên phân tích văn bản tĩnh; xem lưu ý hướng dẫn bên dưới.

### Lưu ý hướng dẫn về phân loại an toàn {#safety-classification-advisory-note}

Phân loại an toàn quy trình xem xét văn bản mã nguồn JavaScript để tìm mẫu như `sdk.requests.send`. Việc nhận diện này không đầy đủ: lời gọi phương thức SDK bị làm rối hoặc xây dựng động có thể không được nhận diện. Luôn xem xét mã nguồn JavaScript trước khi chạy quy trình không đáng tin cậy.

### Vẫn chưa khả dụng nếu chỉ có quyền chạy quy trình {#still-not-available-with-workflow-permissions-only}

* Kích hoạt thủ công quy trình thụ động
* Xóa dữ liệu
* Sửa biến môi trường

## Lời nhắc ví dụ {#example-prompts}

Sau khi kết nối:

* "Hiển thị 20 yêu cầu HTTP gần nhất đến example.com"
* "Dự án này có phát hiện mức cao hoặc nghiêm trọng không?"
* "Những quy trình nào hiện đang được bật?"
* "Kiểm tra truy vấn HTTPQL `req.method.eq:\"POST\"` có hợp lệ không"
* "Tóm tắt trạng thái bảo mật của dự án hiện tại"
* "Phân tích mục HTTP {id} để tìm vấn đề bảo mật"

## Khắc phục sự cố {#troubleshooting}

**Kết nối bị từ chối:** khởi động Ogma trước (`ogma --data-dir ./ogma-data`).

**Máy khách MCP không hiển thị công cụ:** kiểm tra URL kênh truyền hoặc đường dẫn tệp thực thi. Máy khách phải theo tất cả con trỏ của `tools/list`; mỗi trang có tối đa 40 công cụ. Kiểm tra bộ lọc phía máy khách và xem bản đã cài có chứa công cụ bị thiếu không.

**Phiên hoặc token xác nhận không hợp lệ:** kết nối lại sau khi khởi động lại và tạo token xem trước mới.

**Trình duyệt không khả dụng hoặc hành động thất bại:** giữ ứng dụng máy tính đang chạy. Kiểm tra `ogma_browser_health`, hộp thoại và [khôi phục trình duyệt](/vi/guide/mcp-browser.md#recover-from-errors). Chỉ có backend không giao diện thì không cung cấp cầu nối trình duyệt của ứng dụng máy tính.

**Ảnh chụp màn hình không có văn bản đọc được:** dùng máy khách hỗ trợ nội dung hình ảnh MCP gốc hoặc xem xét bản chụp cấu trúc ngữ nghĩa.

**Kết quả trống:** Ogma cần thu lưu lượng trước. Duyệt web với proxy được cấu hình để chuyển tiếp lưu lượng qua Ogma.