Configuración del servidor MCP de Ogma

El servidor MCP de Ogma (ogma-mcp) permite a los asistentes de IA compatibles inspeccionar el contexto del proyecto y, cuando se habilita, controlar el navegador integrado, enviar solicitudes, ejecutar flujos de trabajo y recopilar evidencias. Sus herramientas de notas y tareas son un bloc de trabajo en memoria de la sesión MCP, separado de la página de Notas persistente de la aplicación.

MCP está destinado a herramientas externas como Codex, Claude Code, Cursor y otros clientes de Model Context Protocol. No es la misma función que el asistente IA del espacio de trabajo integrado en la aplicación.

Para consultar la lista completa de recursos y herramientas, consulta Recursos y herramientas MCP.

Inicio rápido: aplicación de escritorio

1. Inicia Ogma y abre el proyecto que deba inspeccionar el agente.
2. Abre Configuración > MCP, elige los permisos necesarios y guarda los cambios. La interacción con el navegador requiere Envío desde Reenvío.
3. Haz clic en Iniciar y copia el endpoint mostrado, normalmente http://127.0.0.1:3000/mcp.
4. Añádelo a tu cliente MCP como servidor Streamable HTTP.
5. Pide al agente que llame a ogma_explain_capabilities y lea ogma://project/current para comprobar la conexión y el proyecto activo.

Esta opción no requiere compilar un binario independiente. Para navegación de páginas, formularios, recorridos de inicio de sesión y resolución de problemas, consulta Automatización del navegador con MCP.

Direcciones de conexión

Interfaz	Dirección predeterminada	Finalidad
Transporte MCP	http://127.0.0.1:3000/mcp	Los clientes MCP nativos se conectan aquí.
API REST del backend	http://127.0.0.1:8181	--api-url del MCP independiente y las rutas de administración y del puente descritas abajo.
Escucha del proxy	127.0.0.1:8080	Captura el tráfico del navegador; no es un endpoint MCP.

Las instancias de escritorio pueden asignar dinámicamente el puerto de la API del backend. Usa la dirección real de la instancia en ejecución para las integraciones stdio/REST y el endpoint mostrado en Configuración para MCP nativo. Un servicio de chat en la nube no puede acceder a tu dirección de bucle local sin un cliente o conector local.

El endpoint HTTP mantiene estado: deja que el cliente gestione la inicialización y las cabeceras de sesión. No hay un endpoint heredado /sse separado. Los clientes personalizados deben seguir la especificación de transporte de MCP.

Cuándo usar MCP

Usa MCP cuando un asistente externo deba ayudarte a:

• Resumir el tráfico capturado.
• Clasificar hallazgos por prioridad.
• Redactar texto de informes basado en evidencias.
• Revisar flujos de trabajo y sesiones de Reenvío.
• Preparar acciones dentro del alcance que apruebes explícitamente.

Usa IA del espacio de trabajo si prefieres la ventana del asistente integrada en Ogma.

Requisitos del servidor independiente

Usa stdio cuando tu cliente necesite iniciar un ejecutable local en lugar de conectarse al endpoint HTTP integrado.

