---
url: https://docs.ogmabox.com/reference/mcp-tools.md
description: >-
  Complete Ogma MCP reference with tool purposes and inputs, resources, prompts,
  permissions, pagination, and result handling.
---

# MCP Resources and Tools

The Ogma MCP server is for external MCP clients such as Codex, Claude Code, Cursor, and other Model Context Protocol hosts. It is separate from the in-app AI assistant.

MCP exposes four discovery surfaces:

* **Resources**: named read targets that an MCP client can open.
* **Resource templates**: parameterized read targets for a specific entry, finding, workflow, run, export, or Replay object.
* **Tools**: callable actions. Some are read-only. Some require server startup flags.
* **Prompts**: reusable instructions that help an agent plan an inspection, retest, or report. Getting a prompt does not execute its tools.

For connection endpoints and client configuration, see [MCP setup](../mcp-setup.md). For an end-to-end interaction sequence, see [Browser automation with MCP](../guide/mcp-browser.md).

This reference covers the current implementation: **255 tools**, 17 resources, 9 resource templates, and 12 prompts. All tools are advertised; permission gates still apply when they are called. Older installed releases may expose fewer tools. Discover the catalog from your running server before choosing a tool.

## Protocol Methods

These are JSON-RPC method names, not separate URL paths. An MCP client handles the connection lifecycle over [HTTP or stdio](../mcp-setup.md#connection-addresses).

| Method | Purpose |
| --- | --- |
| `initialize` | Negotiate protocol version and server/client capabilities. |
| `notifications/initialized` | Tell the server that initialization is complete; this notification has no request ID. |
| `tools/list` | Discover tools and their argument schemas, following `nextCursor`. |
| `tools/call` | Execute a tool using `name` and `arguments`. |
| `resources/list` | List named read-only resources. |
| `resources/templates/list` | List URI templates for reading individual objects. |
| `resources/read` | Read a resource using its complete `uri`. |
| `prompts/list` | Discover reusable prompts and their arguments. |
| `prompts/get` | Retrieve a prompt's messages using `name` and optional string arguments. |

## Discover and Call Tools

Tool names such as `ogma_search_http_history` are MCP tool identifiers, not individual HTTP routes. Call them through `tools/call` on your MCP connection.

1. Initialize the connection with your MCP client.
2. Call `tools/list`. Ogma returns up to **40 tools per page**. Pass each returned `nextCursor` back as `params.cursor` until it is absent; otherwise most browser tools will be missing from the client.
3. Read each tool's `inputSchema` for field types, enum values, defaults, limits, and nested object formats. Do not invent arguments from the tool name.
4. Read `ogma://mcp/permissions` and `ogma://mcp/tool-guide` before taking actions.
5. Call the selected tool with a JSON object in `arguments`.

Example JSON-RPC request on an initialized connection:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "ogma_search_http_history",
    "arguments": {
      "q": "req.host.eq:\"example.com\"",
      "limit": 20,
      "offset": 0
    }
  }
}
```

Use IDs returned by list/search tools rather than guessing them. History and finding searches use `limit`/`offset`; browser delta tools use `since_entry_id`. Neither is the opaque cursor used by `tools/list`.

## Reading Results

Prefer `result.structuredContent`. The text content block contains the same JSON envelope for clients that only support text results. Exception: the default `ogma_browser_snapshot` result has no structured content, and its text content is the readable tree; use `result_detail: "full"` for its structured elements. In the local REST bridge, parse the JSON string in `result` instead; that bridge is not the MCP transport.

For a REST-bridge tool failure, the parsed value is `{ "error": "..." }`, with the tool's serialized error envelope inside that string. An HTTP-success status from the bridge alone does not mean the tool succeeded.

| Envelope field | Meaning |
| --- | --- |
| `ok` | Whether the tool operation succeeded. Also inspect the MCP result's `isError`. |
| `workflow_stage`, `summary` | Operation context and a short explanation. |
| `evidence`, `hypotheses` | Observed evidence and separate, unconfirmed interpretations. |
| `next_actions`, `use_next_tools` | Suggested follow-up work and tool routing. |
| `artifacts` | References to generated evidence or files when available. |
| `raw` | Tool-specific data. Present on the structured paths; compact tools include it only with `result_detail: "full"`. May be an object, array, or text; do not assume one universal shape. |

Screenshot tools also return a native MCP image block. Read the image block rather than expecting base64 image data in the JSON metadata. A browser snapshot returns a compact text tree by default; pass `result_detail: "full"` for its structured elements under `raw.elements`. Browser network and console deltas contain structured entries.

A successful validation call can still return `valid: false` in its data. A tool execution failure uses `isError: true`; invalid protocol requests use JSON-RPC errors. Read the diagnostic before retrying. Backend errors can include an HTTP status, endpoint, and bounded diagnostic text; `[truncated]` means the diagnostic was shortened, not that the operation succeeded.

These result conventions use MCP's [tool result format](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-result).

## Resources

| Resource | What it returns |
| --- | --- |
| `ogma://status` | Current backend health and status. |
| `ogma://projects` | All Ogma projects. |
| `ogma://project/current` | Current active project. |
| `ogma://instances` | Proxy listener instances. |
| `ogma://http-history/recent` | 20 most recent HTTP entries without body content. |
| `ogma://ws-history/recent` | 20 most recent WebSocket connections. |
| `ogma://findings` | Up to 50 findings. |
| `ogma://workflows` | Configured workflows. |
| `ogma://workflow-runs/recent` | 20 most recent workflow run records. |
| `ogma://migration/workflows` | Workflow migration compatibility report. |
| `ogma://exports/recent` | 10 most recent export jobs. |
| `ogma://capabilities` | MCP server capability summary. |
| `ogma://mcp/permissions` | Current MCP permission flags. |
| `ogma://mcp/tool-guide` | Agent tool routing, output conventions, and recommended browser/testing sequences. |
| `ogma://mcp/report-guide` | Report assembly sequence, evidence requirements, and quality checks. |
| `ogma://mcp/resume` | Durable recovery context for the active project: saved checkpoints and recent tool activity. |
| `ogma://replay/sessions/recent` | 20 most recent Replay sessions. |

## Resource Templates

| Template | What it returns |
| --- | --- |
| `ogma://http-history/{entry_id}` | One HTTP history entry. |
| `ogma://ws-history/{connection_id}` | One WebSocket connection. |
| `ogma://findings/{finding_id}` | One finding. |
| `ogma://workflows/{workflow_id}` | One workflow. |
| `ogma://workflow-runs/{run_id}` | One workflow run. |
| `ogma://exports/{export_id}` | One export job. |
| `ogma://replay/sessions/{session_id}` | One Replay session. |
| `ogma://replay/attempts/{session_id}/{attempt_id}` | One Replay attempt. |
| `ogma://workflow-safety/{workflow_id}` | Workflow safety classification and required permissions. |

Read these URIs with `resources/read`, not with an HTTP GET to `ogma://`. Substitute the ID into a resource template before reading it. Resources return text in `contents`; they do not use the tool-result envelope above.

## Prompts

Discover with `prompts/list`, then use `prompts/get` with `name` and an `arguments` object. Prompt argument values are strings. Required arguments are bold below.

