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.


Para a lista completa de recursos e ferramentas, consulte Recursos e ferramentas MCP.
Início rápido: aplicação desktop
- Inicie o Ogma e abra o projeto que o agente deve inspecionar.
- Abra Configurações > MCP, escolha as permissões necessárias e salve. A interação com o navegador exige Reenvio de requisições.
- Clique em Iniciar e copie o endpoint exibido, normalmente
http://127.0.0.1:3000/mcp. - Adicione-o ao seu cliente MCP como um servidor Streamable HTTP.
- Peça ao agente para chamar
ogma_explain_capabilitiese lerogma://project/currentpara 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
| Interface | Endereço padrão | Finalidade |
|---|---|---|
| Transporte MCP | http://127.0.0.1:3000/mcp | Clientes MCP nativos se conectam aqui. |
| API REST do backend | http://127.0.0.1:8181 | --api-url do MCP independente e as rotas de gerenciamento e da ponte descritas abaixo. |
| Listener do proxy | 127.0.0.1:8080 | Captura 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 --releaseA 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 2048O 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:
| Endpoint | Finalidade |
|---|---|
GET /mcp/status | Retorna { running, pid, endpoint, config, diagnostics }. endpoint é null quando está parado; os diagnósticos contêm registros recentes { stream, message }. |
POST /mcp/start | Inicia 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/stop | Para o processo filho do MCP integrado. |
GET /settings/mcp | Retorna a configuração persistida do MCP. |
PUT /settings/mcp | Aceita 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/tools | Retorna { tools, config }, incluindo o inputSchema de cada ferramenta. Esse catálogo REST não é paginado. |
POST /mcp/tools/call | Chama 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/mcpUse 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-findingsOu defina a variável de ambiente:
bash
OGMA_MCP_ALLOW_WRITE_FINDINGS=true ./ogma-mcpFerramentas de escrita disponíveis
| Ferramenta | Descrição |
|---|---|
ogma_preview_finding_from_evidence | Mostra uma prévia de um rascunho de achado a partir de uma entrada HTTP (somente leitura, sempre disponível) |
ogma_create_finding | Cria um achado com severidade, estado, tags e links de evidências |
ogma_update_finding | Atualiza um achado existente |
ogma_add_finding_tag | Adiciona tags a um achado sem substituir as existentes |
ogma_link_finding_evidence | Vincula uma entrada HTTP, tentativa de Reenvio, resultado de Automação ou mensagem WS a um achado |
ogma_delete_finding | Exclui um achado |
ogma_export_findings_report | Gera 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:
- "Analise a entrada HTTP {id} em busca de problemas de segurança. Se encontrar um problema real, use ogma_create_finding para documentá-lo."
- A IA chamará
ogma_get_http_entrypara inspecionar a requisição - Se as evidências sustentarem um achado, ela chamará
ogma_create_findingcom 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-dataOu defina a variável de ambiente:
bash
OGMA_MCP_ALLOW_EXPORT_DATA=true ./ogma-mcpFerramentas de exportação disponíveis
| Ferramenta | Permissão necessária | Descrição |
|---|---|---|
ogma_preview_export_plan | Nenhuma (somente leitura) | Mostra uma prévia do que seria incluído em uma exportação |
ogma_list_export_jobs | Nenhuma (somente leitura) | Lista trabalhos de exportação recentes |
ogma_get_export_job | Nenhuma (somente leitura) | Verifica o estado de um trabalho de exportação |
ogma_get_export_download_info | Nenhuma (somente leitura) | Obtém a URL de download de uma exportação concluída |
ogma_create_export_job | export_data | Cria um trabalho de exportação |
Tipos e formatos de exportação suportados
| Tipo | Descrição | Formatos |
|---|---|---|
http_history | Todas as requisições HTTP que passam pelo proxy | json, csv, raw_http |
search | Requisições HTTP filtradas | json, csv, raw_http |
findings | Achados de segurança | json, csv |
automate_results | Resultados de sessões de Automação | json, 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-requestsOu por variáveis de ambiente:
bash
OGMA_MCP_ALLOW_SEND_REQUESTS=true ./ogma-mcpPré-requisitos
- O proxy do Ogma deve estar em execução
- Um escopo ativo deve estar configurado em Escopos para envios de Reenvio protegidos
- O host de destino deve estar no escopo ativo
Ferramentas de envio
| Ferramenta | Permissão | Descrição |
|---|---|---|
ogma_preview_replay_send | send_requests | Prepara um envio e obtém um token de confirmação |
ogma_send_replay_request | send_requests | Executa o envio com um token de confirmação |
ogma_create_replay_session_from_history | send_requests | Cria uma sessão de Reenvio |
ogma_create_replay_session_raw | send_requests | Cria uma sessão de Reenvio a partir de uma definição de requisição bruta |
ogma_browser_form_to_replay | send_requests | Cria uma sessão de Reenvio a partir de um formulário na página atual |
ogma_create_scope_preset | send_requests | Armazena uma predefinição de escopo; ative separadamente com ogma_set_active_scope |
ogma_repeat_request | send_requests | Repete uma requisição capturada com alterações opcionais |
ogma_replay_with_modifications | send_requests | Reenvia uma requisição capturada com substituições por campo |
ogma_http_request | send_requests | Envia uma requisição HTTP direta |
ogma_fetch_url | send_requests | Busca uma URL e retorna o status, os cabeçalhos e uma prévia |
ogma_follow_redirect | send_requests | Segue uma cadeia de redirecionamentos e informa cada salto |
ogma_bulk_send_requests | send_requests | Envia um lote limitado de requisições |
ogma_fuzz_parameter | send_requests | Substitui um marcador por valores de uma lista de palavras |
ogma_multipart_upload | send_requests | Envia requisições multipart form-data para testes de upload |
ogma_websocket_connect | send_requests | Conecta-se a uma URL WebSocket e troca mensagens |
ogma_login_replay_auto | send_requests | Envia um formulário de login no navegador e captura um perfil de autenticação |
ogma_auth_capture_profile | send_requests | Captura cookies, armazenamento, tokens de autenticação e candidatos CSRF do navegador |
ogma_auth_apply_profile | send_requests | Aplica um perfil de autenticação capturado ao navegador |
ogma_auth_refresh_csrf | send_requests | Atualiza candidatos CSRF a partir do estado do navegador |
ogma_authz_matrix_test | send_requests | Reenvia uma requisição com vários perfis de autenticação |
ogma_run_active_probe_workflow | send_requests | Executa sondagens ativas limitadas e específicas de vulnerabilidades |
ogma_test_race | send_requests | Envia uma requisição de forma concorrente e informa as respostas cujo código de status difere do mais frequente |
ogma_test_smuggling | send_requests | Envia sondagens de dessincronização de requisições CL.TE e TE.CL por TCP bruto |
ogma_test_hpp | send_requests | Envia variações de poluição de parâmetros HTTP |
ogma_run_nuclei | send_requests | Executa 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 navegador | send_requests | Controlam o navegador integrado e capturam o tráfego resultante |
ogma_crawl_site | send_requests | Rastreia um destino no escopo pelo navegador integrado |
ogma_get_replay_session | Nenhuma | Consulta metadados de uma sessão de Reenvio |
ogma_get_replay_attempt | Nenhuma | Consulta metadados de uma tentativa de Reenvio |
ogma_list_replay_sessions | Nenhuma | Lista sessões de Reenvio |
Fluxo de trabalho em duas etapas
O par de ferramentas de Reenvio baseado em confirmação usa duas chamadas:
ogma_preview_replay_send- revise a requisição e obtenha um token de confirmaçãoogma_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-controlOu por variável de ambiente:
bash
OGMA_MCP_ALLOW_INTERCEPT_CONTROL=true ./ogma-mcpFerramentas de interceptação
| Ferramenta | Permissão | Descrição |
|---|---|---|
ogma_get_intercept_status | intercept_control | Lê o estado de interceptação de requisições, respostas e WebSocket |
ogma_set_intercept_enabled | intercept_control | Habilita ou desabilita os modos de interceptação |
ogma_list_intercept_queue | intercept_control | Lista os itens atualmente retidos |
ogma_get_intercept_item | intercept_control | Inspeciona um item da fila |
ogma_forward_intercept_item | intercept_control | Encaminha um item da fila, opcionalmente modificado |
ogma_drop_intercept_item | intercept_control | Descarta um item da fila |
ogma_intercept_and_modify | intercept_control | Aguarda 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-workflowsFerramentas de execução de fluxos de trabalho
| Ferramenta | Permissão | Descrição |
|---|---|---|
ogma_get_workflow_safety | Nenhuma (somente leitura) | Classifica os efeitos colaterais de um fluxo de trabalho |
ogma_preview_workflow_run | run_workflows | Mostra uma prévia e obtém um token de confirmação |
ogma_run_workflow | run_workflows | Executa com um token de confirmação |
ogma_cancel_workflow_run | run_workflows | Cancela 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.