Ogma MCP サーバーの設定

Ogma MCP サーバー（ogma-mcp）を使うと、対応する AI アシスタントがプロジェクトコンテキストを確認できます。必要な機能を有効にすれば、埋め込みブラウザーの操作、リクエストの送信、ワークフローの実行、証拠の収集も行えます。メモ/ToDo ツールは MCP セッション中のメモリ内の作業用メモであり、アプリの永続的なメモページとは別です。

MCP は Codex、Claude Code、Cursor、その他の Model Context Protocol クライアントなどの外部ツール向けです。アプリ内のワークスペース AI アシスタントとは別の機能です。

リソースとツールの完全な一覧は 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	スタンドアロン MCP の --api-url と、下記の管理/ブリッジルート。
プロキシリスナー	127.0.0.1:8080	ブラウザー通信をキャプチャします。MCP エンドポイントではありません。

デスクトップインスタンスではバックエンド API のポートが動的に割り当てられることがあります。stdio/REST 統合には稼働中のインスタンスの実際のアドレスを、ネイティブ MCP には設定画面に表示されたエンドポイントを使用してください。ローカルのクライアント/コネクターがなければ、クラウドのチャットサービスからループバックアドレスには接続できません。

HTTP エンドポイントは状態を保持します。初期化とセッションヘッダーの処理はクライアントに任せてください。従来の独立した /sse エンドポイントはありません。独自のクライアントは MCP のトランスポート仕様に従ってください。

MCP を使用する場面

外部のアシスタントに次の作業を支援させたい場合に MCP を使用します。

• キャプチャされた通信の要約。
• 指摘事項のトリアージ。
• 証拠に基づくレポート文案の作成。
• ワークフローと再送セッションのレビュー。
• 明示的に承認する、診断対象範囲内の操作の準備。

Ogma 内に埋め込まれたアシスタントウィンドウを使用する場合は、ワークスペース AIを利用してください。

スタンドアロン実行の要件

クライアントが埋め込み HTTP エンドポイントに接続するのではなく、ローカルの実行ファイルを起動する必要がある場合は stdio を使用します。

• 実際の API アドレスで稼働している Ogma バックエンド（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 管理機能を提供します。これらのルートは専用の 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 設定の既定値：

{
  "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 リファレンスをご覧ください。

ブラウザー操作、ブラウザーコンテキストの管理、プロジェクトの切り替え、認証フローのすべての呼び出しには --allow-send-requests が必要です。ブラウザーの観察は、制御ツールを有効にしなくても、すでに稼働しているブラウザーを確認できます。--allow-read-secrets（または OGMA_MCP_ALLOW_READ_SECRETS=true）は、マスクされていない環境変数の値へのアクセスを別途許可します。

サーバーには毎分またはセッションごとの操作回数の上限はありません。各ツールは引き続き、入力サイズ、バッチサイズ、診断対象範囲の確認、タイムアウトを制限します。従来の送信/ワークフロー回数制限フラグはサポートされなくなりました。

読み取り専用モード

MCP サーバーは既定で読み取り専用です。明示的に有効にしない限り、次の操作は利用できません。

• リクエストの送信（再送）
• 埋め込みブラウザー、クローラー、認証キャプチャ、アクティブプローブ用ヘルパーの操作
• ワークフローの実行
• 指摘事項の作成または変更
• 診断対象範囲や照合・置換ルールの変更
• インターセプトされた通信の変更または転送
• データの削除
• 機密の環境変数値へのアクセス
• データのエクスポート

ボディプレビューの既定値は 512 バイトです。--body-preview-bytes で調整でき、少なくとも 1 にする必要があります。すべてのツールの出力を制限するものではありません。HTTP ボディ全体の取得またはボディ内の絞り込み検索には ogma_get_http_entry_body、WebSocket メッセージ全体の取得には ogma_get_ws_message を使用してください。

指摘事項の書き込みツール

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. 証拠が指摘事項を裏付ける場合、証拠を関連付けて 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 やすべての直接取得ヘルパーを囲む万能のファイアウォールとして、診断対象範囲を扱わないでください。

インターセプト制御

警告：インターセプト制御は、Ogma のインターセプトキューに現在保留されている実際の通信を、MCP クライアントが転送、破棄、変更できるようにします。

有効にするには：

./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 ソースを確認してください。

ワークフロー権限のみでは利用できない操作

• パッシブワークフローの手動起動
• 削除
• 環境変数の変更

プロンプトの例

接続後：

• 「example.com への直近 20 件の 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 経由で通信が転送されるようプロキシを設定し、ブラウザーでアクセスしてください。