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. For an end-to-end interaction sequence, see Browser automation with MCP.

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.

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:

{
  "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.

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.

All tools are advertised regardless of permissions. Legacy profile flags no longer filter the tool list. See 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.

{
  "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"]
  }
}

{
  "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.

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