| Prompt | Arguments | What it prepares |
| --- | --- | --- |
| `analyze_http_entry` | **`entry_id`** | Inspect one captured HTTP exchange for evidence-backed security issues. |
| `summarize_project_security_state` | None | Summarize findings and remediation priorities for the active project. |
| `triage_findings` | `severity` | Prioritize findings, optionally within one severity. |
| `investigate_suspicious_host` | **`host`** | Review captured traffic for a hostname or IP. |
| `review_workflow_migration_report` | None | Explain workflow compatibility problems and migration steps. |
| `generate_retest_plan` | **`finding_id`** | Prepare reproduction steps and pass/fail criteria for a finding. |
| `create_finding_from_http_evidence` | **`entry_id`** | Analyze evidence and guide finding creation when permitted. |
| `prepare_evidence_export` | **`export_kind`** | Plan an `http_history`, `findings`, or `automate_results` export. |
| `retest_http_entry_with_replay` | **`entry_id`** | Guide the Replay preview-and-confirm sequence. |
| `run_workflow_safely` | **`workflow_id`** | Inspect workflow side effects, preview, and run when permitted. |
| `pentest_web_target` | **`target_url`**, `objective` | Plan a staged, evidence-led assessment of an authorized target. |
| `solve_web_challenge` | **`challenge_url`**, `goal` | Plan a web challenge investigation and evidence collection. |

## Tool Permissions

Most inspection tools are always available. Mutating or outbound actions are controlled by `ogma-mcp` startup flags:

| Permission flag | Enables |
| --- | --- |
| `--allow-write-findings` | Finding writes and report generation; also shared project mutations such as environment-variable and Match & Replace edits. |
| `--allow-export-data` | Export job creation. Reading existing export metadata and download information does not require this flag. |
| `--allow-read-secrets` | Unmasked environment-variable values. This is separate from permission to modify variables. |
| `--allow-send-requests` | Replay/Automate sends, direct/bulk requests, browser interaction, discovery, crawling, authentication journeys, active probes, WebSockets, and project switching. |
| `--allow-run-workflows` | Workflow preview, execution, and cancellation tools. Automate execution uses send permission instead. |
| `--allow-intercept-control` | Intercept status/queue reads, queue mutation, and intercept state control. |

Permission gates are checked when a tool is called; listing a tool does not mean its actions are enabled. Browser observation tools can inspect an already-running browser, but driving it and managing its contexts requires `allow_send_requests`. Authentication journeys also require that permission, including list and verification calls. Session-local notes and todos do not require project-write permission.

There are no per-minute or per-session activity quotas. Individual tools still enforce their own input sizes, batch sizes, timeouts, and scope checks. Workflow execution may need additional send or finding-write permission according to the workflow's operations. See [setup and permissions](../mcp-setup.md#permissions).

