Ir para o conteúdo

Configuração do servidor MCP do Ogma ​

O servidor MCP do Ogma (ogma-mcp) permite que assistentes de IA compatíveis inspecionem o contexto do projeto e, quando habilitado, controlem o navegador integrado, enviem requisições, executem fluxos de trabalho e coletem evidências. Suas ferramentas de notas e tarefas são um bloco de trabalho em memória da sessão MCP, separado da página persistente de Notas da aplicação.

O MCP é destinado a ferramentas externas como Codex, Claude Code, Cursor e outros clientes de Model Context Protocol. Não é o mesmo recurso que o assistente de IA do espaço de trabalho integrado à aplicação.

Configurações do MCP no modo escuroConfigurações do MCP no modo claro

Para a lista completa de recursos e ferramentas, consulte Recursos e ferramentas MCP.

Início rápido: aplicação desktop ​

  1. Inicie o Ogma e abra o projeto que o agente deve inspecionar.
  2. Abra Configurações > MCP, escolha as permissões necessárias e salve. A interação com o navegador exige Reenvio de requisições.
  3. Clique em Iniciar e copie o endpoint exibido, normalmente http://127.0.0.1:3000/mcp.
  4. Adicione-o ao seu cliente MCP como um servidor Streamable HTTP.
  5. Peça ao agente para chamar ogma_explain_capabilities e ler ogma://project/current para verificar a conexão e o projeto ativo.

Essa opção não exige compilar um binário separado. Para navegação de páginas, formulários, jornadas de login e solução de problemas, consulte Automação do navegador com MCP.

Endereços de conexão ​

InterfaceEndereço padrãoFinalidade
Transporte MCPhttp://127.0.0.1:3000/mcpClientes MCP nativos se conectam aqui.
API REST do backendhttp://127.0.0.1:8181--api-url do MCP independente e as rotas de gerenciamento e da ponte descritas abaixo.
Listener do proxy127.0.0.1:8080Captura o tráfego do navegador; não é um endpoint MCP.

Instâncias desktop podem atribuir dinamicamente a porta da API do backend. Use o endereço real da instância em execução para integrações stdio/REST e o endpoint exibido em Configurações para MCP nativo. Um serviço de chat na nuvem não consegue acessar seu endereço de loopback sem um cliente ou conector local.

O endpoint HTTP mantém estado: deixe o cliente gerenciar a inicialização e os cabeçalhos de sessão. Não existe um endpoint legado /sse separado. Clientes personalizados devem seguir a especificação de transporte do MCP.

Quando usar MCP ​

Use MCP quando um assistente externo precisar ajudar você a:

  • Resumir o tráfego capturado.
  • Fazer a triagem de achados.
  • Redigir texto de relatórios baseado em evidências.
  • Revisar fluxos de trabalho e sessões de Reenvio.
  • Preparar ações dentro do escopo que você aprove explicitamente.

Use a IA do espaço de trabalho quando preferir a janela do assistente integrada ao Ogma.

Requisitos do servidor independente ​

