---
url: https://docs.ogmabox.com/pt/reference/mcp-tools.md
description: >-
  Referência completa do MCP do Ogma com finalidades e entradas de ferramentas,
  recursos, prompts, permissões, paginação e tratamento de resultados.
---

# Recursos e ferramentas MCP {#mcp-resources-and-tools}

O servidor MCP do Ogma é destinado a clientes MCP externos como Codex, Claude Code, Cursor e outros hosts de Model Context Protocol. Ele é separado do assistente de IA integrado à aplicação.

O MCP expõe quatro interfaces de descoberta:

* **Recursos**: destinos de leitura com nome que um cliente MCP pode abrir.
* **Modelos de recursos**: destinos de leitura parametrizados para uma entrada, achado, fluxo de trabalho, execução, exportação ou objeto de Reenvio específico.
* **Ferramentas**: ações que podem ser chamadas. Algumas são somente leitura. Outras exigem flags de inicialização do servidor.
* **Prompts**: instruções reutilizáveis que ajudam um agente a planejar uma inspeção, um novo teste ou um relatório. Obter um prompt não executa suas ferramentas.

Para endpoints de conexão e configuração de clientes, consulte [Configuração do MCP](/pt/mcp-setup.md). Para uma sequência completa de interação, consulte [Automação do navegador com MCP](/pt/guide/mcp-browser.md).

Esta referência cobre a implementação atual: **255 ferramentas**, 17 recursos, 9 modelos de recursos e 12 prompts. Todas as ferramentas são anunciadas; os controles de permissão ainda se aplicam quando elas são chamadas. Versões instaladas mais antigas podem expor menos ferramentas. Descubra o catálogo do seu servidor em execução antes de escolher uma ferramenta.

## Métodos do protocolo {#protocol-methods}