All tools are advertised regardless of permissions. Legacy profile flags no longer filter the tool list. See [Tool Discovery and Dispatch](#tool-discovery-and-dispatch).

## Tool Catalog

### Recovering After Context Loss

After reconnecting or losing conversation context, call `ogma_resume_session` before starting another assessment. Check the active project, last checkpoint, and recent tool outcomes. Use `check_live: true` for bounded read-only checks of saved handles; it does not repeat actions. Refresh browser snapshots before reusing element references.

Save a checkpoint before a handoff or a long pause. Tool activity records what ran; it cannot infer your intended next test. Keep the objective, conclusions, uncertainty, and next steps explicit, and reference evidence by ID rather than copying large response bodies into the checkpoint.

```json
{
  "name": "ogma_save_checkpoint",
  "arguments": {
    "assessment_id": "authorization-review",
    "objective": "Compare access to invoices across two test identities",
    "progress": "Captured the owner request; the second identity has not been tested yet",
    "next_steps": ["Resume the saved context", "Verify the active project and both identities before replaying"],
    "uncertainties": ["Whether the server checks invoice ownership"]
  }
}
```

```json
{
  "name": "ogma_resume_session",
  "arguments": {
    "assessment_id": "authorization-review",
    "check_live": true
  }
}
```

Save a checkpoint before handoff or context compaction. Record your objective, completed work, uncertainties, evidence IDs, and the next steps explicitly: the automatic activity log stores handles and outcomes, not request payloads or your intent. A started call without a completed result has an unknown outcome; inspect the current state before retrying a send.

Recovery records are durable and project-scoped. With `assessment_id`, reads are limited to that assessment; omit it on recovery reads to inspect project-wide activity. Existing session-local notes/todos serve a different purpose and should not be mistaken for a durable handoff.

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_save_checkpoint` | Appends a durable handoff. `next_steps` is an array of explicit actions; `references` maps names to saved IDs. Does not execute the plan. | **`objective`**, **`progress`**, **`next_steps`**, `uncertainties`, `references` |
| `ogma_resume_session` | Reads the active project, latest checkpoint, recent activity, and recovery guidance. Optional live checks inspect saved handles without repeating actions. | `check_live` |
| `ogma_get_session_activity` | Reads checkpoints and tool activity newest first. Times are UTC Unix milliseconds. To paginate, pass both `before_ms` and `before_id` from the returned cursor. | `kind`, `id`, `since_ms`, `until_ms`, `before_ms`, `before_id`, `search`, `limit` |

Each row explains the tool and lists its top-level inputs. **Bold inputs are required by its schema**; other inputs are optional. Some tools require a choice between inputs (for example, a Replay source or a click target); their descriptions and runtime validation explain those combinations. For nested fields and exact types, read the running tool's `inputSchema`.

Every tool also accepts an optional `assessment_id` (a non-empty string, maximum 200 characters). Reuse it to keep one assessment's recovery context together. It does not change the active project or grant permissions. This common input is not repeated in the tables below.

### Tool Discovery and Dispatch

The server advertises every registered tool. Use the capability and contract discovery tools to identify an operation and inspect its inputs before calling it; you do not need to change a profile to expose it. See [MCP setup](../mcp-setup.md#tool-discovery).

Use `ogma_browser` for embedded-browser actions (`snapshot`, `fill_input`, `fill_form`, `console_delta`, `network_delta`, and the rest of the browser family) and `ogma_search` for search domains such as `http_history`, `findings`, and `ws_history`. The equivalent dedicated tools remain available.

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_find_tools` | Searches the entire catalogue by task keywords. An exact tool-name query returns its complete contract; `include_schema` requests contracts for keyword matches too. Search words must all match, and a truncated or empty result does not prove a capability is absent. Default limit is 5, maximum 10. | **`query`**, `limit`, `include_schema` |
| `ogma_call_tool` | Runs a registered Ogma tool by name. Inputs other than `tool` are forwarded to the named tool; its permissions still apply. | **`tool`** |
| `ogma_browser` | Drives the embedded browser by action name. Any other `ogma_browser_*` tool is reached by its name suffix, for example `action: "snapshot"` for `ogma_browser_snapshot`. | **`action`**, `selector`, `tab_id`, `url`, `js`, `text`, `value`, `key`, `cookie`, `timeout_ms` |
| `ogma_search` | Searches Ogma data domains through one entry point. Any other `ogma_search_*` tool is reached by its name suffix. | **`domain`**, `q`, `limit`, `offset` |

### HTTP History and Querying

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_search_http_history` | Searches HTTP history with HTTPQL and returns request/response metadata. | `q`, `limit`, `offset`, `result_detail` |
| `ogma_get_http_entry` | Gets one HTTP entry by ID, optionally with body previews. | **`entry_id`**, `include_body_preview`, `result_detail` |
| `ogma_get_http_entry_body` | Gets full request and/or response body for an HTTP entry. | **`entry_id`**, **`part`**, `search_pattern`, `result_detail` |
| `ogma_validate_httpql` | Validates an HTTPQL expression. | **`query`** |
| `ogma_analyze_http_entry_security` | Reviews one HTTP entry for security-relevant behavior and evidence. | **`entry_id`** |
| `ogma_search_by_vulnerability_pattern` | Searches captured traffic for vulnerability-oriented patterns. | **`pattern_type`**, `limit` |

### WebSocket and SSE

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_search_ws_history` | Searches WebSocket connection history with StreamQL. | `q`, `limit`, `offset` |
| `ogma_get_ws_messages` | Gets stored messages for one WebSocket connection. | **`connection_id`**, `limit`, `offset` |
| `ogma_get_ws_message` | Reads one complete message without list-preview truncation; text is UTF-8, binary/control payloads are base64. | **`message_id`** |
| `ogma_validate_streamql` | Validates a StreamQL expression. | **`query`** |
| `ogma_get_ws_messages_live` | Gets live WebSocket messages captured from browser instrumentation. | `host`, `limit` |
| `ogma_create_ws_replay_session` | Creates a WebSocket Replay session. | **`ws_connection_id`** |
| `ogma_connect_ws_replay` | Connects a WebSocket Replay session. | **`ws_session_id`** |
| `ogma_send_ws_replay_message` | Sends a message through a WebSocket Replay session. | **`ws_session_id`**, **`payload`**, `message_type` |
| `ogma_list_ws_replay_sessions` | Lists WebSocket Replay sessions. | `result_detail` |
| `ogma_get_ws_replay_messages` | Reads a WebSocket Replay session transcript, not captured history. Omit `cursor` to start; pass the returned `next_cursor` and drain while `has_more`. | **`ws_session_id`**, `cursor`, `limit`, `result_detail` |
| `ogma_get_ws_replay_message` | Reads one WebSocket Replay message without payload preview truncation; `payload_base64` marks base64-encoded bytes. | **`message_id`**, `result_detail` |
| `ogma_disconnect_ws_replay` | Disconnects a WebSocket Replay session, retaining its session and transcript; also cancels a pending connection. | **`ws_session_id`** |
| `ogma_browser_get_ws_frames` | Reads WebSocket frames captured by the embedded browser. | `limit`, `connection_url`, `direction` |
| `ogma_browser_start_ws_capture` | Starts browser-side WebSocket frame capture. | None. |
| `ogma_browser_send_ws_message` | Sends a WebSocket message from browser context. | **`payload`**, `connection_url` |

### Findings and Evidence

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_search_findings` | Searches findings by severity, reporter, text, limit, and offset. | `severity`, `reporter`, `q`, `limit`, `offset` |
| `ogma_get_finding` | Gets one finding by ID. | **`finding_id`** |
| `ogma_preview_finding_from_evidence` | Previews a finding draft from an HTTP entry without creating it. | **`entry_id`**, `reporter` |
| `ogma_create_finding` | Creates a finding with metadata, tags, confidence, remediation, and optional evidence links. | **`title`**, `severity`, `status`, `description`, `reporter`, `tags`, `dedupe_key`, `entry_id`, `replay_attempt_id`, `automate_result_id`, `ws_message_id`, `confidence`, `remediation`, `skip_dedup_check` |
| `ogma_update_finding` | Updates an existing finding. | **`finding_id`**, **`title`**, `severity`, `status`, `description`, `reporter`, `tags`, `dedupe_key`, `confidence`, `remediation` |
| `ogma_add_finding_tag` | Adds tags to a finding without replacing existing tags. | **`finding_id`**, **`tags`** |
| `ogma_link_finding_evidence` | Adds HTTP, Replay, Automate, captured WebSocket, or WS Replay message evidence to a finding. Supporting links do not replace its primary evidence. | **`finding_id`**, `entry_id`, `replay_attempt_id`, `automate_result_id`, `ws_message_id`, `ws_replay_message_id` |
| `ogma_delete_finding` | Deletes a finding. | **`finding_id`** |
| `ogma_create_finding_from_entry` | Creates a finding from a captured HTTP entry. Embeds the request and response headers and bodies as markdown HTTP evidence, with the response body truncated to 3000 characters. Adds a CVSS score from a supplied breakdown, CWE, PoC code, and references. | **`entry_id`**, **`title`**, **`severity`**, **`vulnerability_type`**, **`description`**, **`impact`**, **`remediation`**, `confidence`, `reporter`, `tags`, `affected_parameter`, `proof_of_concept`, `cvss_breakdown`, `cwe`, `poc_code`, `references`, `skip_dedup_check` |
| `ogma_get_finding_evidence_summary` | Summarizes linked evidence for a finding. | **`finding_id`** |
| `ogma_record_finding_verification` | Records an independent re-test verdict for a finding: `verified`, `refuted`, or `inconclusive`. The newest verdict stands, so a later refutation overrides an earlier confirmation, and the tool reports the row that was stored. | **`finding_id`**, **`state`**, **`method`**, **`reason`**, `evidence_entry_id`, `control_entry_id`, `canary_id` |
| `ogma_check_canary` | Creates a token using `label` and `purpose`, or rechecks an existing token using `canary_id` without creating another. Searches captured traffic for matching entries. A response-body match is read-back evidence; a request-body match only shows the token was sent. | **`canary_id`** or **`label`** and **`purpose`**, `finding_id`, `hosted_path`, `limit` |
| `ogma_export_findings_report` | Creates a findings report export. | **`format`**, `title`, `summary`, `scope`, `tester`, `include_evidence` |

### Exports

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_preview_export_plan` | Previews export contents and format without creating a job. | **`kind`**, **`format`**, `limit`, `q`, `severity`, `reporter` |
| `ogma_create_export_job` | Creates an export job for history, search results, findings, or Automate results. | **`name`**, **`kind`**, **`format`**, `limit`, `offset`, `scope`, `q`, `severity`, `reporter`, `run_id` |
| `ogma_get_export_job` | Gets one export job by ID. | **`export_id`** |
| `ogma_list_export_jobs` | Lists export jobs. | `limit`, `offset` |
| `ogma_get_export_download_info` | Gets download metadata for a completed export. | **`export_id`** |

### Replay and Request Sending

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_preview_replay_send` | Previews a Replay send and returns a confirmation token. | `http_entry_id`, `replay_session_id`, `method`, `path`, `query`, `body`, `result_detail` |
| `ogma_send_replay_request` | Sends a Replay request with the confirmation token. | **`confirmation_token`**, **`request_hash`**, `result_detail` |
| `ogma_create_replay_session_from_history` | Creates a Replay session from a captured HTTP entry. | **`entry_id`**, `name`, `result_detail` |
| `ogma_create_replay_session_raw` | Creates a Replay session from a raw request definition. | `name`, **`host`**, **`port`**, `tls`, `method`, `path`, `headers`, `body` |
| `ogma_get_replay_session` | Gets Replay session metadata and a paginated attempts list. | **`session_id`**, `attempts_limit`, `attempts_offset`, `result_detail` |
| `ogma_get_replay_attempt` | Gets one Replay attempt. | **`session_id`**, **`attempt_id`**, `result_detail` |
| `ogma_list_replay_sessions` | Lists Replay sessions. | `limit`, `offset`, `result_detail` |
| `ogma_create_replay_sequence` | Creates a multi-step Replay sequence from existing Replay sessions, in the order the steps run; `collection_id` overlays that collection's variables during a run. | **`name`**, **`session_ids`**, `collection_id` |
| `ogma_run_replay_sequence` | Runs a stored Replay sequence, which sends real outbound traffic. `plan` lists step indices in execution order; entries may repeat, omit, or reorder steps, and an omitted `plan` runs every stored step once in order. An empty `plan` is refused. | **`sequence_id`**, `plan` |
| `ogma_repeat_request` | Repeats an existing request with optional changes. | **`request_id`**, `params`, `headers`, `body`, `cookies`, `url`, `method`, `method_override`, `path`, `path_override`, `entry_id`, `headers_add`, `headers_remove`, `body_text`, `body_json`, `body_b64`, `body_base64`, `raw_request_base64`, `result_detail` |
| `ogma_replay_with_modifications` | Replays a captured HTTP request with field-level overrides and returns a response plus diff summary. | **`entry_id`**, `method_override`, `path_override`, `headers_add`, `headers_remove`, `body`, `body_text`, `body_json`, `body_b64`, `body_base64`, `raw_request_base64`, `request_id`, `method`, `path`, `headers`, `follow_redirects`, `timeout_secs`, `result_detail` |
| `ogma_http_request` | Sends a direct HTTP request through the MCP tool surface. With `raw_request_base64`, `max_responses` reads several response frames from the same connection instead of stopping at the first, and `followup_raw_request_base64` writes a request on that connection after the first response is read; a response the sent bytes did not ask for is how a request desync is confirmed rather than guessed. Both inputs apply to raw mode only. | **`host`**, `port`, `tls`, `method`, `path`, `headers`, `body_b64`, `method_override`, `path_override`, `headers_add`, `headers_remove`, `body`, `body_text`, `body_json`, `body_base64`, `raw_request_base64`, `max_responses`, `followup_raw_request_base64`, `result_detail` |
| `ogma_bulk_send_requests` | Sends a batch of requests. | **`base_session_id`**, **`payloads`**, **`placeholder`**, `max_requests` |
| `ogma_fetch_url` | Fetches a URL and returns response status, headers, and body preview. | **`url`**, `method`, `headers`, `body_b64`, `max_bytes` |
| `ogma_follow_redirect` | Fetches a URL, follows the redirect chain, and reports every hop. | **`url`**, `method`, `headers`, `body_b64`, `max_hops`, `timeout_secs` |
| `ogma_fuzz_parameter` | Replaces a `{{FUZZ}}` placeholder with wordlist values and clusters responses by status and size. | **`url`**, `method`, `headers`, `body_template`, **`wordlist`**, `timeout_secs`, `stop_on_match` |
| `ogma_multipart_upload` | Sends multipart form-data requests with text and file fields for upload testing. | **`url`**, **`fields`**, `headers`, `timeout_secs` |
| `ogma_test_login` | Tests a login endpoint with supplied or default credential pairs and reports evidence. | **`url`**, `credentials`, `username_field`, `password_field`, `submit_selector`, `success_pattern`, `failure_pattern`, `max_attempts` |

### Workflows and Automate

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_search_workflows` | Lists and filters workflows. | `workflow_type`, `enabled`, `limit`, `offset` |
| `ogma_get_workflow` | Gets one workflow by ID. | **`workflow_id`** |
| `ogma_get_workflow_run` | Gets one workflow run record. | **`run_id`** |
| `ogma_validate_workflow_import` | Validates a workflow bundle for import compatibility. | **`bundle_json`** |
| `ogma_get_workflow_safety` | Gets safety and permission classification for a workflow. | **`workflow_id`** |
| `ogma_preview_workflow_run` | Previews a workflow run before execution. | **`workflow_id`**, `input`, `trigger_entry_id` |
| `ogma_run_workflow` | Runs a workflow. | **`confirmation_token`**, **`definition_hash`**, `input_hash`, `input` |
| `ogma_cancel_workflow_run` | Cancels a workflow run. | **`run_id`** |
| `ogma_list_automate_sessions` | Lists Automate sessions. | `limit`, `offset` |
| `ogma_get_automate_session` | Gets one Automate session. | **`session_id`** |
| `ogma_create_automate_session` | Creates an Automate session with one injection point. `inject_into` selects it as `query:<name>`, `header:<name>`, or `body`; the default is the first query parameter, then the body. | **`entry_id`**, `name`, **`payloads`**, `inject_into`, `placeholder_start`, `placeholder_end`, `worker_count`, `delay_ms` |
| `ogma_run_automate_session` | Runs an Automate session. | **`session_id`** |
| `ogma_list_automate_runs` | Lists Automate runs. | **`session_id`**, `limit`, `offset` |
| `ogma_get_automate_run` | Gets one Automate run. | **`run_id`** |
| `ogma_cancel_automate_run` | Cancels an Automate run. | **`run_id`** |
| `ogma_list_automate_results` | Lists Automate results. | **`run_id`**, `limit`, `offset`, `min_status`, `max_status` |
| `ogma_get_automate_result` | Gets one Automate result. | **`run_id`**, **`seq`** |
| `ogma_load_skill` | Loads built-in MCP skill guidance into the assistant context. | **`skills`** |

### Scanner

Starting passive or active scans requires finding-write permission because scans can create findings. Listing scanner rules and active check categories does not.

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_run_passive_scan` | Runs passive scanner checks for one HTTP entry. | **`entry_id`** |
| `ogma_run_passive_scan_all` | Runs passive scanner checks across captured history. | None. |
| `ogma_list_scanner_rules` | Lists scanner detection rules. | None. |
| `ogma_list_active_checks` | Lists the active scanner check categories with their IDs and descriptions, and reports how many of them create findings. Stub categories are listed but never produce a finding. | None. |
| `ogma_scan_active` | Runs the active scanner, which sends proof payloads and creates findings only for classes it confirms from the response. Pass `entry_id` to scan one entry, or omit it to sweep recent history. Long-running, so it is exposed as a task; the synchronous path polls the job to a terminal state and reports `job_id`, progress counters, and `findings_created`. Requires finding-write permission. | `entry_id`, `checks`, `concurrency`, `delay_ms`, `scan_headers` |

### Intercept

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_get_intercept_status` | Gets current intercept state. | None. |
| `ogma_set_intercept_enabled` | Enables or disables intercept. | `request_enabled`, `response_enabled`, `websocket_enabled` |
| `ogma_list_intercept_queue` | Lists queued intercepted items. | None. |
| `ogma_get_intercept_item` | Gets one queued intercept item. | **`id`** |
| `ogma_forward_intercept_item` | Forwards an intercepted item, optionally modified. | **`id`**, `method`, `path`, `headers`, `body`, `status_override` |
| `ogma_drop_intercept_item` | Drops an intercepted item. | **`id`** |
| `ogma_intercept_and_modify` | Waits for a live intercepted request or response, applies JSON patches, regex replacements, or full body replacement, then forwards it. | **`direction`**, `host_pattern`, `path_pattern`, `wait_secs`, `json_patches`, `regex_replacements`, `body_b64`, `status_override`, `forward_unmatched` |

### Proxy, Scope, and Network

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_list_proxy_listeners` | Lists proxy listeners. | None. |
| `ogma_start_proxy_listener` | Starts a proxy listener. | **`listener_id`** |
| `ogma_stop_proxy_listener` | Stops a proxy listener. | **`listener_id`** |
| `ogma_list_scope_presets` | Lists scope presets. | None. |
| `ogma_create_scope_preset` | Stores a scope preset without activating it. Requires send permission. Each rule requires `pattern` and `include`; optional `rule_type` selects host, CIDR, path, or regex matching. Path rules use `pattern` for the host and `path_pattern` for the path. Activate the returned preset separately with `ogma_set_active_scope`. | **`name`**, **`rules`**, `httpql_expression` |
| `ogma_get_active_scope` | Gets the active scope. | None. |
| `ogma_set_active_scope` | Sets the active scope. | `preset_id` |
| `ogma_local_ips` | Lists local IP addresses useful for listeners and callbacks. | None. |
| `ogma_get_tls_info` | Gets TLS information for a target or captured connection. | **`host`**, `port` |

### Sitemap, Endpoints, and OAST

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_get_sitemap` | Gets the captured sitemap. | `host`, `show_api_only` |
| `ogma_get_sitemap_parameters` | Gets parameters discovered for one sitemap path. | **`host`**, **`port`**, **`path`** |
| `ogma_list_extracted_endpoints` | Lists endpoints extracted from traffic and frontend content. | `limit`, `offset` |
| `ogma_discovery_start` | Starts a background content-discovery job against an in-scope host and port; returns a job ID. | **`host`**, **`port`**, `tls`, `base_path`, `config` |
| `ogma_discovery_list` | Lists discovery jobs and their progress in the active project. | None. |
| `ogma_discovery_get` | Gets a discovery job's status and discovered results. | **`job_id`** |
| `ogma_discovery_cancel` | Requests cancellation of a running discovery job. | **`job_id`** |
| `ogma_import_openapi_spec` | Imports an OpenAPI specification to seed endpoints and request shapes. | **`spec_content`**, `base_url`, `collection_name` |
| `ogma_get_oast_config` | Gets OAST listener configuration. | None. |
| `ogma_get_oast_reachability` | Reports whether the configured OAST callback host can be reached from a target, with the reasons when it cannot and the steps that would fix it. Check it before trusting a blind payload: an unreachable callback produces a false negative that reads as not vulnerable. | None. |
| `ogma_list_oast_interactions` | Lists OAST interactions. Every filter is applied by the backend before the page is cut, so the total counts every match rather than the length of the page, and narrowing to one token label or one source address never hides a matching callback further down the feed. `token_label` is the injection point that carried the token: a query parameter name, a header name, or `body`. Labels are held in memory with their tokens, so a label whose token has aged out matches nothing rather than stale rows. | `limit`, `offset`, `token_id`, `token_label`, `protocol`, `source_ip`, `since` |

### History Annotation

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_set_entry_color` | Sets the color label for a history entry. | **`entry_id`**, **`color`** |
| `ogma_add_entry_tag` | Adds a tag to a history entry. | **`entry_id`**, **`tag`** |
| `ogma_remove_entry_tag` | Removes a tag from a history entry. | **`entry_id`**, **`tag`** |

### Browser Control

For choosing between snapshots, selectors, and screenshots, see the [browser guide](../guide/mcp-browser.md). Do not assume every browser tool accepts `tab_id` or `element_ref`; use only the inputs listed for that tool.

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_browser_launch` | Launches the Ogma browser. | `proxy_port` |
| `ogma_browser_navigate` | Navigates the browser to a URL. | **`url`**, `tab_id`, `wait_for_load`, `timeout_ms`, `result_detail` |
| `ogma_browser_get_dom` | Navigates and returns the rendered DOM plus optional selector results after JavaScript has run. | **`url`**, `wait_secs`, `selectors`, `js_eval`, `include_full_html` |
| `ogma_browser_screenshot` | Captures browser page state. | `tab_id`, `result_detail` |
| `ogma_browser_execute_js` | Executes JavaScript in the browser. | **`script`**, `tab_id` |
| `ogma_browser_get_source` | Gets the current page DOM source. | `tab_id`, `format`, `max_chars` |
| `ogma_browser_get_cookies` | Gets browser cookies. | `tab_id` |
| `ogma_browser_set_cookie` | Sets a browser cookie. | **`name`**, **`value`**, `domain`, `path`, `http_only`, `secure` |
| `ogma_browser_new_tab` | Opens a new browser tab. | `url` |
| `ogma_browser_close_tab` | Closes a browser tab. | `tab_id` |
| `ogma_browser_get_tabs` | Lists browser tabs. | `result_detail` |
| `ogma_browser_click` | Clicks an `element_ref` from a snapshot, or explicit `x` and `y` coordinates. | `element_ref`, `snapshot_id`, `x`, `y`, `button`, `click_count`, `modifiers`, `offset_x`, `offset_y`, `force`, `timeout_ms`, `tab_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_type_text` | Types text into the browser. | **`text`**, `tab_id`, `snapshot_id` |
| `ogma_browser_fill_input` | Sets an input using exactly one CSS `selector` or snapshot `element_ref`; an empty value clears it. Does not submit. | **`selector`**, `value`, `tab_id`, **`element_ref`**, `snapshot_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_fill_form` | Replaces text in several inputs, textareas, or contenteditable elements in one call, in the supplied order; each field uses exactly one `element_ref` or `selector` plus a `value`. Stops at the first failure and does not submit. | **`fields`**, `snapshot_id`, `tab_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_click_selector` | Clicks an element by selector. | **`selector`**, `tab_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_submit_form` | Submits a form. | `selector`, `tab_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_get_page_links` | Extracts links from the current page. | `tab_id` |
| `ogma_browser_get_page_forms` | Extracts forms from the current page. Set `include_templates` to `true` (default `false`) to add each form's absolute action URL, method, effective content type, successful controls with current values, submit controls, and CSRF-like `token_candidates`. Multipart forms point at `ogma_multipart_upload` instead of a synthesized body. Requires the `send_requests` permission. | `tab_id`, `include_templates` |
| `ogma_browser_form_to_replay` | Creates a Replay session from a form on the live page, reading current field values and the browser's live cookies at that moment, with Origin and Referer headers derived from the page. It does not send the request. | **`form_selector`**, `tab_id`, `name` |
| `ogma_browser_scroll` | Scrolls the current page. | `selector`, `x`, `y`, `tab_id` |
| `ogma_browser_wait_for_selector` | Waits for an element selector. | **`selector`**, `timeout_ms`, `tab_id`, `snapshot_id` |
| `ogma_browser_get_network_log` | Gets browser network events. | `host`, `since_ms`, `limit` |
| `ogma_browser_go_back` | Goes back in browser history. | `tab_id`, `snapshot_id` |
| `ogma_browser_go_forward` | Goes forward in browser history. | `tab_id`, `snapshot_id` |
| `ogma_browser_reload` | Reloads the page. | `tab_id`, `snapshot_id` |
| `ogma_browser_find_text` | Finds text in the current page. | **`text`**, `tab_id`, `snapshot_id` |
| `ogma_browser_clear_data` | Clears browser data. | `types` |
| `ogma_crawl_site` | Crawls a target through the embedded browser within the active scope and returns coverage data. | **`start_url`**, `max_pages`, `max_depth`, `wait_ms`, `tab_id` |

### Browser Elements and Waits

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_browser_snapshot` | Reads a compact semantic page tree with element references and state; `result_detail: "full"` returns the structured envelope with elements under `raw.elements` instead. Can request a delta from a previous snapshot. | `tab_id`, `previous_snapshot_id`, `changes_only`, `focus_ref`, `text`, `max_elements`, `max_text_length`, `include_hidden`, `max_depth`, `result_detail` |
| `ogma_browser_hover` | Hovers over a referenced element and reports newly visible menus or tooltips. | **`element_ref`**, `snapshot_id`, `offset_x`, `offset_y`, `modifiers`, `timeout_ms`, `tab_id` |
| `ogma_browser_select_option` | Selects dropdown options by value, label, or index and reports the selected values. | **`element_ref`**, `snapshot_id`, **`values`**, `match_mode`, `allow_first_match`, `timeout_ms`, `tab_id` |
| `ogma_browser_check` | Sets a checkbox or radio state explicitly instead of blindly toggling it. | **`element_ref`**, `snapshot_id`, `checked`, `timeout_ms`, `tab_id` |
| `ogma_browser_press_key` | Sends a key or key combination to the focused page or a referenced element. | **`key`**, `element_ref`, `snapshot_id`, `modifiers`, `repeat`, `delay_ms`, `tab_id` |
| `ogma_browser_focus` | Focuses a referenced element and reports its input capabilities. | **`element_ref`**, `snapshot_id`, `tab_id` |
| `ogma_browser_blur` | Removes focus from the currently focused element. | `tab_id`, `snapshot_id` |
| `ogma_browser_drag_and_drop` | Drags one referenced element onto another. | **`source_ref`**, **`target_ref`**, `snapshot_id`, `steps`, `tab_id` |
| `ogma_browser_scroll_to` | Scrolls to an element, page position, or within a referenced scroll container. | `target`, `element_ref`, `snapshot_id`, `container_ref`, `direction`, `amount`, `behavior`, `timeout_ms`, `tab_id` |
| `ogma_browser_wait_for` | Waits for an element/text/URL/navigation/dialog condition or page stability; supports an explicit sleep when necessary. | **`condition`**, `target`, `timeout_ms`, `stability_ms`, `tab_id`, `snapshot_id`, `result_detail` |
| `ogma_browser_handle_dialog` | Accepts or dismisses a JavaScript dialog, with optional prompt text and expected-dialog checks. | **`action`**, `prompt_text`, `expected_type`, `expected_message`, `tab_id`, `snapshot_id` |
| `ogma_browser_dialog_status` | Reports any pending JavaScript dialog without dismissing it. | None. |

### Browser Files, Popups, and Downloads

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_list_hosted_files` | Lists active-project hosted files and their IDs for uploads and artifact inspection. | `limit`, `offset` |
| `ogma_artifact_read_range` | Reads a bounded byte range of a hosted file rather than returning the entire file. | **`artifact_id`**, `offset`, `length` |
| `ogma_artifact_search` | Searches a bounded range of a UTF-8 hosted file for literal text and returns matching byte offsets. | **`artifact_id`**, **`query`**, `offset`, `max_bytes`, `max_matches` |
| `ogma_browser_file_upload` | Sets a file input from existing Ogma hosted-file IDs, not arbitrary client filesystem paths. | **`element_ref`**, `snapshot_id`, **`artifact_ids`**, `tab_id` |
| `ogma_browser_wait_for_popup` | Arms popup detection before an action, waits for a popup, or checks detection status. | **`action`**, `timeout_ms`, `switch_to_new_tab` |
| `ogma_browser_download_wait` | Detects an in-progress or completed browser download. Inspect its ID and state; detection does not imply completion or that it is the newest download. | `timeout_ms` |
| `ogma_browser_download_get` | Inspects one download and saves completed content as an artifact when available. | **`download_id`** |
| `ogma_browser_download_status` | Lists browser downloads and their current progress/state. | None. |

### Browser Identities, Storage, and Permissions

Browser permission tools below control website permissions such as camera or geolocation. They do not change the MCP server's tool permissions.

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_browser_context_create` | Creates an isolated browser identity and initial tab; returns `context_id` and `tab_id`. | `label`, `auth_profile_id`, `initial_url`, `retain_on_close` |
| `ogma_browser_context_clone` | Creates a clean context or copies the source context's cookies with `clone_mode: authenticated`; it is not a full storage clone. | **`context_id`**, `clone_mode`, `label` |
| `ogma_browser_context_close` | Closes a context and its tabs, clearing storage unless retention was requested at creation. | **`context_id`** |
| `ogma_browser_context_list` | Lists browser contexts and their state. | None. |
| `ogma_browser_auth_state_capture` | Captures cookies and web storage as a named, in-memory auth state; returns redacted metadata. | **`name`**, `tab_id`, `context_id`, `role`, `url` |
| `ogma_browser_auth_state_apply` | Restores a captured auth state; expiry metadata is not proof that the server accepts the session. | **`auth_state_id`**, `tab_id`, `context_id`, `url` |
| `ogma_browser_auth_state_list` | Lists captured auth states without their full secret values. | None. |
| `ogma_browser_auth_state_delete` | Deletes one captured auth state. | **`auth_state_id`** |
| `ogma_browser_storage_list` | Lists cookies and web-storage entries using shortened value previews. | `origin`, `storage_type` |
| `ogma_browser_storage_get` | Inspects one cookie or storage key with a shortened value preview. | **`storage_type`**, **`key`**, `origin` |
| `ogma_browser_storage_set` | Writes a cookie/storage value; accepts an Ogma `env:VARIABLE_NAME` reference. | **`storage_type`**, **`key`**, **`value`**, `origin`, `domain`, `path`, `http_only`, `secure`, `expires` |
| `ogma_browser_storage_delete` | Deletes one cookie or web-storage key. | **`storage_type`**, **`key`**, `origin` |
| `ogma_browser_permissions_set` | Grants, denies, or resets specified website permissions for an origin. | **`origin`**, **`permissions`**, `setting`, `context_id` |
| `ogma_browser_permissions_reset` | Clears browser permission overrides. | `context_id` |
| `ogma_browser_permissions_get` | Queries website permission states for an origin. | **`origin`**, `permissions` |

### Browser Diagnostics, Evidence, and Recovery

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_browser_network_delta` | Gets bounded network entries after a cursor, retaining full URLs, timing, errors, and HTTP History IDs when available. | `since_entry_id`, `resource_types`, `status_filter`, `failed_only`, `max_entries` |
| `ogma_browser_console_delta` | Gets new console entries, including source URL, line, and column when provided by the browser. | `since_entry_id`, `levels`, `max_entries` |
| `ogma_browser_action_correlation` | Gets traffic/events associated with an action's time window, or lists recent actions. Timing alone does not prove causation. | `browser_action_id`, `limit` |
| `ogma_browser_snapshot_save` | Archives the current snapshot for later comparison; the archive retains up to 20 snapshots. | `label` |
| `ogma_browser_page_state_compare` | Compares two archived snapshots and reports element/state differences, optionally ignoring volatile values and roles. | **`snapshot_id_a`**, **`snapshot_id_b`**, `ignore_volatile`, `ignore_roles` |
| `ogma_browser_trace_start` | Starts a lightweight action trace; `detailed` adds console and network references. | `level`, `label`, `context_id` |
| `ogma_browser_trace_stop` | Stops a trace and retains its events in memory. | **`trace_id`** |
| `ogma_browser_trace_export` | Saves a stopped trace as a JSON hosted-file artifact in the active project. | **`trace_id`** |
| `ogma_browser_trace_list` | Lists traces and their recording/export state. | None. |
| `ogma_browser_trace_note` | Appends a note to all currently recording traces. | **`note`** |
| `ogma_browser_human_takeover_start` | Pauses agent browser actions for a manual checkpoint, with a bounded timeout. | `reason`, `context_id`, `tab_id`, `timeout_ms` |
| `ogma_browser_human_takeover_complete` | Returns control after manual interaction and refreshes the page snapshot. | **`takeover_id`** |
| `ogma_browser_human_takeover_status` | Checks whether manual control is active and reports the remaining time. | None. |
| `ogma_browser_health` | Reports debugger-bridge health and recent crash/disconnection information. | None. |
| `ogma_browser_recover` | Attempts bridge recovery, preserving evidence by default; can report `relaunch_required`. | `preserve_evidence` |

### Authentication and Authorization Testing

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_auth_capture_profile` | Captures cookies, storage, detected auth tokens, and CSRF candidates from the embedded browser. | **`name`**, `role`, `url`, `tab_id`, `wait_ms` |
| `ogma_auth_list_profiles` | Lists captured auth profiles with secret values summarized. | None. |
| `ogma_auth_apply_profile` | Applies a captured auth profile to the embedded browser for role or account switching. | **`profile_id`**, `url`, `tab_id`, `wait_ms` |
| `ogma_auth_refresh_csrf` | Refreshes CSRF token candidates from the current page, cookies, storage, meta tags, and hidden inputs. | `profile_id`, `url`, `tab_id`, `wait_ms` |
| `ogma_login_replay_auto` | Auto-detects a login form, submits credentials in the embedded browser, and captures an auth profile. | **`login_url`**, **`username`**, **`password`**, **`profile_name`**, `role`, `tab_id`, `wait_ms` |
| `ogma_authz_matrix_test` | Replays one captured request as multiple auth profiles to compare access-control outcomes. | **`request_id`**, **`profile_ids`**, `mutations`, `entry_id` |

### Reusable Login Journeys

Unlike in-memory auth profiles, login journeys are persisted per project. Credentials reference Ogma environment-variable IDs. All configured verification checks must pass; a login form submission alone is not successful authentication.

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_auth_journey_record` | Saves login steps, credential references, verification checks, and optional manual MFA checkpoints. This defines a journey; it does not record arbitrary clicks automatically. | **`name`**, `role`, **`login_url`**, **`username_env_var_id`**, **`password_env_var_id`**, `username_selectors`, `password_selectors`, `submit_selectors`, `steps`, **`verification`**, `mfa`, `mfa_reason`, `mfa_timeout_ms` |
| `ogma_auth_journey_list` | Lists saved login journeys in the active project with session secrets redacted. | None. |
| `ogma_auth_journey_replay` | Executes a saved login journey, verifies authentication, and saves the refreshed session; pauses for manual MFA when configured. | **`journey_id`**, `tab_id` |
| `ogma_auth_journey_verify` | Checks URL, DOM, cookies, and an optional verification request against the current session. | **`journey_id`**, `tab_id` |
| `ogma_auth_journey_ensure` | Verifies the current session, attempts saved-state restoration, and replays login only if still necessary. | **`journey_id`**, `tab_id` |
| `ogma_auth_journey_resume` | Continues a journey after its manual checkpoint and verifies the resulting session. | **`journey_id`**, **`takeover_id`**, `tab_id` |

### Utilities and Analysis

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_fetch_sourcemap` | Fetches and inspects a JavaScript source map. | **`url`**, `base_url` |
| `ogma_proto_decode` | Decodes protobuf payloads using configured schemas. | **`data_b64`**, `content_type` |
| `ogma_decode_jwt` | Decodes JWT headers and claims. | **`token`** |
| `ogma_decode_response` | Decodes, decompresses, or transforms response bodies with ordered operations such as base64, gzip, deflate, brotli, URL, HTML entity, and hex handling. | **`input`**, `input_is_b64`, **`operations`**, `max_output_bytes` |
| `ogma_search_js_secrets` | Searches JavaScript responses for exposed secrets and endpoints. | `host`, `patterns` |
| `ogma_compare_responses` | Compares two responses. | **`entry_id_a`**, **`entry_id_b`**, `mode` |
| `ogma_bytes_transform` | Performs byte transforms such as encoding, decoding, XOR, hashing, and extraction. | **`operation`**, **`data`**, `key`, `output_encoding`, `offset`, `length`, `min_len` |
| `ogma_wasm_inspect` | Inspects a WebAssembly module. | **`wasm_b64`**, `data_encoding` |
| `ogma_fingerprint_target` | Identifies target technology from captured traffic and responses. | `host`, `entry_limit` |
| `ogma_sign_request` | Computes HMAC-SHA256 request signature headers for applications that use client-side signing schemes. | **`key`**, **`method`**, **`path`**, `params` |
| `ogma_find_in_response` | Fetches up to 10 URLs and searches response bodies for a regex with compact context. | **`urls`**, **`pattern`**, `headers`, `context_chars`, `max_matches_per_url`, `case_insensitive`, `timeout_secs` |
| `ogma_think` | Records structured reasoning or plan text inside the MCP session. | **`thought`** |
| `ogma_explain_capabilities` | Returns the MCP server capability summary. | None. |

### Active Probe Helpers

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_run_active_probe_workflow` | Runs a bounded vulnerability-specific probe against a captured request. Modules include IDOR/BOLA, CORS, SSRF OAST, XSS reflection/storage, SQLi timing/error, path traversal, SSTI, upload bypass, GraphQL introspection/authorization, JWT manipulation, and rate limit checks. | **`probe`**, **`request_id`**, `entry_id`, `target_param`, `profile_ids`, `values`, `origins`, `max_cases` |
| `ogma_test_race` | Sends one request concurrently and reports the mode status, the responses that deviated from it, and a verdict. Use it for single-use operations: several successful responses to an operation that succeeds once show that it is not atomic. Pass `request_id` for a captured entry, or `host` and `port` with the rest of the request explicitly. Set `http2` to send every request as a concurrent stream on one connection (single-packet), which is the variant that wins tight windows when the target speaks HTTP/2; the default opens one connection per request. A deviation is evidence about concurrency handling only, and a uniform batch is not proof of atomicity, so confirm from the state the operation changed. | `request_id`, `entry_id`, `method`, `host`, `port`, `tls`, `path`, `query`, `params`, `headers`, `body_b64`, `concurrency`, `stagger_ms`, `http2` |
| `ogma_test_smuggling` | Sends CL.TE and TE.CL desync probes over raw TCP and reports the probe results, the candidates, and a verdict. Headers passed in `headers` ride on the probe request only; the follow-up request that measures the desync is always sent without them. The probe is heuristic and often wrong in both directions: a front end that closes the connection after the first request, or one that rejects the conflicting framing with a 400, probes the same as a vulnerable one, and a negative result is not proof of safety. Confirm before reporting: replay the probe bytes with `ogma_http_request` in raw mode, passing them as `raw_request_base64` with `max_responses` set to 2 to read the response the bytes did not ask for, then send a plain request with `followup_raw_request_base64` on the same connection and compare the two statuses. HTTP/1.x only. | **`host`**, **`port`**, `tls`, `path`, `timeout_ms`, `headers` |
| `ogma_test_hpp` | Sends HTTP parameter pollution variations for the named parameters, then reports which variation changed the response status or body, plus a verdict. Use it when a parameter is validated in one component and consumed in another, so a duplicate name may resolve differently in each. A changed response shows that duplicate parameters are handled differently; it does not by itself prove that a control was bypassed. `headers` is sent on every request, the baseline included, so a Cookie or Authorization there probes an endpoint that needs credentials; with no headers the requests carry no cookies and no authentication, so a variation that changes nothing on a login-gated endpoint proves nothing. | **`host`**, **`port`**, **`params`**, `tls`, `path`, `base_value`, `test_value`, `timeout_ms`, `headers` |
| `ogma_list_nuclei_templates` | Lists the template scanner templates bundled with Ogma, with severity and what a match means. Read this before `ogma_run_nuclei` to pick one by name. | None. |
| `ogma_run_nuclei` | Runs one template against a target URL and reports every match. It creates no findings. Pass `template` for a bundled template or `template_yaml` for your own document, not both. The parser is a subset of nuclei: status, word, and regex matchers, `matchers-condition`, and regex extractors. Matcher types outside that subset, including DSL expressions, are skipped rather than evaluated, and the tool does not run templates that a full nuclei install would accept. Templates check exposure and misconfiguration surfaces the passive scanner cannot see, such as an exposed `.env`, `.git/config`, an actuator endpoint, or a server-status page. | **`target`**, `template`, `template_yaml` |
| `ogma_record_test_attempt` | Records that one endpoint, parameter, or vector was tested and what came of it, so a later session can tell a dead end from an untested point. Only `no_signal` retires a point; `transport_error` means the probe never reached the target, so it proves nothing about the vector. | **`host`**, **`port`**, **`path`**, **`vector`**, **`outcome`**, **`reason`**, `parameter`, `payload_label`, `evidence_entry_id` |
| `ogma_list_test_attempts` | Lists recorded test attempts, newest first, and groups them by host, port, path, parameter, and vector, reporting each point's deciding attempt, how many attempts it has, and whether it is exhausted. A point is exhausted only when its deciding outcome is `no_signal`; a later `transport_error` does not clear one. | `host`, `port`, `path`, `vector`, `limit` |

### Direct WebSocket Testing

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_websocket_connect` | Connects to a `ws://` or `wss://` URL, sends messages, and returns a transcript. | **`url`**, **`messages`**, `headers`, `timeout_secs` |
| `ogma_ws_capture_history` | Saves a WebSocket transcript from `ogma_websocket_connect` as structured Ogma history for review and evidence linking. | **`url`**, **`transcript`**, `label` |

### Match and Replace

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_list_match_replace_rules` | Lists Match & Replace rules. | None. |
| `ogma_create_match_replace_rule` | Creates a Match & Replace rule; workflow operations require workflow\_id. | **`name`**, `enabled`, **`direction`**, **`operation`**, **`match_value`**, `match_mode`, `replace_value`, `filter_method`, `filter_host`, `filter_path`, `filter_httpql`, `position`, `workflow_id` |
| `ogma_toggle_match_replace_rule` | Enables or disables a Match & Replace rule. | **`rule_id`**, **`enabled`** |
| `ogma_delete_match_replace_rule` | Deletes a Match & Replace rule. | **`rule_id`** |

### Environment Variables

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_list_env_vars` | Lists environment variable names and metadata. | None. |
| `ogma_set_env_var` | Creates or updates an environment variable. | **`name`**, **`value`**, `scope`, `is_secret` |
| `ogma_get_env_var_value` | Reads an environment variable value when permitted. | **`name`** |

### Projects, Notes, Todos, and Session

Project switching affects the active project in Ogma, not only the requesting agent. Coordinate with other clients. The note/todo tools below are an **in-memory MCP-session scratchpad**, not the application's persistent Notes page. Preserve the session report before disconnecting or restarting MCP.

| Tool | What it does | Inputs |
| --- | --- | --- |
| `ogma_list_projects` | Lists projects. | None. |
| `ogma_switch_project` | Switches the active project. | `project_id`, `project_name` |
| `ogma_start_pentest_session` | Creates a structured assessment plan and, by default, a session-local note/checklist for the target. Does not run a full scan automatically. | **`target_url`**, `objective`, `mode`, `create_scratchpad` |
| `ogma_get_coverage_status` | Summarizes the current session's checklist progress and remaining coverage; not proof of complete testing. | None. |
| `ogma_recommend_skills` | Suggests built-in skill guidance from observed technologies, paths, headers, and other supplied context. | `observations`, `paths`, `content_types`, `headers`, `technologies`, `response_snippets`, `notes` |
| `ogma_note_create` | Creates a note. | **`title`**, **`content`**, `category` |
| `ogma_note_list` | Lists notes. | `category` |
| `ogma_note_get` | Gets one note. | **`id`** |
| `ogma_note_update` | Updates a note. | **`id`**, `title`, `content`, `category` |
| `ogma_note_delete` | Deletes a note. | **`id`** |
| `ogma_todo_create` | Creates a todo. | **`task`**, `priority` |
| `ogma_todo_list` | Lists todos. | `status`, `priority` |
| `ogma_todo_update` | Updates a todo. | **`id`**, `task`, `priority`, `status` |
| `ogma_todo_mark_done` | Marks a todo done. | **`id`** |
| `ogma_todo_delete` | Deletes a todo. | **`id`** |
| `ogma_finish_session` | Finalizes the MCP session with summary, methodology, and recommendations. | **`summary`**, **`methodology`**, **`recommendations`** |
| `ogma_get_session_report` | Gets the current MCP session report. | None. |

## Relationship to Workspace AI

The MCP server is a protocol server used by external tools. The in-app Workspace AI is a Vue/browser feature that calls configured AI providers directly and exposes its own frontend tool list. See [Workspace AI](../guide/workspace-ai.md).