Use stdio quando seu cliente precisar iniciar um executável local em vez de se conectar ao endpoint HTTP integrado.

  • Backend do Ogma em execução em seu endereço real de API (padrão da CLI: http://127.0.0.1:8181)
  • O binário ogma-mcp (compilado a partir do código-fonte)

Compilação ​

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

A saída padrão é target/release/ogma-mcp (ogma-mcp.exe no Windows), a menos que você personalize o diretório de destino do Cargo.

Execução ​

bash
# Connect to Ogma running on the default port
./ogma-mcp

# Connect to a custom address
./ogma-mcp --api-url http://127.0.0.1:9090

# Use a larger body preview
./ogma-mcp --body-preview-bytes 2048

O servidor encerra se não conseguir acessar a API do Ogma. Configure o cliente MCP para iniciar esse comando; stdout transporta as mensagens MCP e stderr contém os diagnósticos. As permissões do stdio vêm de suas próprias flags, não das configurações do MCP integrado.

Descoberta de ferramentas ​

O servidor atual sempre anuncia seu catálogo completo de ferramentas. Não existe um seletor de perfil de ferramentas em Configurações. Os valores antigos de --tool-profile, --mcp-tool-profile e OGMA_MCP_TOOL_PROFILE são aceitos por compatibilidade, mas não ocultam ferramentas nem concedem permissões.

Para um catálogo grande, comece com ogma_explain_capabilities e ogma_find_tools em vez de adivinhar as entradas. Pesquise palavras-chave da tarefa para selecionar ferramentas e, depois, consulte o nome exato de uma ferramenta para inspecionar seu contrato. Os despachantes de navegador e pesquisa oferecem pontos de entrada convenientes; as ferramentas específicas continuam disponíveis diretamente. Consulte Descoberta e despacho de ferramentas.

Configurações de MCP na aplicação ​

Versões empacotadas do Ogma podem gerenciar MCP em Configurações > MCP. Use a tela de configurações quando quiser que o Ogma inicie ou pare o processo MCP integrado da instância ativa.

Use o binário independente ogma-mcp quando seu cliente de IA esperar iniciar o servidor MCP diretamente.

Salvar as configurações reinicia automaticamente um processo MCP integrado em execução. Reconecte os clientes depois; IDs de sessão e tokens de confirmação antigos não podem ser reutilizados. Diagnóstico de execução exibe a saída recente do processo.

O Ogma também expõe o gerenciamento do MCP por sua API REST local. Essas rotas ficam na porta da API do backend, não na porta dedicada ao MCP. Elas são usadas pela tela de configurações e pela ponte de IA da aplicação:

EndpointFinalidade
GET /mcp/statusRetorna { running, pid, endpoint, config, diagnostics }. endpoint é null quando está parado; os diagnósticos contêm registros recentes { stream, message }.
POST /mcp/startInicia o MCP integrado com as configurações persistidas e retorna o estado. Sem corpo. Retorna um conflito se já estiver em execução.
POST /mcp/stopPara o processo filho do MCP integrado.
GET /settings/mcpRetorna a configuração persistida do MCP.
PUT /settings/mcpAceita um objeto de configuração completo, salva e reinicia o MCP se estiver em execução. Retorna a configuração aceita ou um erro. Somente hosts de vinculação de loopback são permitidos.
GET /mcp/toolsRetorna { tools, config }, incluindo o inputSchema de cada ferramenta. Esse catálogo REST não é paginado.
POST /mcp/tools/callChama uma ferramenta com { "name": "ogma_explain_capabilities", "arguments": {} }. Retorna { "result": "..." }; interprete esse texto como o envelope JSON da ferramenta. Não é um resultado MCP nativo com blocos de imagem.

A ponte REST usa permissões persistidas, mas não exige que o processo filho HTTP MCP separado seja iniciado. Ela compartilha uma sessão de ponte para o backend e a configuração. Prefira MCP nativo para sessões isoladas de clientes e saída de imagens.

Em falhas da ponte, interpretar result produz { "error": "..." }, contendo o envelope de erro serializado. Verifique esse valor em vez de tratar um status HTTP de sucesso como sucesso da ferramenta.

Configuração persistida padrão do MCP:

json
{
  "bind_host": "127.0.0.1",
  "port": 3000,
  "allow_write_findings": false,
  "allow_export_data": false,
  "allow_read_secrets": false,
  "allow_send_requests": false,
  "allow_run_workflows": false,
  "allow_intercept_control": false,
  "tool_profile": "full"
}

Os hosts de vinculação permitidos são 127.0.0.1, localhost e ::1; as portas devem estar entre 1024 e 65535. Esta versão não configura autenticação para MCP exposto à rede, portanto endereços de vinculação públicos são rejeitados. Os campos legados allow_public_bind e acknowledge_write_tool_risk não anulam essa restrição.

Claude Code ​

Para o endpoint desktop em execução:

bash
claude mcp add --transport http ogma http://127.0.0.1:3000/mcp

Use o endpoint exibido pelo Ogma se for diferente. Consulte a configuração MCP do Claude Code para os escopos de configuração e as opções de stdio. Verifique com: "Quais projetos o Ogma tem?"

Cursor ​

Mescle esta entrada no .cursor/mcp.json do seu projeto ou no ~/.cursor/mcp.json do usuário:

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

Habilite a conexão nas configurações de MCP do Cursor. Consulte a documentação de MCP do Cursor.

Configuração do cliente stdio ​

Clientes que iniciam um executável podem usar esta entrada de servidor, ajustando o local do arquivo de configuração conforme necessário:

json
{
  "mcpServers": {
    "ogma": {
      "command": "/absolute/path/to/ogma-mcp",
      "args": ["--api-url", "http://127.0.0.1:8181"]
    }
  }
}

No Windows, use o caminho completo do executável e escape as barras invertidas no JSON. Alguns clientes também exigem "type": "stdio". Adicione flags de permissão a args conforme necessário.

Permissões ​

Todas as seis capacidades privilegiadas são desabilitadas por padrão. Leia seus valores atuais em ogma://mcp/permissions. Uma ferramenta listada ainda pode rejeitar a execução até que sua capacidade seja habilitada. A tabela completa de flags e variáveis de ambiente está na referência da CLI.

A interação com o navegador, o gerenciamento de contextos, a troca de projeto e todas as chamadas de jornadas de autenticação exigem --allow-send-requests. A observação do navegador pode inspecionar um navegador já em execução sem habilitar suas ferramentas de controle. --allow-read-secrets (ou OGMA_MCP_ALLOW_READ_SECRETS=true) permite separadamente valores de variáveis de ambiente sem mascaramento.

O servidor não tem cotas de atividade por minuto ou por sessão. As ferramentas individuais ainda aplicam seus tamanhos de entrada, tamanhos de lote, verificações de escopo e tempos limite. As antigas flags de cotas de envio e fluxos de trabalho não são mais suportadas.

Modo somente leitura ​

Por padrão, o servidor MCP é somente leitura. Estas operações não ficam disponíveis sem habilitação explícita:

  • Enviar requisições (Reenvio)
  • Controlar o navegador integrado, o rastreador, a captura de autenticação e os auxiliares de sondagem ativa
  • Executar fluxos de trabalho
  • Criar ou modificar achados
  • Modificar o escopo ou as regras de localizar e substituir
  • Modificar ou encaminhar tráfego interceptado
  • Excluir dados
  • Acessar valores secretos de variáveis de ambiente
  • Exportar dados

As prévias de corpos têm 512 bytes por padrão. --body-preview-bytes ajusta as prévias e deve ser pelo menos 1; não limita a saída de todas as ferramentas. Use ogma_get_http_entry_body para um corpo HTTP completo ou uma pesquisa específica no corpo, e ogma_get_ws_message para uma mensagem WebSocket completa.

Ferramentas de escrita de achados ​

Para habilitar a criação de achados assistida por IA, reinicie o ogma-mcp com permissões de escrita:

bash
./ogma-mcp --allow-write-findings

Ou defina a variável de ambiente:

bash
OGMA_MCP_ALLOW_WRITE_FINDINGS=true ./ogma-mcp

Ferramentas de escrita disponíveis ​

FerramentaDescrição
ogma_preview_finding_from_evidenceMostra uma prévia de um rascunho de achado a partir de uma entrada HTTP (somente leitura, sempre disponível)
ogma_create_findingCria um achado com severidade, estado, tags e links de evidências
ogma_update_findingAtualiza um achado existente
ogma_add_finding_tagAdiciona tags a um achado sem substituir as existentes
ogma_link_finding_evidenceVincula uma entrada HTTP, tentativa de Reenvio, resultado de Automação ou mensagem WS a um achado
ogma_delete_findingExclui um achado
ogma_export_findings_reportGera um relatório HTML, Markdown ou PDF

A implementação atual também usa a permissão de escrita de achados para ferramentas de escrita compartilhadas, como atualizações de variáveis de ambiente, anotações do histórico, seleção de escopo e alterações de Localizar e substituir. Consulte o catálogo de ferramentas para essas ações.

Exemplo: criação de achados assistida por IA ​

Com --allow-write-findings:

  1. "Analise a entrada HTTP {id} em busca de problemas de segurança. Se encontrar um problema real, use ogma_create_finding para documentá-lo."
  2. A IA chamará ogma_get_http_entry para inspecionar a requisição
  3. Se as evidências sustentarem um achado, ela chamará ogma_create_finding com as evidências vinculadas

Ainda indisponível apenas com escrita de achados ​

  • Envio de Reenvio
  • Execução de fluxos de trabalho
  • Criação de exportações
  • Controle da fila de interceptação
  • Troca de projeto

Ferramentas de exportação ​

Para habilitar a criação de trabalhos de exportação assistida por IA, reinicie o ogma-mcp com permissões de exportação:

bash
./ogma-mcp --allow-export-data

Ou defina a variável de ambiente:

bash
OGMA_MCP_ALLOW_EXPORT_DATA=true ./ogma-mcp

Ferramentas de exportação disponíveis ​

FerramentaPermissão necessáriaDescrição
ogma_preview_export_planNenhuma (somente leitura)Mostra uma prévia do que seria incluído em uma exportação
ogma_list_export_jobsNenhuma (somente leitura)Lista trabalhos de exportação recentes
ogma_get_export_jobNenhuma (somente leitura)Verifica o estado de um trabalho de exportação
ogma_get_export_download_infoNenhuma (somente leitura)Obtém a URL de download de uma exportação concluída
ogma_create_export_jobexport_dataCria um trabalho de exportação

Tipos e formatos de exportação suportados ​

TipoDescriçãoFormatos
http_historyTodas as requisições HTTP que passam pelo proxyjson, csv, raw_http
searchRequisições HTTP filtradasjson, csv, raw_http
findingsAchados de segurançajson, csv
automate_resultsResultados de sessões de Automaçãojson, csv

Nota: o formato raw_http só é válido para os tipos http_history e search.

Aviso de segurança ​

Arquivos de exportação podem conter corpos completos de requisições e respostas HTTP, que podem incluir senhas, tokens e dados pessoais. Trate os arquivos de exportação com o cuidado adequado.

Ainda indisponível apenas com permissões de exportação ​

  • Exclusão de arquivos de exportação
  • Renomeação de arquivos de exportação
  • Transmissão do conteúdo de exportação pelo MCP
  • Envio de Reenvio
  • Execução de fluxos de trabalho

Envio de requisições de Reenvio ​

Aviso: isso habilita o envio de tráfego HTTP de saída real pelo Reenvio do Ogma.

Para habilitar:

bash
./ogma-mcp --allow-send-requests

Ou por variáveis de ambiente:

bash
OGMA_MCP_ALLOW_SEND_REQUESTS=true ./ogma-mcp

Pré-requisitos ​

  1. O proxy do Ogma deve estar em execução
  2. Um escopo ativo deve estar configurado em Escopos para envios de Reenvio protegidos
  3. O host de destino deve estar no escopo ativo

Ferramentas de envio ​

FerramentaPermissãoDescrição
ogma_preview_replay_sendsend_requestsPrepara um envio e obtém um token de confirmação
ogma_send_replay_requestsend_requestsExecuta o envio com um token de confirmação
ogma_create_replay_session_from_historysend_requestsCria uma sessão de Reenvio
ogma_create_replay_session_rawsend_requestsCria uma sessão de Reenvio a partir de uma definição de requisição bruta
ogma_browser_form_to_replaysend_requestsCria uma sessão de Reenvio a partir de um formulário na página atual
ogma_create_scope_presetsend_requestsArmazena uma predefinição de escopo; ative separadamente com ogma_set_active_scope
ogma_repeat_requestsend_requestsRepete uma requisição capturada com alterações opcionais
ogma_replay_with_modificationssend_requestsReenvia uma requisição capturada com substituições por campo
ogma_http_requestsend_requestsEnvia uma requisição HTTP direta
ogma_fetch_urlsend_requestsBusca uma URL e retorna o status, os cabeçalhos e uma prévia
ogma_follow_redirectsend_requestsSegue uma cadeia de redirecionamentos e informa cada salto
ogma_bulk_send_requestssend_requestsEnvia um lote limitado de requisições
ogma_fuzz_parametersend_requestsSubstitui um marcador por valores de uma lista de palavras
ogma_multipart_uploadsend_requestsEnvia requisições multipart form-data para testes de upload
ogma_websocket_connectsend_requestsConecta-se a uma URL WebSocket e troca mensagens
ogma_login_replay_autosend_requestsEnvia um formulário de login no navegador e captura um perfil de autenticação
ogma_auth_capture_profilesend_requestsCaptura cookies, armazenamento, tokens de autenticação e candidatos CSRF do navegador
ogma_auth_apply_profilesend_requestsAplica um perfil de autenticação capturado ao navegador
ogma_auth_refresh_csrfsend_requestsAtualiza candidatos CSRF a partir do estado do navegador
ogma_authz_matrix_testsend_requestsReenvia uma requisição com vários perfis de autenticação
ogma_run_active_probe_workflowsend_requestsExecuta sondagens ativas limitadas e específicas de vulnerabilidades
ogma_test_racesend_requestsEnvia uma requisição de forma concorrente e informa as respostas cujo código de status difere do mais frequente
ogma_test_smugglingsend_requestsEnvia sondagens de dessincronização de requisições CL.TE e TE.CL por TCP bruto
ogma_test_hppsend_requestsEnvia variações de poluição de parâmetros HTTP
ogma_run_nucleisend_requestsExecuta um modelo do scanner de modelos, incluído ou fornecido, contra uma URL de destino
ogma_browser_navigate e ferramentas de interação com o navegadorsend_requestsControlam o navegador integrado e capturam o tráfego resultante
ogma_crawl_sitesend_requestsRastreia um destino no escopo pelo navegador integrado
ogma_get_replay_sessionNenhumaConsulta metadados de uma sessão de Reenvio
ogma_get_replay_attemptNenhumaConsulta metadados de uma tentativa de Reenvio
ogma_list_replay_sessionsNenhumaLista sessões de Reenvio

Fluxo de trabalho em duas etapas ​

O par de ferramentas de Reenvio baseado em confirmação usa duas chamadas:

  1. ogma_preview_replay_send - revise a requisição e obtenha um token de confirmação
  2. ogma_send_replay_request - confirme e envie com o token

Os tokens de confirmação expiram em 5 minutos, são de uso único e pertencem à sessão MCP que os criou. Gere outra prévia depois de alterar a requisição ou reiniciar o MCP. Essa regra de duas etapas não se aplica a todas as ferramentas de envio: ferramentas HTTP diretas, auxiliares de repetição e ações do navegador podem enviar imediatamente quando habilitados.

Sessão de exemplo ​

Usuário: Reenvie a entrada HTTP abc123 e verifique a resposta
IA: (chama ogma_preview_replay_send com http_entry_id="abc123")
    - mostra a prévia da requisição, o token de confirmação e o estado do escopo --
IA: (chama ogma_send_replay_request com confirmation_token e request_hash)
    - mostra o status da resposta, os tempos e a prévia da resposta --

Ainda indisponível apenas com permissões de envio de requisições ​

  • Execução de fluxos de trabalho
  • Criação ou atualização de achados
  • Exclusão

Mantenha o escopo ativo restrito antes de habilitar essas ferramentas. Verificações de escopo se aplicam às rotas de envio protegidas; não trate o escopo como um firewall universal para JavaScript arbitrário do navegador ou para todos os auxiliares de busca direta.

Controle de interceptação ​

Aviso: o controle de interceptação permite que um cliente MCP encaminhe, descarte ou modifique tráfego em tempo real atualmente retido na fila de interceptação do Ogma.

Para habilitar:

bash
./ogma-mcp --allow-intercept-control

Ou por variável de ambiente:

bash
OGMA_MCP_ALLOW_INTERCEPT_CONTROL=true ./ogma-mcp

Ferramentas de interceptação ​

FerramentaPermissãoDescrição
ogma_get_intercept_statusintercept_controlLê o estado de interceptação de requisições, respostas e WebSocket
ogma_set_intercept_enabledintercept_controlHabilita ou desabilita os modos de interceptação
ogma_list_intercept_queueintercept_controlLista os itens atualmente retidos
ogma_get_intercept_itemintercept_controlInspeciona um item da fila
ogma_forward_intercept_itemintercept_controlEncaminha um item da fila, opcionalmente modificado
ogma_drop_intercept_itemintercept_controlDescarta um item da fila
ogma_intercept_and_modifyintercept_controlAguarda um item correspondente, modifica e encaminha

Execução de fluxos de trabalho ​

Aviso: a execução de fluxos de trabalho executa sua lógica. Alguns fluxos enviam tráfego HTTP ou criam achados.

Para habilitar:

bash
./ogma-mcp --allow-run-workflows

Ferramentas de execução de fluxos de trabalho ​

FerramentaPermissãoDescrição
ogma_get_workflow_safetyNenhuma (somente leitura)Classifica os efeitos colaterais de um fluxo de trabalho
ogma_preview_workflow_runrun_workflowsMostra uma prévia e obtém um token de confirmação
ogma_run_workflowrun_workflowsExecuta com um token de confirmação
ogma_cancel_workflow_runrun_workflowsCancela um fluxo de trabalho ativo em execução

Gere a prévia com workflow_id, mais input para um fluxo de conversão ou trigger_entry_id para uma entrada capturada de um fluxo ativo. Execute com o confirmation_token e o definition_hash retornados; fluxos de conversão também precisam de input_hash e do mesmo input. Os tokens expiram após cinco minutos e são de uso único. Leia a execução resultante com ogma_get_workflow_run.

A execução de Automação está disponível por suas ferramentas de sessão e execução com permissão de envio de requisições, não com a permissão de execução de fluxos de trabalho. Listar e inspecionar execuções existentes não exige permissão de envio.

Requisitos entre permissões ​

Fluxos de trabalho que usam sdk.requests.send também exigem --allow-send-requests. Fluxos de trabalho que usam sdk.findings.create também exigem --allow-write-findings.

A detecção se baseia em análise estática de texto; consulte a nota de orientação abaixo.

Nota de orientação sobre a classificação de segurança ​

A classificação de segurança de fluxos de trabalho inspeciona o texto do código-fonte JavaScript em busca de padrões como sdk.requests.send. Essa detecção não é exaustiva: chamadas a métodos do SDK ofuscadas ou construídas dinamicamente podem não ser detectadas. Sempre revise o código-fonte JavaScript antes de executar fluxos de trabalho não confiáveis.

Ainda indisponível apenas com permissões de fluxos de trabalho ​

  • Acionamento manual de fluxos de trabalho passivos
  • Exclusão
  • Alteração de variáveis de ambiente

Prompts de exemplo ​

Depois de conectar:

  • "Mostre as últimas 20 requisições HTTP para example.com"
  • "Há achados de severidade alta ou crítica neste projeto?"
  • "Quais fluxos de trabalho estão habilitados atualmente?"
  • "Verifique se a consulta HTTPQL req.method.eq:\"POST\" é válida"
  • "Resuma o estado de segurança do projeto atual"
  • "Analise a entrada HTTP {id} em busca de problemas de segurança"

Solução de problemas ​

Conexão recusada: inicie o Ogma primeiro (ogma --data-dir ./ogma-data).

O cliente MCP não mostra ferramentas: verifique a URL de transporte ou o caminho do executável. Os clientes devem seguir todos os cursores de tools/list; cada página contém até 40 ferramentas. Verifique a filtragem do cliente e se sua versão instalada inclui a ferramenta ausente.

Sessão ou token de confirmação inválido: reconecte depois de um reinício e gere um novo token de prévia.

Navegador indisponível ou ação falhou: mantenha a aplicação desktop em execução. Verifique ogma_browser_health, os diálogos e a recuperação do navegador. Um backend sem interface gráfica sozinho não fornece a ponte do navegador desktop.

A captura de tela não tem texto legível: use um cliente que suporte conteúdo de imagem MCP nativo ou inspecione a captura semântica.

Resultados vazios: o Ogma precisa capturar tráfego primeiro. Navegue com seu proxy configurado para encaminhar o tráfego pelo Ogma.

Software proprietário. Todos os direitos reservados.