Estes são nomes de métodos JSON-RPC, não caminhos de URL separados. Um cliente MCP gerencia o ciclo de vida da conexão por [HTTP ou stdio](/pt/mcp-setup.md#connection-addresses).

| Método | Finalidade |
| --- | --- |
| `initialize` | Negocia a versão do protocolo e as capacidades do servidor e do cliente. |
| `notifications/initialized` | Informa ao servidor que a inicialização foi concluída; esta notificação não tem ID de requisição. |
| `tools/list` | Descobre ferramentas e seus esquemas de argumentos, seguindo `nextCursor`. |
| `tools/call` | Executa uma ferramenta usando `name` e `arguments`. |
| `resources/list` | Lista recursos somente leitura com nome. |
| `resources/templates/list` | Lista modelos de URI para ler objetos individuais. |
| `resources/read` | Lê um recurso usando seu `uri` completo. |
| `prompts/list` | Descobre prompts reutilizáveis e seus argumentos. |
| `prompts/get` | Recupera as mensagens de um prompt usando `name` e argumentos opcionais de texto. |

## Descobrir e chamar ferramentas {#discover-and-call-tools}

Nomes como `ogma_search_http_history` são identificadores de ferramentas MCP, não rotas HTTP individuais. Chame-as por `tools/call` na sua conexão MCP.

1. Inicialize a conexão com seu cliente MCP.
2. Chame `tools/list`. O Ogma retorna até **40 ferramentas por página**. Passe cada `nextCursor` retornado como `params.cursor` até ele deixar de aparecer; caso contrário, a maioria das ferramentas do navegador estará ausente no cliente.
3. Leia o `inputSchema` de cada ferramenta para tipos de campos, valores de enumeração, valores padrão, limites e formatos de objetos aninhados. Não invente argumentos com base no nome da ferramenta.
4. Leia `ogma://mcp/permissions` e `ogma://mcp/tool-guide` antes de realizar ações.
5. Chame a ferramenta selecionada com um objeto JSON em `arguments`.

Exemplo de requisição JSON-RPC em uma conexão inicializada:

```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 retornados por ferramentas de listagem e pesquisa em vez de adivinhá-los. Pesquisas no histórico e em achados usam `limit`/`offset`; ferramentas de diferenças do navegador usam `since_entry_id`. Nenhum deles é o cursor opaco usado por `tools/list`.

## Leitura de resultados {#reading-results}

Prefira `result.structuredContent`. O bloco de conteúdo de texto contém o mesmo envelope JSON para clientes que só suportam resultados de texto. Exceção: o resultado padrão de `ogma_browser_snapshot` não tem conteúdo estruturado, e seu conteúdo de texto é a árvore legível; use `result_detail: "full"` para seus elementos estruturados. Na ponte REST local, interprete a string JSON em `result` em vez disso; essa ponte não é o transporte MCP.

Em uma falha de ferramenta na ponte REST, o valor interpretado é `{ "error": "..." }`, com o envelope de erro serializado da ferramenta dentro dessa string. Um status HTTP de sucesso da ponte sozinho não significa que a ferramenta teve sucesso.

| Campo do envelope | Significado |
| --- | --- |
| `ok` | Se a operação da ferramenta teve sucesso. Inspecione também `isError` no resultado MCP. |
| `workflow_stage`, `summary` | Contexto da operação e uma explicação breve. |
| `evidence`, `hypotheses` | Evidências observadas e interpretações separadas, não confirmadas. |
| `next_actions`, `use_next_tools` | Trabalho de acompanhamento sugerido e direcionamento de ferramentas. |
| `artifacts` | Referências a evidências ou arquivos gerados quando disponíveis. |
| `raw` | Dados específicos da ferramenta. Presente nas rotas estruturadas; ferramentas compactas só o incluem com `result_detail: "full"`. Pode ser um objeto, uma matriz ou texto; não presuma um formato universal. |

Ferramentas de captura de tela também retornam um bloco de imagem MCP nativo. Leia o bloco de imagem em vez de esperar dados de imagem base64 nos metadados JSON. Uma captura semântica do navegador retorna uma árvore de texto compacta por padrão; passe `result_detail: "full"` para seus elementos estruturados em `raw.elements`. As diferenças de rede e console do navegador contêm entradas estruturadas.

Uma chamada de validação bem-sucedida ainda pode retornar `valid: false` nos dados. Uma falha de execução de ferramenta usa `isError: true`; requisições de protocolo inválidas usam erros JSON-RPC. Leia o diagnóstico antes de tentar novamente. Erros do backend podem incluir um status HTTP, endpoint e texto de diagnóstico limitado; `[truncated]` significa que o diagnóstico foi encurtado, não que a operação teve sucesso.

Essas convenções de resultado usam o [formato de resultados de ferramentas](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-result) do MCP.

## Recursos {#resources}

| Recurso | O que retorna |
| --- | --- |
| `ogma://status` | Saúde e estado atuais do backend. |
| `ogma://projects` | Todos os projetos do Ogma. |
| `ogma://project/current` | Projeto ativo atual. |
| `ogma://instances` | Instâncias de listener do proxy. |
| `ogma://http-history/recent` | As 20 entradas HTTP mais recentes sem conteúdo de corpo. |
| `ogma://ws-history/recent` | As 20 conexões WebSocket mais recentes. |
| `ogma://findings` | Até 50 achados. |
| `ogma://workflows` | Fluxos de trabalho configurados. |
| `ogma://workflow-runs/recent` | Os 20 registros de execução de fluxos de trabalho mais recentes. |
| `ogma://migration/workflows` | Relatório de compatibilidade de migração de fluxos de trabalho. |
| `ogma://exports/recent` | Os 10 trabalhos de exportação mais recentes. |
| `ogma://capabilities` | Resumo de capacidades do servidor MCP. |
| `ogma://mcp/permissions` | Flags atuais de permissão do MCP. |
| `ogma://mcp/tool-guide` | Direcionamento de ferramentas para agentes, convenções de saída e sequências recomendadas de navegador e testes. |
| `ogma://mcp/report-guide` | Sequência de montagem de relatórios, requisitos de evidências e verificações de qualidade. |
| `ogma://mcp/resume` | Contexto durável de recuperação do projeto ativo: pontos de controle salvos e atividade recente de ferramentas. |
| `ogma://replay/sessions/recent` | As 20 sessões de Reenvio mais recentes. |

## Modelos de recursos {#resource-templates}

| Modelo | O que retorna |
| --- | --- |
| `ogma://http-history/{entry_id}` | Uma entrada do histórico HTTP. |
| `ogma://ws-history/{connection_id}` | Uma conexão WebSocket. |
| `ogma://findings/{finding_id}` | Um achado. |
| `ogma://workflows/{workflow_id}` | Um fluxo de trabalho. |
| `ogma://workflow-runs/{run_id}` | Uma execução de fluxo de trabalho. |
| `ogma://exports/{export_id}` | Um trabalho de exportação. |
| `ogma://replay/sessions/{session_id}` | Uma sessão de Reenvio. |
| `ogma://replay/attempts/{session_id}/{attempt_id}` | Uma tentativa de Reenvio. |
| `ogma://workflow-safety/{workflow_id}` | Classificação de segurança e permissões necessárias de um fluxo de trabalho. |

Leia essas URIs com `resources/read`, não com um HTTP GET para `ogma://`. Substitua o ID no modelo de recurso antes de lê-lo. Recursos retornam texto em `contents`; eles não usam o envelope de resultado de ferramentas descrito acima.

## Prompts {#prompts}

Descubra com `prompts/list` e depois use `prompts/get` com `name` e um objeto `arguments`. Os valores dos argumentos de prompts são strings. Argumentos obrigatórios aparecem em negrito abaixo.

| Prompt | Argumentos | O que prepara |
| --- | --- | --- |
| `analyze_http_entry` | **`entry_id`** | Inspeciona uma troca HTTP capturada em busca de problemas de segurança sustentados por evidências. |
| `summarize_project_security_state` | Nenhum | Resume achados e prioridades de correção do projeto ativo. |
| `triage_findings` | `severity` | Prioriza achados, opcionalmente dentro de uma severidade. |
| `investigate_suspicious_host` | **`host`** | Revisa tráfego capturado para um nome de host ou IP. |
| `review_workflow_migration_report` | Nenhum | Explica problemas de compatibilidade de fluxos de trabalho e etapas de migração. |
| `generate_retest_plan` | **`finding_id`** | Prepara etapas de reprodução e critérios de aprovação ou reprovação para um achado. |
| `create_finding_from_http_evidence` | **`entry_id`** | Analisa evidências e orienta a criação de achados quando permitida. |
| `prepare_evidence_export` | **`export_kind`** | Planeja uma exportação de `http_history`, `findings` ou `automate_results`. |
| `retest_http_entry_with_replay` | **`entry_id`** | Orienta a sequência de prévia e confirmação de Reenvio. |
| `run_workflow_safely` | **`workflow_id`** | Inspeciona efeitos colaterais de um fluxo de trabalho, mostra uma prévia e executa quando permitido. |
| `pentest_web_target` | **`target_url`**, `objective` | Planeja uma avaliação em etapas, orientada por evidências, de um destino autorizado. |
| `solve_web_challenge` | **`challenge_url`**, `goal` | Planeja a investigação de um desafio web e a coleta de evidências. |

## Permissões de ferramentas {#tool-permissions}

A maioria das ferramentas de inspeção está sempre disponível. Ações de alteração ou de saída são controladas por flags de inicialização de `ogma-mcp`:

| Flag de permissão | Habilita |
| --- | --- |
| `--allow-write-findings` | Escrita de achados e geração de relatórios; também alterações compartilhadas do projeto, como edições de variáveis de ambiente e Localizar e substituir. |
| `--allow-export-data` | Criação de trabalhos de exportação. Ler metadados de exportações existentes e informações de download não exige essa flag. |
| `--allow-read-secrets` | Valores de variáveis de ambiente sem mascaramento. É separado da permissão de modificar variáveis. |
| `--allow-send-requests` | Envios de Reenvio/Automação, requisições diretas e em lote, interação com o navegador, descoberta, rastreamento, jornadas de autenticação, sondagens ativas, WebSockets e troca de projeto. |
| `--allow-run-workflows` | Ferramentas de prévia, execução e cancelamento de fluxos de trabalho. A execução de Automação usa a permissão de envio em vez disso. |
| `--allow-intercept-control` | Leituras de estado e fila de interceptação, alterações da fila e controle do estado de interceptação. |

Os controles de permissão são verificados quando uma ferramenta é chamada; listar uma ferramenta não significa que suas ações estão habilitadas. Ferramentas de observação do navegador podem inspecionar um navegador já em execução, mas controlá-lo e gerenciar seus contextos exige `allow_send_requests`. Jornadas de autenticação também exigem essa permissão, incluindo chamadas de listagem e verificação. Notas e tarefas locais da sessão não exigem permissão de escrita do projeto.

Não existem cotas de atividade por minuto ou por sessão. Ferramentas individuais ainda aplicam seus próprios tamanhos de entrada, tamanhos de lote, tempos limite e verificações de escopo. A execução de fluxos de trabalho pode precisar de permissões adicionais de envio ou escrita de achados conforme as operações do fluxo. Consulte [Configuração e permissões](/pt/mcp-setup.md#permissions).

Todas as ferramentas são anunciadas independentemente das permissões. Flags de perfil legadas não filtram mais a lista de ferramentas. Consulte [Descoberta e despacho de ferramentas](#tool-discovery-and-dispatch).

## Catálogo de ferramentas {#tool-catalog}

### Recuperação após perda de contexto {#recovering-after-context-loss}

Depois de reconectar ou perder o contexto da conversa, chame `ogma_resume_session` antes de iniciar outra avaliação. Verifique o projeto ativo, o último ponto de controle e os resultados recentes das ferramentas. Use `check_live: true` para verificações limitadas somente leitura de referências salvas; isso não repete ações. Atualize as capturas semânticas do navegador antes de reutilizar referências de elementos.

Salve um ponto de controle antes de uma transferência de trabalho ou uma pausa longa. A atividade das ferramentas registra o que foi executado; ela não consegue inferir o próximo teste que você pretendia realizar. Mantenha o objetivo, as conclusões, as incertezas e as próximas etapas explícitos, e referencie evidências por ID em vez de copiar grandes corpos de resposta para o ponto de controle.

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

Salve um ponto de controle antes de transferir o trabalho ou compactar o contexto. Registre explicitamente seu objetivo, o trabalho concluído, as incertezas, os IDs de evidências e as próximas etapas: o registro automático de atividade armazena referências e resultados, não os conteúdos das requisições nem sua intenção. Uma chamada iniciada sem resultado concluído tem um desfecho desconhecido; inspecione o estado atual antes de tentar um envio novamente.

Os registros de recuperação são duráveis e restritos ao projeto. Com `assessment_id`, as leituras ficam limitadas àquela avaliação; omita-o nas leituras de recuperação para inspecionar a atividade de todo o projeto. As notas e tarefas existentes locais da sessão têm outra finalidade e não devem ser confundidas com uma transferência durável de trabalho.

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_save_checkpoint` | Acrescenta uma transferência durável de trabalho. `next_steps` é uma matriz de ações explícitas; `references` associa nomes a IDs salvos. Não executa o plano. | **`objective`**, **`progress`**, **`next_steps`**, `uncertainties`, `references` |
| `ogma_resume_session` | Lê o projeto ativo, o último ponto de controle, a atividade recente e as orientações de recuperação. Verificações em tempo real opcionais inspecionam referências salvas sem repetir ações. | `check_live` |
| `ogma_get_session_activity` | Lê pontos de controle e atividade de ferramentas, dos mais recentes para os mais antigos. Os horários são milissegundos Unix UTC. Para paginar, passe tanto `before_ms` quanto `before_id` do cursor retornado. | `kind`, `id`, `since_ms`, `until_ms`, `before_ms`, `before_id`, `search`, `limit` |

Cada linha explica a ferramenta e lista suas entradas de nível superior. **Entradas em negrito são obrigatórias pelo esquema**; outras entradas são opcionais. Algumas ferramentas exigem escolher entre entradas (por exemplo, uma origem de Reenvio ou um alvo de clique); suas descrições e a validação em execução explicam essas combinações. Para campos aninhados e tipos exatos, leia o `inputSchema` da ferramenta em execução.

Toda ferramenta também aceita um `assessment_id` opcional (uma string não vazia, com no máximo 200 caracteres). Reutilize-o para manter o contexto de recuperação de uma avaliação agrupado. Ele não altera o projeto ativo nem concede permissões. Essa entrada comum não é repetida nas tabelas abaixo.

### Descoberta e despacho de ferramentas {#tool-discovery-and-dispatch}

O servidor anuncia todas as ferramentas registradas. Use as ferramentas de descoberta de capacidades e contratos para identificar uma operação e inspecionar suas entradas antes de chamá-la; você não precisa alterar um perfil para expô-la. Consulte [Configuração do MCP](/pt/mcp-setup.md#tool-discovery).

Use `ogma_browser` para ações do navegador integrado (`snapshot`, `fill_input`, `fill_form`, `console_delta`, `network_delta` e o restante da família de navegador) e `ogma_search` para domínios de pesquisa como `http_history`, `findings` e `ws_history`. As ferramentas específicas equivalentes continuam disponíveis.

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_find_tools` | Pesquisa todo o catálogo por palavras-chave da tarefa. Uma consulta pelo nome exato de uma ferramenta retorna seu contrato completo; `include_schema` também solicita contratos para correspondências por palavras-chave. Todas as palavras de pesquisa devem corresponder, e um resultado truncado ou vazio não prova que uma capacidade esteja ausente. O limite padrão é 5, e o máximo é 10. | **`query`**, `limit`, `include_schema` |
| `ogma_call_tool` | Executa uma ferramenta registrada do Ogma pelo nome. Entradas diferentes de `tool` são encaminhadas para a ferramenta indicada; suas permissões ainda se aplicam. | **`tool`** |
| `ogma_browser` | Controla o navegador integrado pelo nome da ação. Qualquer outra ferramenta `ogma_browser_*` é acessada pelo sufixo do nome, por exemplo `action: "snapshot"` para `ogma_browser_snapshot`. | **`action`**, `selector`, `tab_id`, `url`, `js`, `text`, `value`, `key`, `cookie`, `timeout_ms` |
| `ogma_search` | Pesquisa domínios de dados do Ogma por um único ponto de entrada. Qualquer outra ferramenta `ogma_search_*` é acessada pelo sufixo do nome. | **`domain`**, `q`, `limit`, `offset` |

### Histórico HTTP e consultas {#http-history-and-querying}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_search_http_history` | Pesquisa o histórico HTTP com HTTPQL e retorna metadados de requisições e respostas. | `q`, `limit`, `offset`, `result_detail` |
| `ogma_get_http_entry` | Obtém uma entrada HTTP por ID, opcionalmente com prévias de corpos. | **`entry_id`**, `include_body_preview`, `result_detail` |
| `ogma_get_http_entry_body` | Obtém o corpo completo da requisição e/ou resposta de uma entrada HTTP. | **`entry_id`**, **`part`**, `search_pattern`, `result_detail` |
| `ogma_validate_httpql` | Valida uma expressão HTTPQL. | **`query`** |
| `ogma_analyze_http_entry_security` | Revisa uma entrada HTTP quanto a comportamentos e evidências relevantes para a segurança. | **`entry_id`** |
| `ogma_search_by_vulnerability_pattern` | Pesquisa padrões voltados a vulnerabilidades no tráfego capturado. | **`pattern_type`**, `limit` |

### WebSocket e SSE {#websocket-and-sse}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_search_ws_history` | Pesquisa o histórico de conexões WebSocket com StreamQL. | `q`, `limit`, `offset` |
| `ogma_get_ws_messages` | Obtém mensagens armazenadas de uma conexão WebSocket. | **`connection_id`**, `limit`, `offset` |
| `ogma_get_ws_message` | Lê uma mensagem completa sem o truncamento das prévias de listas; texto é UTF-8, e conteúdos binários e de controle são base64. | **`message_id`** |
| `ogma_validate_streamql` | Valida uma expressão StreamQL. | **`query`** |
| `ogma_get_ws_messages_live` | Obtém mensagens WebSocket em tempo real capturadas pela instrumentação do navegador. | `host`, `limit` |
| `ogma_create_ws_replay_session` | Cria uma sessão de Reenvio WebSocket. | **`ws_connection_id`** |
| `ogma_connect_ws_replay` | Conecta uma sessão de Reenvio WebSocket. | **`ws_session_id`** |
| `ogma_send_ws_replay_message` | Envia uma mensagem por uma sessão de Reenvio WebSocket. | **`ws_session_id`**, **`payload`**, `message_type` |
| `ogma_list_ws_replay_sessions` | Lista sessões de Reenvio WebSocket. | `result_detail` |
| `ogma_get_ws_replay_messages` | Lê a transcrição de uma sessão de Reenvio WebSocket, não o histórico capturado. Omita `cursor` para começar; passe o `next_cursor` retornado e continue enquanto `has_more` indicar mais resultados. | **`ws_session_id`**, `cursor`, `limit`, `result_detail` |
| `ogma_get_ws_replay_message` | Lê uma mensagem de Reenvio WebSocket completa, sem truncamento do payload; `payload_base64` indica bytes codificados em base64. | **`message_id`**, `result_detail` |
| `ogma_disconnect_ws_replay` | Desconecta uma sessão de Reenvio WebSocket, mantendo sua sessão e transcrição; também cancela uma conexão pendente. | **`ws_session_id`** |
| `ogma_browser_get_ws_frames` | Lê quadros WebSocket capturados pelo navegador integrado. | `limit`, `connection_url`, `direction` |
| `ogma_browser_start_ws_capture` | Inicia a captura de quadros WebSocket no navegador. | Nenhuma. |
| `ogma_browser_send_ws_message` | Envia uma mensagem WebSocket a partir do contexto do navegador. | **`payload`**, `connection_url` |

### Achados e evidências {#findings-and-evidence}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_search_findings` | Pesquisa achados por severidade, relator, texto, limite e deslocamento. | `severity`, `reporter`, `q`, `limit`, `offset` |
| `ogma_get_finding` | Obtém um achado por ID. | **`finding_id`** |
| `ogma_preview_finding_from_evidence` | Mostra uma prévia de um rascunho de achado a partir de uma entrada HTTP sem criá-lo. | **`entry_id`**, `reporter` |
| `ogma_create_finding` | Cria um achado com metadados, tags, confiança, correção e links opcionais de evidências. | **`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` | Atualiza um achado existente. | **`finding_id`**, **`title`**, `severity`, `status`, `description`, `reporter`, `tags`, `dedupe_key`, `confidence`, `remediation` |
| `ogma_add_finding_tag` | Adiciona tags a um achado sem substituir as existentes. | **`finding_id`**, **`tags`** |
| `ogma_link_finding_evidence` | Adiciona a um achado evidências de HTTP, Reenvio, Automação, WebSocket capturado ou mensagem de Reenvio WS. Links de apoio não substituem sua evidência principal. | **`finding_id`**, `entry_id`, `replay_attempt_id`, `automate_result_id`, `ws_message_id`, `ws_replay_message_id` |
| `ogma_delete_finding` | Exclui um achado. | **`finding_id`** |
| `ogma_create_finding_from_entry` | Cria um achado a partir de uma entrada HTTP capturada. Incorpora os cabeçalhos e corpos de requisição e resposta como evidência HTTP em Markdown, com o corpo de resposta truncado em 3000 caracteres. Adiciona uma pontuação CVSS a partir de um detalhamento fornecido, CWE, código PoC e referências. | **`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` | Resume as evidências vinculadas a um achado. | **`finding_id`** |
| `ogma_record_finding_verification` | Registra um veredicto independente de novo teste para um achado: `verified`, `refuted` ou `inconclusive`. O veredicto mais recente prevalece, então uma refutação posterior substitui uma confirmação anterior, e a ferramenta informa a linha armazenada. | **`finding_id`**, **`state`**, **`method`**, **`reason`**, `evidence_entry_id`, `control_entry_id`, `canary_id` |
| `ogma_check_canary` | Cria um token usando `label` e `purpose`, ou verifica novamente um token existente usando `canary_id` sem criar outro. Pesquisa entradas correspondentes no tráfego capturado. Uma correspondência no corpo da resposta é evidência de leitura posterior; uma correspondência no corpo da requisição só mostra que o token foi enviado. | **`canary_id`** ou **`label`** e **`purpose`**, `finding_id`, `hosted_path`, `limit` |
| `ogma_export_findings_report` | Cria uma exportação de relatório de achados. | **`format`**, `title`, `summary`, `scope`, `tester`, `include_evidence` |

### Exportações {#exports}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_preview_export_plan` | Mostra uma prévia do conteúdo e formato da exportação sem criar um trabalho. | **`kind`**, **`format`**, `limit`, `q`, `severity`, `reporter` |
| `ogma_create_export_job` | Cria um trabalho de exportação para histórico, resultados de pesquisa, achados ou resultados de Automação. | **`name`**, **`kind`**, **`format`**, `limit`, `offset`, `scope`, `q`, `severity`, `reporter`, `run_id` |
| `ogma_get_export_job` | Obtém um trabalho de exportação por ID. | **`export_id`** |
| `ogma_list_export_jobs` | Lista trabalhos de exportação. | `limit`, `offset` |
| `ogma_get_export_download_info` | Obtém metadados de download de uma exportação concluída. | **`export_id`** |

### Reenvio e envio de requisições {#replay-and-request-sending}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_preview_replay_send` | Mostra uma prévia de um envio de Reenvio e retorna um token de confirmação. | `http_entry_id`, `replay_session_id`, `method`, `path`, `query`, `body`, `result_detail` |
| `ogma_send_replay_request` | Envia uma requisição de Reenvio com o token de confirmação. | **`confirmation_token`**, **`request_hash`**, `result_detail` |
| `ogma_create_replay_session_from_history` | Cria uma sessão de Reenvio a partir de uma entrada HTTP capturada. | **`entry_id`**, `name`, `result_detail` |
| `ogma_create_replay_session_raw` | Cria uma sessão de Reenvio a partir de uma definição de requisição bruta. | `name`, **`host`**, **`port`**, `tls`, `method`, `path`, `headers`, `body` |
| `ogma_get_replay_session` | Obtém metadados de uma sessão de Reenvio e uma lista paginada de tentativas. | **`session_id`**, `attempts_limit`, `attempts_offset`, `result_detail` |
| `ogma_get_replay_attempt` | Obtém uma tentativa de Reenvio. | **`session_id`**, **`attempt_id`**, `result_detail` |
| `ogma_list_replay_sessions` | Lista sessões de Reenvio. | `limit`, `offset`, `result_detail` |
| `ogma_create_replay_sequence` | Cria uma sequência de Reenvio de várias etapas a partir de sessões de Reenvio existentes, na ordem de execução das etapas; `collection_id` sobrepõe as variáveis dessa coleção durante uma execução. | **`name`**, **`session_ids`**, `collection_id` |
| `ogma_run_replay_sequence` | Executa uma sequência de Reenvio armazenada, enviando tráfego real de saída. `plan` lista os índices das etapas na ordem de execução; as entradas podem repetir, omitir ou reordenar etapas, e omitir `plan` executa cada etapa armazenada uma vez, em ordem. Um `plan` vazio é recusado. | **`sequence_id`**, `plan` |
| `ogma_repeat_request` | Repete uma requisição existente com alterações opcionais. | **`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` | Reenvia uma requisição HTTP capturada com substituições por campo e retorna uma resposta mais um resumo de diferenças. | **`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` | Envia uma requisição HTTP direta pela interface de ferramentas MCP. Com `raw_request_base64`, `max_responses` lê vários quadros de resposta na mesma conexão em vez de parar no primeiro, e `followup_raw_request_base64` escreve uma requisição nessa conexão depois de ler a primeira resposta; uma resposta que os bytes enviados não solicitaram é como se confirma uma dessincronização de requisições, em vez de supô-la. Ambas as entradas se aplicam apenas ao modo bruto. | **`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` | Envia um lote de requisições. | **`base_session_id`**, **`payloads`**, **`placeholder`**, `max_requests` |
| `ogma_fetch_url` | Busca uma URL e retorna o status da resposta, os cabeçalhos e uma prévia do corpo. | **`url`**, `method`, `headers`, `body_b64`, `max_bytes` |
| `ogma_follow_redirect` | Busca uma URL, segue a cadeia de redirecionamentos e informa cada salto. | **`url`**, `method`, `headers`, `body_b64`, `max_hops`, `timeout_secs` |
| `ogma_fuzz_parameter` | Substitui um marcador `{{FUZZ}}` por valores de uma lista de palavras e agrupa respostas por status e tamanho. | **`url`**, `method`, `headers`, `body_template`, **`wordlist`**, `timeout_secs`, `stop_on_match` |
| `ogma_multipart_upload` | Envia requisições multipart form-data com campos de texto e arquivo para testes de upload. | **`url`**, **`fields`**, `headers`, `timeout_secs` |
| `ogma_test_login` | Testa um endpoint de login com pares de credenciais fornecidos ou padrão e informa as evidências. | **`url`**, `credentials`, `username_field`, `password_field`, `submit_selector`, `success_pattern`, `failure_pattern`, `max_attempts` |

### Fluxos de trabalho e Automação {#workflows-and-automate}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_search_workflows` | Lista e filtra fluxos de trabalho. | `workflow_type`, `enabled`, `limit`, `offset` |
| `ogma_get_workflow` | Obtém um fluxo de trabalho por ID. | **`workflow_id`** |
| `ogma_get_workflow_run` | Obtém um registro de execução de fluxo de trabalho. | **`run_id`** |
| `ogma_validate_workflow_import` | Valida a compatibilidade de importação de um pacote de fluxos de trabalho. | **`bundle_json`** |
| `ogma_get_workflow_safety` | Obtém a classificação de segurança e permissões de um fluxo de trabalho. | **`workflow_id`** |
| `ogma_preview_workflow_run` | Mostra uma prévia de uma execução de fluxo de trabalho antes de executá-lo. | **`workflow_id`**, `input`, `trigger_entry_id` |
| `ogma_run_workflow` | Executa um fluxo de trabalho. | **`confirmation_token`**, **`definition_hash`**, `input_hash`, `input` |
| `ogma_cancel_workflow_run` | Cancela uma execução de fluxo de trabalho. | **`run_id`** |
| `ogma_list_automate_sessions` | Lista sessões de Automação. | `limit`, `offset` |
| `ogma_get_automate_session` | Obtém uma sessão de Automação. | **`session_id`** |
| `ogma_create_automate_session` | Cria uma sessão de Automação com um ponto de injeção. `inject_into` seleciona esse ponto como `query:<name>`, `header:<name>` ou `body`; o padrão é o primeiro parâmetro de consulta, depois o corpo. | **`entry_id`**, `name`, **`payloads`**, `inject_into`, `placeholder_start`, `placeholder_end`, `worker_count`, `delay_ms` |
| `ogma_run_automate_session` | Executa uma sessão de Automação. | **`session_id`** |
| `ogma_list_automate_runs` | Lista execuções de Automação. | **`session_id`**, `limit`, `offset` |
| `ogma_get_automate_run` | Obtém uma execução de Automação. | **`run_id`** |
| `ogma_cancel_automate_run` | Cancela uma execução de Automação. | **`run_id`** |
| `ogma_list_automate_results` | Lista resultados de Automação. | **`run_id`**, `limit`, `offset`, `min_status`, `max_status` |
| `ogma_get_automate_result` | Obtém um resultado de Automação. | **`run_id`**, **`seq`** |
| `ogma_load_skill` | Carrega orientações de habilidades MCP integradas no contexto do assistente. | **`skills`** |

### Varredura {#scanner}

Iniciar varreduras passivas ou ativas exige permissão de escrita de achados porque as varreduras podem criar achados. Listar regras do scanner e categorias de verificações ativas não exige essa permissão.

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_run_passive_scan` | Executa verificações do scanner passivo para uma entrada HTTP. | **`entry_id`** |
| `ogma_run_passive_scan_all` | Executa verificações do scanner passivo no histórico capturado. | Nenhuma. |
| `ogma_list_scanner_rules` | Lista regras de detecção do scanner. | Nenhuma. |
| `ogma_list_active_checks` | Lista categorias de verificações do scanner ativo com seus IDs e descrições, e informa quantas delas criam achados. Categorias não implementadas são listadas, mas nunca produzem um achado. | Nenhuma. |
| `ogma_scan_active` | Executa o scanner ativo, que envia payloads de teste e cria achados apenas para classes que confirma a partir da resposta. Passe `entry_id` para verificar uma entrada ou omita-o para percorrer o histórico recente. É uma operação longa, por isso é exposta como tarefa; a rota síncrona consulta o trabalho até um estado final e informa `job_id`, contadores de progresso e `findings_created`. Exige permissão de escrita de achados. | `entry_id`, `checks`, `concurrency`, `delay_ms`, `scan_headers` |

### Interceptação {#intercept}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_get_intercept_status` | Obtém o estado atual de interceptação. | Nenhuma. |
| `ogma_set_intercept_enabled` | Habilita ou desabilita a interceptação. | `request_enabled`, `response_enabled`, `websocket_enabled` |
| `ogma_list_intercept_queue` | Lista itens interceptados na fila. | Nenhuma. |
| `ogma_get_intercept_item` | Obtém um item de interceptação da fila. | **`id`** |
| `ogma_forward_intercept_item` | Encaminha um item interceptado, opcionalmente modificado. | **`id`**, `method`, `path`, `headers`, `body`, `status_override` |
| `ogma_drop_intercept_item` | Descarta um item interceptado. | **`id`** |
| `ogma_intercept_and_modify` | Aguarda uma requisição ou resposta interceptada em tempo real, aplica patches JSON, substituições por expressões regulares ou substituição completa do corpo e depois encaminha. | **`direction`**, `host_pattern`, `path_pattern`, `wait_secs`, `json_patches`, `regex_replacements`, `body_b64`, `status_override`, `forward_unmatched` |

### Proxy, escopo e rede {#proxy-scope-and-network}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_list_proxy_listeners` | Lista listeners do proxy. | Nenhuma. |
| `ogma_start_proxy_listener` | Inicia um listener do proxy. | **`listener_id`** |
| `ogma_stop_proxy_listener` | Para um listener do proxy. | **`listener_id`** |
| `ogma_list_scope_presets` | Lista predefinições de escopo. | Nenhuma. |
| `ogma_create_scope_preset` | Armazena uma predefinição de escopo sem ativá-la. Exige permissão de envio. Cada regra exige `pattern` e `include`; `rule_type` opcional seleciona correspondência por host, CIDR, caminho ou expressão regular. Regras de caminho usam `pattern` para o host e `path_pattern` para o caminho. Ative a predefinição retornada separadamente com `ogma_set_active_scope`. | **`name`**, **`rules`**, `httpql_expression` |
| `ogma_get_active_scope` | Obtém o escopo ativo. | Nenhuma. |
| `ogma_set_active_scope` | Define o escopo ativo. | `preset_id` |
| `ogma_local_ips` | Lista endereços IP locais úteis para listeners e callbacks. | Nenhuma. |
| `ogma_get_tls_info` | Obtém informações TLS de um destino ou conexão capturada. | **`host`**, `port` |

### Mapa do site, endpoints e OAST {#sitemap-endpoints-and-oast}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_get_sitemap` | Obtém o mapa do site capturado. | `host`, `show_api_only` |
| `ogma_get_sitemap_parameters` | Obtém parâmetros descobertos para um caminho do mapa do site. | **`host`**, **`port`**, **`path`** |
| `ogma_list_extracted_endpoints` | Lista endpoints extraídos do tráfego e do conteúdo do frontend. | `limit`, `offset` |
| `ogma_discovery_start` | Inicia um trabalho de descoberta de conteúdo em segundo plano contra um host e porta no escopo; retorna um ID de trabalho. | **`host`**, **`port`**, `tls`, `base_path`, `config` |
| `ogma_discovery_list` | Lista trabalhos de descoberta e seu progresso no projeto ativo. | Nenhuma. |
| `ogma_discovery_get` | Obtém o estado e os resultados descobertos de um trabalho de descoberta. | **`job_id`** |
| `ogma_discovery_cancel` | Solicita o cancelamento de um trabalho de descoberta em execução. | **`job_id`** |
| `ogma_import_openapi_spec` | Importa uma especificação OpenAPI para preencher endpoints e estruturas iniciais de requisições. | **`spec_content`**, `base_url`, `collection_name` |
| `ogma_get_oast_config` | Obtém a configuração de listener do OAST. | Nenhuma. |
| `ogma_get_oast_reachability` | Informa se o host de callback OAST configurado pode ser acessado de um destino, com os motivos quando não pode e as etapas que resolveriam isso. Verifique antes de confiar em um payload de teste cego: um callback inacessível produz um falso negativo interpretado como ausência de vulnerabilidade. | Nenhuma. |
| `ogma_list_oast_interactions` | Lista interações OAST. Todos os filtros são aplicados pelo backend antes de recortar a página, então o total conta todas as correspondências em vez do tamanho da página, e restringir a uma etiqueta de token ou endereço de origem nunca oculta um callback correspondente mais adiante na lista. `token_label` é o ponto de injeção que transportou o token: um nome de parâmetro de consulta, um nome de cabeçalho ou `body`. Etiquetas ficam em memória com seus tokens, então uma etiqueta cujo token tenha expirado não corresponde a nada, em vez de corresponder a linhas antigas. | `limit`, `offset`, `token_id`, `token_label`, `protocol`, `source_ip`, `since` |

### Anotações do histórico {#history-annotation}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_set_entry_color` | Define a etiqueta de cor de uma entrada do histórico. | **`entry_id`**, **`color`** |
| `ogma_add_entry_tag` | Adiciona uma tag a uma entrada do histórico. | **`entry_id`**, **`tag`** |
| `ogma_remove_entry_tag` | Remove uma tag de uma entrada do histórico. | **`entry_id`**, **`tag`** |

### Controle do navegador {#browser-control}

Para escolher entre capturas semânticas, seletores e capturas de tela, consulte o [guia do navegador](/pt/guide/mcp-browser.md). Não presuma que toda ferramenta do navegador aceita `tab_id` ou `element_ref`; use apenas as entradas listadas para aquela ferramenta.

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_browser_launch` | Inicia o navegador do Ogma. | `proxy_port` |
| `ogma_browser_navigate` | Navega até uma URL no navegador. | **`url`**, `tab_id`, `wait_for_load`, `timeout_ms`, `result_detail` |
| `ogma_browser_get_dom` | Navega e retorna o DOM renderizado e resultados opcionais de seletores depois que o JavaScript foi executado. | **`url`**, `wait_secs`, `selectors`, `js_eval`, `include_full_html` |
| `ogma_browser_screenshot` | Captura o estado da página do navegador. | `tab_id`, `result_detail` |
| `ogma_browser_execute_js` | Executa JavaScript no navegador. | **`script`**, `tab_id` |
| `ogma_browser_get_source` | Obtém o código-fonte DOM da página atual. | `tab_id`, `format`, `max_chars` |
| `ogma_browser_get_cookies` | Obtém cookies do navegador. | `tab_id` |
| `ogma_browser_set_cookie` | Define um cookie do navegador. | **`name`**, **`value`**, `domain`, `path`, `http_only`, `secure` |
| `ogma_browser_new_tab` | Abre uma nova aba do navegador. | `url` |
| `ogma_browser_close_tab` | Fecha uma aba do navegador. | `tab_id` |
| `ogma_browser_get_tabs` | Lista abas do navegador. | `result_detail` |
| `ogma_browser_click` | Clica em um `element_ref` de uma captura semântica ou em coordenadas `x` e `y` explícitas. | `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` | Digita texto no navegador. | **`text`**, `tab_id`, `snapshot_id` |
| `ogma_browser_fill_input` | Define um campo usando exatamente um `selector` CSS ou `element_ref` de captura semântica; um valor vazio limpa o campo. Não envia o formulário. | **`selector`**, `value`, `tab_id`, **`element_ref`**, `snapshot_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_fill_form` | Substitui texto em vários campos, áreas de texto ou elementos contenteditable em uma chamada, na ordem fornecida; cada campo usa exatamente um `element_ref` ou `selector`, mais um `value`. Para na primeira falha e não envia o formulário. | **`fields`**, `snapshot_id`, `tab_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_click_selector` | Clica em um elemento pelo seletor. | **`selector`**, `tab_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_submit_form` | Envia um formulário. | `selector`, `tab_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_get_page_links` | Extrai links da página atual. | `tab_id` |
| `ogma_browser_get_page_forms` | Extrai formulários da página atual. Defina `include_templates` como `true` (padrão `false`) para adicionar a URL absoluta de ação, o método, o tipo de conteúdo efetivo, os controles que seriam incluídos no envio com seus valores atuais, os controles de envio e os `token_candidates` semelhantes a CSRF de cada formulário. Formulários multipart apontam para `ogma_multipart_upload` em vez de um corpo sintetizado. Exige a permissão `send_requests`. | `tab_id`, `include_templates` |
| `ogma_browser_form_to_replay` | Cria uma sessão de Reenvio a partir de um formulário na página atual, lendo os valores atuais dos campos e os cookies ativos do navegador naquele momento, com cabeçalhos Origin e Referer derivados da página. Não envia a requisição. | **`form_selector`**, `tab_id`, `name` |
| `ogma_browser_scroll` | Rola a página atual. | `selector`, `x`, `y`, `tab_id` |
| `ogma_browser_wait_for_selector` | Aguarda um seletor de elemento. | **`selector`**, `timeout_ms`, `tab_id`, `snapshot_id` |
| `ogma_browser_get_network_log` | Obtém eventos de rede do navegador. | `host`, `since_ms`, `limit` |
| `ogma_browser_go_back` | Volta no histórico do navegador. | `tab_id`, `snapshot_id` |
| `ogma_browser_go_forward` | Avança no histórico do navegador. | `tab_id`, `snapshot_id` |
| `ogma_browser_reload` | Recarrega a página. | `tab_id`, `snapshot_id` |
| `ogma_browser_find_text` | Localiza texto na página atual. | **`text`**, `tab_id`, `snapshot_id` |
| `ogma_browser_clear_data` | Limpa dados do navegador. | `types` |
| `ogma_crawl_site` | Rastreia um destino pelo navegador integrado dentro do escopo ativo e retorna dados de cobertura. | **`start_url`**, `max_pages`, `max_depth`, `wait_ms`, `tab_id` |

### Elementos e esperas do navegador {#browser-elements-and-waits}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_browser_snapshot` | Lê uma árvore semântica compacta da página com referências e estados de elementos; `result_detail: "full"` retorna o envelope estruturado com elementos em `raw.elements` em vez disso. Pode solicitar diferenças em relação a uma captura anterior. | `tab_id`, `previous_snapshot_id`, `changes_only`, `focus_ref`, `text`, `max_elements`, `max_text_length`, `include_hidden`, `max_depth`, `result_detail` |
| `ogma_browser_hover` | Posiciona o ponteiro sobre um elemento referenciado e informa menus ou dicas que ficaram visíveis. | **`element_ref`**, `snapshot_id`, `offset_x`, `offset_y`, `modifiers`, `timeout_ms`, `tab_id` |
| `ogma_browser_select_option` | Seleciona opções de listas suspensas por valor, rótulo ou índice e informa os valores selecionados. | **`element_ref`**, `snapshot_id`, **`values`**, `match_mode`, `allow_first_match`, `timeout_ms`, `tab_id` |
| `ogma_browser_check` | Define explicitamente o estado de uma caixa de seleção ou botão de opção em vez de alterná-lo às cegas. | **`element_ref`**, `snapshot_id`, `checked`, `timeout_ms`, `tab_id` |
| `ogma_browser_press_key` | Envia uma tecla ou combinação de teclas para a página com foco ou para um elemento referenciado. | **`key`**, `element_ref`, `snapshot_id`, `modifiers`, `repeat`, `delay_ms`, `tab_id` |
| `ogma_browser_focus` | Dá foco a um elemento referenciado e informa suas capacidades de entrada. | **`element_ref`**, `snapshot_id`, `tab_id` |
| `ogma_browser_blur` | Remove o foco do elemento que está com foco atualmente. | `tab_id`, `snapshot_id` |
| `ogma_browser_drag_and_drop` | Arrasta um elemento referenciado para outro. | **`source_ref`**, **`target_ref`**, `snapshot_id`, `steps`, `tab_id` |
| `ogma_browser_scroll_to` | Rola até um elemento, posição da página ou dentro de um contêiner de rolagem referenciado. | `target`, `element_ref`, `snapshot_id`, `container_ref`, `direction`, `amount`, `behavior`, `timeout_ms`, `tab_id` |
| `ogma_browser_wait_for` | Aguarda uma condição de elemento, texto, URL, navegação ou diálogo, ou a estabilidade da página; suporta uma pausa explícita quando necessário. | **`condition`**, `target`, `timeout_ms`, `stability_ms`, `tab_id`, `snapshot_id`, `result_detail` |
| `ogma_browser_handle_dialog` | Aceita ou dispensa um diálogo JavaScript, com texto de resposta opcional e verificações do diálogo esperado. | **`action`**, `prompt_text`, `expected_type`, `expected_message`, `tab_id`, `snapshot_id` |
| `ogma_browser_dialog_status` | Informa qualquer diálogo JavaScript pendente sem dispensá-lo. | Nenhuma. |

### Arquivos, pop-ups e downloads do navegador {#browser-files-popups-and-downloads}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_list_hosted_files` | Lista arquivos hospedados do projeto ativo e seus IDs para uploads e inspeção de artefatos. | `limit`, `offset` |
| `ogma_artifact_read_range` | Lê um intervalo limitado de bytes de um arquivo hospedado em vez de retornar o arquivo inteiro. | **`artifact_id`**, `offset`, `length` |
| `ogma_artifact_search` | Pesquisa texto literal em um intervalo limitado de um arquivo hospedado UTF-8 e retorna deslocamentos de bytes correspondentes. | **`artifact_id`**, **`query`**, `offset`, `max_bytes`, `max_matches` |
| `ogma_browser_file_upload` | Define um campo de arquivo a partir de IDs de arquivos hospedados existentes no Ogma, não de caminhos arbitrários do sistema de arquivos do cliente. | **`element_ref`**, `snapshot_id`, **`artifact_ids`**, `tab_id` |
| `ogma_browser_wait_for_popup` | Prepara a detecção de pop-ups antes de uma ação, aguarda um pop-up ou verifica o estado da detecção. | **`action`**, `timeout_ms`, `switch_to_new_tab` |
| `ogma_browser_download_wait` | Detecta um download do navegador em andamento ou concluído. Inspecione seu ID e estado; a detecção não implica conclusão nem que seja o download mais recente. | `timeout_ms` |
| `ogma_browser_download_get` | Inspeciona um download e salva o conteúdo concluído como artefato quando disponível. | **`download_id`** |
| `ogma_browser_download_status` | Lista downloads do navegador e seu progresso e estado atuais. | Nenhuma. |

### Identidades, armazenamento e permissões do navegador {#browser-identities-storage-and-permissions}

As ferramentas de permissão do navegador abaixo controlam permissões de sites, como câmera ou geolocalização. Elas não alteram as permissões de ferramentas do servidor MCP.

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_browser_context_create` | Cria uma identidade isolada de navegador e uma aba inicial; retorna `context_id` e `tab_id`. | `label`, `auth_profile_id`, `initial_url`, `retain_on_close` |
| `ogma_browser_context_clone` | Cria um contexto limpo ou copia cookies do contexto de origem com `clone_mode: authenticated`; não é uma clonagem completa do armazenamento. | **`context_id`**, `clone_mode`, `label` |
| `ogma_browser_context_close` | Fecha um contexto e suas abas, limpando o armazenamento a menos que a retenção tenha sido solicitada na criação. | **`context_id`** |
| `ogma_browser_context_list` | Lista contextos do navegador e seu estado. | Nenhuma. |
| `ogma_browser_auth_state_capture` | Captura cookies e armazenamento web como um estado de autenticação com nome em memória; retorna metadados com dados sensíveis ocultos. | **`name`**, `tab_id`, `context_id`, `role`, `url` |
| `ogma_browser_auth_state_apply` | Restaura um estado de autenticação capturado; metadados de expiração não provam que o servidor aceita a sessão. | **`auth_state_id`**, `tab_id`, `context_id`, `url` |
| `ogma_browser_auth_state_list` | Lista estados de autenticação capturados sem seus valores secretos completos. | Nenhuma. |
| `ogma_browser_auth_state_delete` | Exclui um estado de autenticação capturado. | **`auth_state_id`** |
| `ogma_browser_storage_list` | Lista cookies e entradas de armazenamento web usando prévias abreviadas dos valores. | `origin`, `storage_type` |
| `ogma_browser_storage_get` | Inspeciona um cookie ou chave de armazenamento com uma prévia abreviada do valor. | **`storage_type`**, **`key`**, `origin` |
| `ogma_browser_storage_set` | Escreve um valor de cookie ou armazenamento; aceita uma referência `env:VARIABLE_NAME` do Ogma. | **`storage_type`**, **`key`**, **`value`**, `origin`, `domain`, `path`, `http_only`, `secure`, `expires` |
| `ogma_browser_storage_delete` | Exclui um cookie ou chave de armazenamento web. | **`storage_type`**, **`key`**, `origin` |
| `ogma_browser_permissions_set` | Concede, nega ou redefine permissões de site especificadas para uma origem. | **`origin`**, **`permissions`**, `setting`, `context_id` |
| `ogma_browser_permissions_reset` | Limpa substituições de permissões do navegador. | `context_id` |
| `ogma_browser_permissions_get` | Consulta estados de permissões de site para uma origem. | **`origin`**, `permissions` |

### Diagnósticos, evidências e recuperação do navegador {#browser-diagnostics-evidence-and-recovery}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_browser_network_delta` | Obtém entradas de rede limitadas após um cursor, mantendo URLs completas, tempos, erros e IDs do Histórico HTTP quando disponíveis. | `since_entry_id`, `resource_types`, `status_filter`, `failed_only`, `max_entries` |
| `ogma_browser_console_delta` | Obtém novas entradas de console, incluindo URL de origem, linha e coluna quando fornecidas pelo navegador. | `since_entry_id`, `levels`, `max_entries` |
| `ogma_browser_action_correlation` | Obtém tráfego e eventos associados à janela de tempo de uma ação ou lista ações recentes. A coincidência temporal sozinha não prova causalidade. | `browser_action_id`, `limit` |
| `ogma_browser_snapshot_save` | Arquiva a captura semântica atual para comparação posterior; o arquivo mantém até 20 capturas. | `label` |
| `ogma_browser_page_state_compare` | Compara duas capturas semânticas arquivadas e informa diferenças de elementos e estado, opcionalmente ignorando valores voláteis e funções de elementos. | **`snapshot_id_a`**, **`snapshot_id_b`**, `ignore_volatile`, `ignore_roles` |
| `ogma_browser_trace_start` | Inicia um rastreamento leve de ações; `detailed` adiciona referências de console e rede. | `level`, `label`, `context_id` |
| `ogma_browser_trace_stop` | Para um rastreamento e mantém seus eventos em memória. | **`trace_id`** |
| `ogma_browser_trace_export` | Salva um rastreamento parado como um artefato JSON de arquivo hospedado no projeto ativo. | **`trace_id`** |
| `ogma_browser_trace_list` | Lista rastreamentos e seus estados de gravação e exportação. | Nenhuma. |
| `ogma_browser_trace_note` | Acrescenta uma nota a todos os rastreamentos sendo gravados. | **`note`** |
| `ogma_browser_human_takeover_start` | Pausa as ações do agente no navegador para um ponto de controle manual, com tempo limite definido. | `reason`, `context_id`, `tab_id`, `timeout_ms` |
| `ogma_browser_human_takeover_complete` | Devolve o controle após a interação manual e atualiza a captura semântica da página. | **`takeover_id`** |
| `ogma_browser_human_takeover_status` | Verifica se o controle manual está ativo e informa o tempo restante. | Nenhuma. |
| `ogma_browser_health` | Informa a saúde da ponte de depuração e informações recentes de falhas e desconexões. | Nenhuma. |
| `ogma_browser_recover` | Tenta recuperar a ponte, preservando evidências por padrão; pode informar `relaunch_required`. | `preserve_evidence` |

### Testes de autenticação e autorização {#authentication-and-authorization-testing}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_auth_capture_profile` | Captura cookies, armazenamento, tokens de autenticação detectados e candidatos CSRF do navegador integrado. | **`name`**, `role`, `url`, `tab_id`, `wait_ms` |
| `ogma_auth_list_profiles` | Lista perfis de autenticação capturados com valores secretos resumidos. | Nenhuma. |
| `ogma_auth_apply_profile` | Aplica um perfil de autenticação capturado ao navegador integrado para trocar de função ou conta. | **`profile_id`**, `url`, `tab_id`, `wait_ms` |
| `ogma_auth_refresh_csrf` | Atualiza candidatos a tokens CSRF a partir da página atual, cookies, armazenamento, tags meta e campos ocultos. | `profile_id`, `url`, `tab_id`, `wait_ms` |
| `ogma_login_replay_auto` | Detecta automaticamente um formulário de login, envia credenciais no navegador integrado e captura um perfil de autenticação. | **`login_url`**, **`username`**, **`password`**, **`profile_name`**, `role`, `tab_id`, `wait_ms` |
| `ogma_authz_matrix_test` | Reenvia uma requisição capturada com vários perfis de autenticação para comparar resultados de controle de acesso. | **`request_id`**, **`profile_ids`**, `mutations`, `entry_id` |

### Jornadas de login reutilizáveis {#reusable-login-journeys}

Ao contrário dos perfis de autenticação em memória, jornadas de login são persistidas por projeto. As credenciais referenciam IDs de variáveis de ambiente do Ogma. Todas as verificações configuradas devem passar; o envio de um formulário de login sozinho não significa autenticação bem-sucedida.

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_auth_journey_record` | Salva etapas de login, referências de credenciais, verificações e pontos de controle manuais de MFA opcionais. Isso define uma jornada; não grava cliques arbitrários automaticamente. | **`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` | Lista jornadas de login salvas no projeto ativo com segredos de sessão ocultos. | Nenhuma. |
| `ogma_auth_journey_replay` | Executa uma jornada de login salva, verifica a autenticação e salva a sessão atualizada; pausa para MFA manual quando configurado. | **`journey_id`**, `tab_id` |
| `ogma_auth_journey_verify` | Verifica URL, DOM, cookies e uma requisição de verificação opcional contra a sessão atual. | **`journey_id`**, `tab_id` |
| `ogma_auth_journey_ensure` | Verifica a sessão atual, tenta restaurar o estado salvo e repete o login somente se ainda for necessário. | **`journey_id`**, `tab_id` |
| `ogma_auth_journey_resume` | Continua uma jornada após seu ponto de controle manual e verifica a sessão resultante. | **`journey_id`**, **`takeover_id`**, `tab_id` |

### Utilitários e análise {#utilities-and-analysis}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_fetch_sourcemap` | Busca e inspeciona um mapa de código-fonte JavaScript. | **`url`**, `base_url` |
| `ogma_proto_decode` | Decodifica conteúdos protobuf usando esquemas configurados. | **`data_b64`**, `content_type` |
| `ogma_decode_jwt` | Decodifica cabeçalhos e declarações JWT. | **`token`** |
| `ogma_decode_response` | Decodifica, descomprime ou transforma corpos de resposta com operações ordenadas como tratamento de base64, gzip, deflate, brotli, URL, entidades HTML e hexadecimal. | **`input`**, `input_is_b64`, **`operations`**, `max_output_bytes` |
| `ogma_search_js_secrets` | Pesquisa segredos e endpoints expostos em respostas JavaScript. | `host`, `patterns` |
| `ogma_compare_responses` | Compara duas respostas. | **`entry_id_a`**, **`entry_id_b`**, `mode` |
| `ogma_bytes_transform` | Executa transformações de bytes como codificação, decodificação, XOR, cálculo de hashes e extração. | **`operation`**, **`data`**, `key`, `output_encoding`, `offset`, `length`, `min_len` |
| `ogma_wasm_inspect` | Inspeciona um módulo WebAssembly. | **`wasm_b64`**, `data_encoding` |
| `ogma_fingerprint_target` | Identifica tecnologias do destino a partir do tráfego e das respostas capturados. | `host`, `entry_limit` |
| `ogma_sign_request` | Calcula cabeçalhos de assinatura de requisições HMAC-SHA256 para aplicações que usam esquemas de assinatura no cliente. | **`key`**, **`method`**, **`path`**, `params` |
| `ogma_find_in_response` | Busca até 10 URLs e pesquisa uma expressão regular nos corpos de resposta com contexto compacto. | **`urls`**, **`pattern`**, `headers`, `context_chars`, `max_matches_per_url`, `case_insensitive`, `timeout_secs` |
| `ogma_think` | Registra raciocínio estruturado ou texto de planejamento dentro da sessão MCP. | **`thought`** |
| `ogma_explain_capabilities` | Retorna o resumo de capacidades do servidor MCP. | Nenhuma. |

### Auxiliares de sondagem ativa {#active-probe-helpers}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_run_active_probe_workflow` | Executa uma sondagem limitada e específica de uma vulnerabilidade contra uma requisição capturada. Os módulos incluem IDOR/BOLA, CORS, SSRF OAST, reflexão e armazenamento de XSS, temporização e erros SQLi, travessia de caminhos, SSTI, evasão de controles de upload, introspecção e autorização GraphQL, manipulação JWT e verificações de limites de taxa. | **`probe`**, **`request_id`**, `entry_id`, `target_param`, `profile_ids`, `values`, `origins`, `max_cases` |
| `ogma_test_race` | Envia uma requisição de forma concorrente e informa o código de status mais frequente, as respostas que divergiram dele e um veredicto. Use para operações de uso único: várias respostas bem-sucedidas a uma operação que só deve ter sucesso uma vez mostram que ela não é atômica. Passe `request_id` para uma entrada capturada, ou `host` e `port` com o restante da requisição explicitamente. Defina `http2` para enviar todas as requisições como fluxos concorrentes em uma conexão (pacote único), a variante que aproveita janelas estreitas quando o destino usa HTTP/2; o padrão abre uma conexão por requisição. Uma divergência é evidência apenas sobre o tratamento de concorrência, e um lote uniforme não prova atomicidade, então confirme pelo estado que a operação alterou. | `request_id`, `entry_id`, `method`, `host`, `port`, `tls`, `path`, `query`, `params`, `headers`, `body_b64`, `concurrency`, `stagger_ms`, `http2` |
| `ogma_test_smuggling` | Envia sondagens de dessincronização CL.TE e TE.CL por TCP bruto e informa os resultados das sondagens, os candidatos e um veredicto. Cabeçalhos passados em `headers` acompanham apenas a requisição de sondagem; a requisição seguinte que mede a dessincronização sempre é enviada sem eles. A sondagem é heurística e frequentemente erra nas duas direções: um frontend que fecha a conexão após a primeira requisição, ou rejeita a delimitação conflitante com um 400, produz o mesmo resultado de sondagem que um vulnerável, e um resultado negativo não prova segurança. Confirme antes de relatar: reenvie os bytes da sondagem com `ogma_http_request` em modo bruto, passando-os como `raw_request_base64` com `max_responses` definido como 2 para ler a resposta que os bytes não solicitaram; depois envie uma requisição simples com `followup_raw_request_base64` na mesma conexão e compare os dois status. Apenas HTTP/1.x. | **`host`**, **`port`**, `tls`, `path`, `timeout_ms`, `headers` |
| `ogma_test_hpp` | Envia variações de poluição de parâmetros HTTP para os parâmetros indicados e depois informa qual variação alterou o status ou corpo da resposta, além de um veredicto. Use quando um parâmetro é validado em um componente e consumido em outro, então um nome duplicado pode ser resolvido de forma diferente em cada um. Uma resposta alterada mostra que parâmetros duplicados são tratados de modo diferente; não prova por si só que um controle foi contornado. `headers` é enviado em toda requisição, incluindo a de referência, então um cabeçalho Cookie ou Authorization permite sondar um endpoint que precisa de credenciais; sem cabeçalhos, as requisições não levam cookies nem autenticação, então uma variação que não muda nada em um endpoint protegido por login não prova nada. | **`host`**, **`port`**, **`params`**, `tls`, `path`, `base_value`, `test_value`, `timeout_ms`, `headers` |
| `ogma_list_nuclei_templates` | Lista modelos do scanner de modelos incluídos no Ogma, com a severidade e o significado de uma correspondência. Leia antes de `ogma_run_nuclei` para escolher um pelo nome. | Nenhuma. |
| `ogma_run_nuclei` | Executa um modelo contra uma URL de destino e informa todas as correspondências. Não cria achados. Passe `template` para um modelo incluído ou `template_yaml` para seu próprio documento, não ambos. O analisador é um subconjunto do nuclei: verificadores de status, palavras e expressões regulares, `matchers-condition` e extratores de expressões regulares. Tipos de verificadores fora desse subconjunto, incluindo expressões DSL, são ignorados em vez de avaliados, e a ferramenta não executa modelos que uma instalação completa do nuclei aceitaria. Os modelos verificam superfícies de exposição e configuração incorreta que o scanner passivo não consegue ver, como um `.env` ou `.git/config` exposto, um endpoint actuator ou uma página de status do servidor. | **`target`**, `template`, `template_yaml` |
| `ogma_record_test_attempt` | Registra que um endpoint, parâmetro ou vetor foi testado e qual foi o resultado, para uma sessão posterior distinguir um ponto sem resultados de um ponto não testado. Apenas `no_signal` descarta um ponto; `transport_error` significa que a sondagem nunca chegou ao destino, então não prova nada sobre o vetor. | **`host`**, **`port`**, **`path`**, **`vector`**, **`outcome`**, **`reason`**, `parameter`, `payload_label`, `evidence_entry_id` |
| `ogma_list_test_attempts` | Lista tentativas de teste registradas, da mais recente para a mais antiga, e agrupa por host, porta, caminho, parâmetro e vetor, informando a tentativa decisiva de cada ponto, quantas tentativas ele tem e se está esgotado. Um ponto só está esgotado quando seu resultado decisivo é `no_signal`; um `transport_error` posterior não anula esse estado. | `host`, `port`, `path`, `vector`, `limit` |

### Testes diretos de WebSocket {#direct-websocket-testing}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_websocket_connect` | Conecta-se a uma URL `ws://` ou `wss://`, envia mensagens e retorna uma transcrição. | **`url`**, **`messages`**, `headers`, `timeout_secs` |
| `ogma_ws_capture_history` | Salva uma transcrição WebSocket de `ogma_websocket_connect` como histórico estruturado do Ogma para revisão e vinculação de evidências. | **`url`**, **`transcript`**, `label` |

### Localizar e substituir {#match-and-replace}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_list_match_replace_rules` | Lista regras de Localizar e substituir. | Nenhuma. |
| `ogma_create_match_replace_rule` | Cria uma regra de Localizar e substituir; operações de fluxo de trabalho exigem 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` | Habilita ou desabilita uma regra de Localizar e substituir. | **`rule_id`**, **`enabled`** |
| `ogma_delete_match_replace_rule` | Exclui uma regra de Localizar e substituir. | **`rule_id`** |

### Variáveis de ambiente {#environment-variables}

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_list_env_vars` | Lista nomes e metadados de variáveis de ambiente. | Nenhuma. |
| `ogma_set_env_var` | Cria ou atualiza uma variável de ambiente. | **`name`**, **`value`**, `scope`, `is_secret` |
| `ogma_get_env_var_value` | Lê o valor de uma variável de ambiente quando permitido. | **`name`** |

### Projetos, notas, tarefas e sessão {#projects-notes-todos-and-session}

A troca de projeto afeta o projeto ativo no Ogma, não apenas o agente que solicita. Coordene com outros clientes. As ferramentas de notas e tarefas abaixo são um **bloco de trabalho em memória da sessão MCP**, não a página persistente de Notas da aplicação. Preserve o relatório da sessão antes de desconectar ou reiniciar o MCP.

| Ferramenta | O que faz | Entradas |
| --- | --- | --- |
| `ogma_list_projects` | Lista projetos. | Nenhuma. |
| `ogma_switch_project` | Troca o projeto ativo. | `project_id`, `project_name` |
| `ogma_start_pentest_session` | Cria um plano estruturado de avaliação e, por padrão, uma nota ou lista de verificação local da sessão para o destino. Não executa uma varredura completa automaticamente. | **`target_url`**, `objective`, `mode`, `create_scratchpad` |
| `ogma_get_coverage_status` | Resume o progresso da lista de verificação da sessão atual e a cobertura restante; não prova que os testes estejam completos. | Nenhuma. |
| `ogma_recommend_skills` | Sugere orientações de habilidades integradas a partir de tecnologias, caminhos, cabeçalhos observados e outros contextos fornecidos. | `observations`, `paths`, `content_types`, `headers`, `technologies`, `response_snippets`, `notes` |
| `ogma_note_create` | Cria uma nota. | **`title`**, **`content`**, `category` |
| `ogma_note_list` | Lista notas. | `category` |
| `ogma_note_get` | Obtém uma nota. | **`id`** |
| `ogma_note_update` | Atualiza uma nota. | **`id`**, `title`, `content`, `category` |
| `ogma_note_delete` | Exclui uma nota. | **`id`** |
| `ogma_todo_create` | Cria uma tarefa. | **`task`**, `priority` |
| `ogma_todo_list` | Lista tarefas. | `status`, `priority` |
| `ogma_todo_update` | Atualiza uma tarefa. | **`id`**, `task`, `priority`, `status` |
| `ogma_todo_mark_done` | Marca uma tarefa como concluída. | **`id`** |
| `ogma_todo_delete` | Exclui uma tarefa. | **`id`** |
| `ogma_finish_session` | Finaliza a sessão MCP com resumo, metodologia e recomendações. | **`summary`**, **`methodology`**, **`recommendations`** |
| `ogma_get_session_report` | Obtém o relatório da sessão MCP atual. | Nenhuma. |

## Relação com a IA do espaço de trabalho {#relationship-to-workspace-ai}

O servidor MCP é um servidor de protocolo usado por ferramentas externas. A IA do espaço de trabalho integrada à aplicação é um recurso de Vue e navegador que chama diretamente os provedores de IA configurados e expõe sua própria lista de ferramentas do frontend. Consulte [IA do espaço de trabalho](/pt/guide/workspace-ai.md).