• Backend de Ogma en ejecución en su dirección API real (valor predeterminado de la CLI: http://127.0.0.1:8181)
• El binario ogma-mcp (compilado a partir del código fuente)

Compilación

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

La salida predeterminada es target/release/ogma-mcp (ogma-mcp.exe en Windows), salvo que hayas personalizado el directorio de destino de Cargo.

Ejecución

# 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

El servidor termina si no puede acceder a la API de Ogma. Configura el cliente MCP para iniciar este comando; stdout transporta los mensajes MCP y stderr contiene los diagnósticos. Los permisos de stdio proceden de sus propias opciones, no de la configuración de MCP integrado.

Descubrimiento de herramientas

El servidor actual siempre anuncia su catálogo completo de herramientas. No hay un selector de perfiles de herramientas en Configuración. Los valores antiguos de --tool-profile, --mcp-tool-profile y OGMA_MCP_TOOL_PROFILE se aceptan por compatibilidad, pero no ocultan herramientas ni conceden permisos.

Para un catálogo extenso, empieza con ogma_explain_capabilities y ogma_find_tools en lugar de adivinar las entradas. Busca palabras clave de la tarea para seleccionar herramientas y luego consulta el nombre exacto de una herramienta para inspeccionar su contrato. Los despachadores de navegador y búsqueda ofrecen puntos de entrada prácticos; las herramientas específicas siguen estando disponibles directamente. Consulta Descubrimiento y despacho de herramientas.

Configuración de MCP en la aplicación

Las versiones empaquetadas de Ogma pueden gestionar MCP desde Configuración > MCP. Usa esa pantalla cuando quieras que Ogma inicie o detenga el proceso MCP integrado de la instancia activa.

Usa el binario independiente ogma-mcp cuando tu cliente de IA espere iniciar directamente el servidor MCP.

Guardar la configuración reinicia automáticamente un proceso MCP integrado que esté en ejecución. Después, vuelve a conectar los clientes; los identificadores de sesión y tokens de confirmación anteriores no pueden reutilizarse. Diagnóstico de ejecución muestra la salida reciente del proceso.

Ogma también expone la administración de MCP mediante su API REST local. Estas rutas están en el puerto de la API del backend, no en el puerto dedicado de MCP. Las utilizan la pantalla de configuración y el puente de IA integrado en la aplicación:

Endpoint	Finalidad
GET /mcp/status	Devuelve { running, pid, endpoint, config, diagnostics }. endpoint es null cuando está detenido; los diagnósticos contienen registros recientes { stream, message }.
POST /mcp/start	Inicia MCP integrado con la configuración persistente y devuelve el estado. Sin cuerpo. Devuelve un conflicto si ya está en ejecución.
POST /mcp/stop	Detiene el proceso hijo de MCP integrado.
GET /settings/mcp	Devuelve la configuración persistente de MCP.
PUT /settings/mcp	Acepta un objeto de configuración completo, lo guarda y reinicia MCP si está en ejecución. Devuelve la configuración aceptada o un error. Solo se permiten hosts de enlace de bucle local.
GET /mcp/tools	Devuelve { tools, config }, incluido el inputSchema de cada herramienta. Este catálogo REST no está paginado.
POST /mcp/tools/call	Llama a una herramienta con { "name": "ogma_explain_capabilities", "arguments": {} }. Devuelve { "result": "..." }; analiza ese texto como el contenedor JSON de la herramienta. No es un resultado MCP nativo con bloques de imagen.

El puente REST usa los permisos persistentes, pero no requiere iniciar el proceso hijo HTTP MCP independiente. Comparte una sesión de puente para el backend y la configuración. Prefiere MCP nativo para sesiones de cliente aisladas y salida de imágenes.

En los fallos del puente, analizar result produce { "error": "..." }, que contiene el contenedor de error serializado. Comprueba ese valor en lugar de considerar un estado HTTP correcto como éxito de la herramienta.

Configuración persistente predeterminada de MCP:

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

Los hosts de enlace permitidos son 127.0.0.1, localhost y ::1; los puertos deben estar entre 1024 y 65535. Esta versión no configura autenticación para MCP expuesto a la red, por lo que rechaza las direcciones de enlace públicas. Los campos heredados allow_public_bind y acknowledge_write_tool_risk no anulan esta restricción.

Claude Code

Para el endpoint de escritorio en ejecución:

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

Usa el endpoint mostrado por Ogma si es diferente. Consulta la configuración MCP de Claude Code para los ámbitos de configuración y las opciones de stdio. Verifica con: "¿Qué proyectos tiene Ogma?"

Cursor

Combina esta entrada con el archivo .cursor/mcp.json de tu proyecto o el archivo de usuario ~/.cursor/mcp.json:

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

Habilita la conexión en la configuración MCP de Cursor. Consulta la documentación MCP de Cursor.

Configuración del cliente stdio

Los clientes que inician un ejecutable pueden usar esta entrada de servidor, ajustando la ubicación del archivo de configuración según sea necesario:

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

En Windows, usa la ruta completa del ejecutable y escapa las barras inversas en JSON. Algunos clientes también requieren "type": "stdio". Añade las opciones de permisos a args según sea necesario.

Permisos

Las seis capacidades privilegiadas están deshabilitadas de forma predeterminada. Lee sus valores actuales en ogma://mcp/permissions. Una herramienta listada puede seguir rechazando la ejecución hasta que se habilite su capacidad. La tabla completa de opciones y variables de entorno está en la referencia de la CLI.

La interacción con el navegador, la gestión de contextos, el cambio de proyecto y todas las llamadas de recorridos de autenticación requieren --allow-send-requests. La observación del navegador puede inspeccionar un navegador ya en ejecución sin habilitar sus herramientas de control. --allow-read-secrets (o OGMA_MCP_ALLOW_READ_SECRETS=true) permite por separado los valores de variables de entorno sin enmascarar.

El servidor no tiene cuotas de actividad por minuto ni por sesión. Las herramientas individuales siguen aplicando sus tamaños de entrada, tamaños de lote, comprobaciones de alcance y tiempos de espera. Las antiguas opciones de cuotas de envío y flujos de trabajo ya no se admiten.

Modo de solo lectura

De forma predeterminada, el servidor MCP es de solo lectura. Estas operaciones no están disponibles salvo que se habiliten explícitamente:

• Enviar solicitudes (Reenvío)
• Controlar el navegador integrado, el rastreador, la captura de autenticación y los asistentes de sondeo activo
• Ejecutar flujos de trabajo
• Crear o modificar hallazgos
• Modificar el alcance o las reglas de coincidencia y reemplazo
• Modificar o reenviar tráfico interceptado
• Eliminar datos
• Acceder a valores secretos de variables de entorno
• Exportar datos

Las vistas previas de cuerpos tienen un valor predeterminado de 512 bytes. --body-preview-bytes ajusta las vistas previas y debe ser al menos 1; no limita la salida de todas las herramientas. Usa ogma_get_http_entry_body para obtener un cuerpo HTTP completo o buscar específicamente en él, y ogma_get_ws_message para obtener un mensaje WebSocket completo.

Herramientas de escritura de hallazgos

Para habilitar la creación de hallazgos asistida por IA, reinicia ogma-mcp con permisos de escritura:

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

O establece la variable de entorno:

OGMA_MCP_ALLOW_WRITE_FINDINGS=true ./ogma-mcp

Herramientas de escritura disponibles

Herramienta	Descripción
ogma_preview_finding_from_evidence	Muestra una vista previa de un borrador de hallazgo a partir de una entrada HTTP (solo lectura, siempre disponible)
ogma_create_finding	Crea un hallazgo con gravedad, estado, etiquetas y enlaces a evidencias
ogma_update_finding	Actualiza un hallazgo existente
ogma_add_finding_tag	Añade etiquetas a un hallazgo sin reemplazar las existentes
ogma_link_finding_evidence	Vincula una entrada HTTP, un intento de Reenvío, un resultado de Automatización o un mensaje WS a un hallazgo
ogma_delete_finding	Elimina un hallazgo
ogma_export_findings_report	Genera un informe HTML, Markdown o PDF

La implementación actual también usa el permiso de escritura de hallazgos para herramientas de escritura compartidas, como actualizaciones de variables de entorno, anotaciones del historial, selección del alcance y modificaciones de Buscar y reemplazar. Consulta el catálogo de herramientas para esas acciones.

Ejemplo: creación de hallazgos asistida por IA

Con --allow-write-findings:

1. "Analiza la entrada HTTP {id} en busca de problemas de seguridad. Si encuentras un problema real, usa ogma_create_finding para documentarlo."
2. La IA llamará a ogma_get_http_entry para inspeccionar la solicitud
3. Si las evidencias respaldan un hallazgo, llamará a ogma_create_finding con las evidencias vinculadas

Aún no disponible solo con escritura de hallazgos

• Envío desde Reenvío
• Ejecución de flujos de trabajo
• Creación de exportaciones
• Control de la cola de interceptación
• Cambio de proyecto

Herramientas de exportación

Para habilitar la creación de trabajos de exportación asistida por IA, reinicia ogma-mcp con permisos de exportación:

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

O establece la variable de entorno:

OGMA_MCP_ALLOW_EXPORT_DATA=true ./ogma-mcp

Herramientas de exportación disponibles

Herramienta	Permiso requerido	Descripción
ogma_preview_export_plan	Ninguno (solo lectura)	Muestra una vista previa de lo que incluiría una exportación
ogma_list_export_jobs	Ninguno (solo lectura)	Lista los trabajos de exportación recientes
ogma_get_export_job	Ninguno (solo lectura)	Comprueba el estado de un trabajo de exportación
ogma_get_export_download_info	Ninguno (solo lectura)	Obtiene la URL de descarga de una exportación completada
ogma_create_export_job	export_data	Crea un trabajo de exportación

Tipos y formatos de exportación compatibles

Tipo	Descripción	Formatos
http_history	Todas las solicitudes HTTP que pasan por el proxy	json, csv, raw_http
search	Solicitudes HTTP filtradas	json, csv, raw_http
findings	Hallazgos de seguridad	json, csv
automate_results	Resultados de sesiones de Automatización	json, csv

Nota: el formato raw_http solo es válido para los tipos http_history y search.

Advertencia de seguridad

Los archivos de exportación pueden contener cuerpos completos de solicitudes y respuestas HTTP, que pueden incluir contraseñas, tokens y datos personales. Manipula los archivos de exportación con el cuidado adecuado.

Aún no disponible solo con permisos de exportación

• Eliminación de archivos de exportación
• Cambio de nombre de archivos de exportación
• Transmisión del contenido de exportación mediante MCP
• Envío desde Reenvío
• Ejecución de flujos de trabajo

Envío de solicitudes de Reenvío

Advertencia: esto habilita el envío de tráfico HTTP saliente real a través de Ogma Reenvío.

Para habilitarlo:

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

O mediante variables de entorno:

OGMA_MCP_ALLOW_SEND_REQUESTS=true ./ogma-mcp

Requisitos previos

1. El proxy de Ogma debe estar en ejecución
2. Debe configurarse un alcance activo en Alcances para los envíos de Reenvío protegidos
3. El host de destino debe estar dentro del alcance activo

Herramientas de envío

Herramienta	Permiso	Descripción
ogma_preview_replay_send	send_requests	Prepara un envío y obtiene un token de confirmación
ogma_send_replay_request	send_requests	Ejecuta el envío con un token de confirmación
ogma_create_replay_session_from_history	send_requests	Crea una sesión de Reenvío
ogma_create_replay_session_raw	send_requests	Crea una sesión de Reenvío a partir de una definición de solicitud sin procesar
ogma_browser_form_to_replay	send_requests	Crea una sesión de Reenvío a partir de un formulario de la página activa
ogma_create_scope_preset	send_requests	Guarda un ajuste de alcance; actívalo por separado con ogma_set_active_scope
ogma_repeat_request	send_requests	Repite una solicitud capturada con cambios opcionales
ogma_replay_with_modifications	send_requests	Reproduce una solicitud capturada con sustituciones a nivel de campo
ogma_http_request	send_requests	Envía una solicitud HTTP directa
ogma_fetch_url	send_requests	Obtiene una URL y devuelve el estado, las cabeceras y una vista previa
ogma_follow_redirect	send_requests	Sigue una cadena de redirecciones e informa de cada salto
ogma_bulk_send_requests	send_requests	Envía un lote limitado de solicitudes
ogma_fuzz_parameter	send_requests	Reemplaza un marcador con valores de una lista de palabras
ogma_multipart_upload	send_requests	Envía solicitudes multipart form-data para pruebas de carga de archivos
ogma_websocket_connect	send_requests	Se conecta a una URL WebSocket e intercambia mensajes
ogma_login_replay_auto	send_requests	Envía un formulario de inicio de sesión del navegador y captura un perfil de autenticación
ogma_auth_capture_profile	send_requests	Captura cookies, almacenamiento, tokens de autenticación y candidatos CSRF del navegador
ogma_auth_apply_profile	send_requests	Aplica un perfil de autenticación capturado al navegador
ogma_auth_refresh_csrf	send_requests	Actualiza los candidatos CSRF a partir del estado del navegador
ogma_authz_matrix_test	send_requests	Reproduce una solicitud con varios perfiles de autenticación
ogma_run_active_probe_workflow	send_requests	Ejecuta sondeos activos limitados y específicos de vulnerabilidades
ogma_test_race	send_requests	Envía una solicitud de forma concurrente e informa de las respuestas cuyo código de estado difiere del más frecuente
ogma_test_smuggling	send_requests	Envía sondeos de desincronización de solicitudes CL.TE y TE.CL mediante TCP sin procesar
ogma_test_hpp	send_requests	Envía variantes de contaminación de parámetros HTTP
ogma_run_nuclei	send_requests	Ejecuta una plantilla del escáner de plantillas, incluida o proporcionada, contra una URL de destino
ogma_browser_navigate y herramientas de interacción con el navegador	send_requests	Controlan el navegador integrado y capturan el tráfico resultante
ogma_crawl_site	send_requests	Rastrea un destino dentro del alcance mediante el navegador integrado
ogma_get_replay_session	Ninguno	Consulta los metadatos de una sesión de Reenvío
ogma_get_replay_attempt	Ninguno	Consulta los metadatos de un intento de Reenvío
ogma_list_replay_sessions	Ninguno	Lista las sesiones de Reenvío

Flujo de trabajo de dos pasos

El par de herramientas de Reenvío basado en confirmación utiliza dos llamadas:

1. ogma_preview_replay_send - revisa la solicitud y obtiene un token de confirmación
2. ogma_send_replay_request - confirma y envía con el token

Los tokens de confirmación caducan en 5 minutos, son de un solo uso y pertenecen a la sesión MCP que los creó. Genera otra vista previa tras cambiar la solicitud o reiniciar MCP. Esta regla de dos pasos no se aplica a todas las herramientas de envío: las herramientas HTTP directas, los asistentes de repetición y las acciones del navegador pueden enviar inmediatamente cuando están habilitados.

Sesión de ejemplo

Usuario: Reenvía la entrada HTTP abc123 y comprueba la respuesta
IA: (llama a ogma_preview_replay_send con http_entry_id="abc123")
    - muestra la vista previa de la solicitud, el token de confirmación y el estado del alcance --
IA: (llama a ogma_send_replay_request con confirmation_token y request_hash)
    - muestra el estado de respuesta, los tiempos y la vista previa de la respuesta --

Aún no disponible solo con permisos de envío de solicitudes

• Ejecución de flujos de trabajo
• Creación o actualización de hallazgos
• Eliminación

Mantén un alcance activo restringido antes de habilitar estas herramientas. Las comprobaciones de alcance se aplican a las rutas de envío protegidas; no consideres el alcance un cortafuegos universal para JavaScript arbitrario del navegador ni para todos los asistentes de obtención directa.

Control de interceptación

Advertencia: el control de interceptación permite a un cliente MCP reenviar, descartar o modificar tráfico en vivo retenido en la cola de interceptación de Ogma.

Para habilitarlo:

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

O mediante una variable de entorno:

OGMA_MCP_ALLOW_INTERCEPT_CONTROL=true ./ogma-mcp

Herramientas de interceptación

Herramienta	Permiso	Descripción
ogma_get_intercept_status	intercept_control	Lee el estado de interceptación de solicitudes, respuestas y WebSocket
ogma_set_intercept_enabled	intercept_control	Habilita o deshabilita los modos de interceptación
ogma_list_intercept_queue	intercept_control	Lista los elementos retenidos actualmente
ogma_get_intercept_item	intercept_control	Inspecciona un elemento de la cola
ogma_forward_intercept_item	intercept_control	Reenvía un elemento de la cola, modificado opcionalmente
ogma_drop_intercept_item	intercept_control	Descarta un elemento de la cola
ogma_intercept_and_modify	intercept_control	Espera un elemento coincidente, lo modifica y lo reenvía

Ejecución de flujos de trabajo

Advertencia: la ejecución de flujos de trabajo ejecuta su lógica. Algunos flujos envían tráfico HTTP o crean hallazgos.

Para habilitarla:

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

Herramientas de ejecución de flujos de trabajo

Herramienta	Permiso	Descripción
ogma_get_workflow_safety	Ninguno (solo lectura)	Clasifica los efectos secundarios de un flujo de trabajo
ogma_preview_workflow_run	run_workflows	Muestra una vista previa y obtiene un token de confirmación
ogma_run_workflow	run_workflows	Ejecuta con un token de confirmación
ogma_cancel_workflow_run	run_workflows	Cancela un flujo de trabajo activo en ejecución

Genera la vista previa con workflow_id, más input para un flujo de conversión o trigger_entry_id para una entrada capturada de un flujo activo. Ejecuta con el confirmation_token y el definition_hash devueltos; los flujos de conversión también necesitan input_hash y el mismo input. Los tokens caducan tras cinco minutos y son de un solo uso. Lee la ejecución resultante con ogma_get_workflow_run.

La ejecución de Automatización está disponible mediante sus herramientas de sesión y ejecución con permiso de envío de solicitudes, no con el permiso de ejecución de flujos de trabajo. Listar e inspeccionar ejecuciones existentes no requiere permiso de envío.

Requisitos entre permisos

Los flujos de trabajo que usan sdk.requests.send también requieren --allow-send-requests. Los flujos de trabajo que usan sdk.findings.create también requieren --allow-write-findings.

La detección se basa en análisis estático de texto; consulta la nota orientativa siguiente.

Nota orientativa sobre la clasificación de seguridad

La clasificación de seguridad de los flujos de trabajo inspecciona el texto del código fuente JavaScript en busca de patrones como sdk.requests.send. Esta detección no es exhaustiva: puede no detectar llamadas a métodos del SDK ofuscadas o construidas dinámicamente. Revisa siempre el código fuente JavaScript antes de ejecutar flujos de trabajo no confiables.

Aún no disponible solo con permisos de flujos de trabajo

• Activación manual de flujos de trabajo pasivos
• Eliminación
• Modificación de variables de entorno

Prompts de ejemplo

Una vez conectado:

• "Muéstrame las últimas 20 solicitudes HTTP a example.com"
• "¿Hay hallazgos de gravedad alta o crítica en este proyecto?"
• "¿Qué flujos de trabajo están habilitados actualmente?"
• "Comprueba si la consulta HTTPQL req.method.eq:\"POST\" es válida"
• "Resume el estado de seguridad del proyecto actual"
• "Analiza la entrada HTTP {id} en busca de problemas de seguridad"

Resolución de problemas

Conexión rechazada: inicia Ogma primero (ogma --data-dir ./ogma-data).

El cliente MCP no muestra herramientas: comprueba la URL de transporte o la ruta del ejecutable. Los clientes deben seguir todos los cursores de tools/list; cada página contiene hasta 40 herramientas. Comprueba el filtrado del cliente y si la versión instalada incluye la herramienta que falta.

Sesión o token de confirmación inválidos: vuelve a conectar tras un reinicio y genera un nuevo token de vista previa.

Navegador no disponible o acción fallida: mantén la aplicación de escritorio en ejecución. Comprueba ogma_browser_health, los diálogos y la recuperación del navegador. Un backend sin interfaz gráfica por sí solo no proporciona el puente del navegador de escritorio.

La captura de pantalla no tiene texto legible: usa un cliente compatible con contenido de imagen MCP nativo o inspecciona la instantánea semántica.

Resultados vacíos: Ogma necesita que primero se capture tráfico. Navega con el proxy configurado para reenviar el tráfico a través de Ogma.