Ogma MCP 伺服器設定

Ogma MCP 伺服器（ogma-mcp）讓相容的 AI 助手查看專案情境資訊，並在啟用相關功能後，操作嵌入式瀏覽器、傳送請求、執行工作流程及收集證據。它的筆記/待辦工具是儲存於記憶體中的 MCP 工作階段暫存記事區，與應用程式中持久儲存的筆記頁面分開。

MCP 供 Codex、Claude Code、Cursor 及其他模型情境協定用戶端等外部工具使用，與應用程式內的工作區 AI 助手不是同一項功能。

完整資源與工具清單請參閱 MCP 資源與工具。

快速入門：桌面應用程式

1. 啟動 Ogma，開啟要讓代理程式檢查的專案。
2. 開啟設定 > MCP，選擇所需權限並儲存。瀏覽器互動需要傳送重送請求權限。
3. 點選啟動並複製顯示的端點，通常是 http://127.0.0.1:3000/mcp。
4. 將此端點以 Streamable HTTP 伺服器的形式加入 MCP 用戶端。
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	獨立 MCP 的 --api-url，以及下方的管理/橋接路由。
代理監聽器	127.0.0.1:8080	擷取瀏覽器流量；這不是 MCP 端點。

桌面執行個體可能動態指派後端 API 連接埠。stdio/REST 整合請使用實際執行個體的位址，原生 MCP 請使用設定中顯示的端點。若沒有本機用戶端/連接器，雲端聊天服務無法存取你的回送位址。

HTTP 端點會維護狀態：請讓用戶端處理初始化及工作階段標頭。沒有獨立的舊版 /sse 端點。自訂用戶端應遵循 MCP 傳輸規格。

何時使用 MCP

需要外部助手協助以下工作時，請使用 MCP：

• 摘要已擷取的流量。
• 對檢測發現進行分級處理。
• 草擬以證據為依據的報告文字。
• 檢閱工作流程及重送工作階段。
• 準備在指定測試範圍內、由你明確核准的操作。

若想使用 Ogma 內嵌的助手視窗，請改用工作區 AI。

獨立執行的需求

若用戶端需要啟動本機執行檔，而不是連接內嵌的 HTTP 端點，請使用 stdio。

• Ogma 後端在其實際 API 位址執行中（CLI 預設：http://127.0.0.1:8181）
• ogma-mcp 二進位檔（從原始碼建置）

建置

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

除非自訂了 Cargo 目標目錄，否則預設輸出是 target/release/ogma-mcp（Windows 上為 ogma-mcp.exe）。

執行

# 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-profile、--mcp-tool-profile 和 OGMA_MCP_TOOL_PROFILE 值仍可接受，以維持相容性，但不會隱藏工具或授予權限。

工具目錄較大時，請先使用 ogma_explain_capabilities 和 ogma_find_tools，不要猜測輸入。搜尋任務關鍵字以篩選工具，再查詢確切的工具名稱以查看其契約。瀏覽器與搜尋分派器提供方便的進入點；專用工具也仍可直接使用。參閱工具探索與分派。

應用程式內的 MCP 設定

封裝後的 Ogma 版本可從設定 > MCP 管理 MCP。若希望由 Ogma 啟動或停止目前執行個體的內嵌 MCP 處理程序，請使用設定畫面。

若 AI 用戶端預期直接啟動 MCP 伺服器，請使用獨立的 ogma-mcp 二進位檔。

儲存設定會自動重新啟動正在執行的內嵌 MCP 處理程序。之後請重新連接用戶端；舊的工作階段 ID 及確認權杖無法重複使用。執行階段診斷會顯示最近的處理程序輸出。

Ogma 也透過本機 REST API 提供 MCP 管理功能。這些路由位於後端 API 連接埠，而不是專用 MCP 連接埠，供設定畫面及應用程式內的 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	傳回 { 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 選項請參閱 Claude Code 的 MCP 設定。可用以下問題驗證：「Ogma 有哪些專案？」

Cursor

將此項目合併至專案的 .cursor/mcp.json 或使用者層級的 ~/.cursor/mcp.json：

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

在 Cursor 的 MCP 設定中啟用連線。參閱 Cursor MCP 文件。

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 參考。

瀏覽器互動、瀏覽器環境（context）管理、專案切換，以及所有驗證流程呼叫，都需要 --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 訊息。

檢測發現寫入工具

若要啟用 AI 輔助建立檢測發現，請以寫入權限重新啟動 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 報告

目前實作也以檢測發現寫入權限控制共用寫入工具，例如環境變數更新、歷程記錄註記、測試範圍選擇及比對與取代修改。這些操作請參閱工具目錄。

範例：AI 輔助建立檢測發現

啟用 --allow-write-findings 後：

1. 「分析 HTTP 項目 {id} 中的安全問題。如果發現真實問題，請使用 ogma_create_finding 記錄。」
2. AI 會呼叫 ogma_get_http_entry 檢查請求
3. 若證據支持某項檢測發現，AI 會呼叫 ogma_create_finding 並連結證據

僅啟用檢測發現寫入時仍無法使用的操作

• 重送請求
• 執行工作流程
• 建立匯出
• 控制攔截佇列
• 切換專案

匯出工具

若要啟用 AI 輔助建立匯出工作，請以匯出權限重新啟動 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 串流匯出內容
• 重送請求
• 執行工作流程

傳送重送請求

警告：此功能允許透過 Ogma 重送工具傳送真實的對外 HTTP 流量。

啟用方式：

./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	連接 WebSocket URL 並交換訊息
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	透過原始 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	無	列出重送工作階段

兩步驟工作流程

需要確認的重送工具組使用兩次呼叫：

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 個傳送至 example.com 的 HTTP 請求」
• 「此專案是否有高風險或嚴重的檢測發現？」
• 「目前啟用了哪些工作流程？」
• 「檢查 HTTPQL 查詢 req.method.eq:\"POST\" 是否有效」
• 「摘要目前專案的安全狀態」
• 「分析 HTTP 項目 {id} 中的安全問題」

疑難排解

連線遭拒： 請先啟動 Ogma（ogma --data-dir ./ogma-data）。

MCP 用戶端沒有顯示工具： 檢查傳輸 URL 或執行檔路徑。用戶端必須跟隨所有 tools/list 游標；每頁最多包含 40 個工具。請檢查用戶端篩選，以及已安裝版本是否包含缺少的工具。

工作階段或確認權杖無效： 重新啟動後，請重新連線並產生新的預覽權杖。

瀏覽器無法使用或操作失敗： 保持桌面應用程式執行。檢查 ogma_browser_health、對話方塊及瀏覽器復原。只有無介面的後端並不提供桌面瀏覽器橋接。

螢幕截圖沒有可讀文字： 使用支援原生 MCP 影像內容的用戶端，或檢查語意快照。

結果為空： Ogma 必須先擷取流量。設定瀏覽器代理，讓流量經 Ogma 轉送後再瀏覽。