> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindfort.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP (Model Context Protocol)

> Conecta un agente de IA a MindFort mediante MCP para gestionar objetivos autorizados, evaluaciones, hallazgos, cobertura, credenciales, analíticas e informes.

Para configurar MindFort con tu agente, usa el prompt copiable de [Inicio rápido para agentes](https://docs.mindfort.ai/es/agent-quickstart.md).

## Qué puedes hacer

Conecta Cursor, Claude Code, Codex u otro cliente MCP a MindFort y trabaja con el programa de seguridad de tu organización desde tu agente. El servidor MCP de MindFort expone un catálogo de herramientas explícito y limitado a la organización para:

* Explorar, crear, actualizar y eliminar objetivos autorizados
* Gestionar credenciales de prueba de solo escritura para aplicaciones web y API
* Revisar escenarios de cobertura, estados de ejecución y hallazgos vinculados
* Descubrir objetivos candidatos cuando Discovery está habilitado
* Iniciar, supervisar y cancelar evaluaciones
* Explorar, clasificar, comentar y volver a probar hallazgos
* Consultar métricas de seguridad, distribuciones, antigüedad, remediación y puntuaciones de salud
* Generar, consultar y descargar informes

Tu agente puede trabajar con los datos disponibles para tu cuenta de MindFort. Usa los ID de recursos que devuelve MindFort en lugar de adivinar identificadores.

## Casos de uso de MCP

| Caso de uso | Prompt de ejemplo |
| - | - |
| **Comprobar la postura actual** | `Show my current MindFort metrics, coverage gaps, and critical active findings.` |
| **Supervisar una evaluación** | `List my active assessments and show the stage progress for the newest one.` |
| **Investigar un hallazgo localmente** | `Pull this MindFort finding, inspect the relevant code, and explain the vulnerable path.` |
| **Generar un parche local** | `Use the evidence and remediation advice to patch this finding in my working tree.` |
| **Volver a probar tras el despliegue** | `Add a deployment note, start a retest, and poll the finding until it finishes.` |
| **Preparar un informe** | `Generate a condensed report for this target and give me the download URL when ready.` |
| **Configurar pruebas de API** | `Show the target metadata and credential types required for authenticated API testing.` |
| **Revisar brechas de cobertura** | `List incomplete coverage checks and summarize their latest run results.` |

## MCP frente a Patching en la plataforma

Usa **Patching** cuando quieras que MindFort genere un pull request directamente desde la plataforma.

Usa **MCP** cuando quieras que tu agente de IA local combine la evidencia de MindFort con tu copia local del repositorio, tu sistema de compilación y tus convenciones de ingeniería.

## Instalación

### Cursor

[![Instalar en Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=MindFort\&config=eyJ1cmwiOiJodHRwczovL2FwaS5taW5kZm9ydC5hcHAvbWNwIiwidHJhbnNwb3J0IjoiaHR0cCJ9)

O añade el servidor a `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "MindFort": {
      "url": "https://api.mindfort.app/mcp",
      "transport": "http"
    }
  }
}
```

### Claude Code

```bash theme={null}
claude mcp add --transport http MindFort https://api.mindfort.app/mcp
```

Después ejecuta `/mcp` dentro de Claude Code para iniciar sesión.

O añade el servidor a `.mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "MindFort": {
      "type": "http",
      "url": "https://api.mindfort.app/mcp"
    }
  }
}
```

### Codex

```bash theme={null}
codex mcp add MindFort --url https://api.mindfort.app/mcp
```

O añade el servidor a `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.MindFort]
url = "https://api.mindfort.app/mcp"
```

### Otros clientes MCP

Usa el endpoint Streamable HTTP:

```text theme={null}
https://api.mindfort.app/mcp
```

MindFort usa Streamable HTTP sin estado: los clientes envían solicitudes MCP con `POST /mcp`. No se admiten el transporte heredado HTTP+SSE ni los antiguos métodos de flujo `GET /mcp` y de sesión `DELETE /mcp`.

## Inicio de sesión y autorización

MindFort MCP usa OAuth basado en el navegador con tu cuenta de MindFort existente. No necesitas una clave de API.

1. Añade el servidor MCP de MindFort.
2. Completa el inicio de sesión en el navegador cuando tu cliente te lo solicite.
3. Selecciona la organización de MindFort que corresponda.
4. Pide al agente que llame a `get_current_context` y confirma la organización, el rol y las capacidades habilitadas.

El acceso MCP requiere una membresía activa en la organización y los permisos y funciones aplicables. Si tu membresía o tus permisos cambian, vuelve a conectarte y confirma tu acceso con `get_current_context`.

> [!NOTE]
>
> El catálogo depende del rol del miembro y de las funciones de la organización. Los miembros cuyo único rol es auditor tienen acceso de solo lectura a las operaciones permitidas. Las herramientas y variantes de credenciales sujetas a funciones solo aparecen cuando la organización tiene habilitada la función correspondiente. MindFort no expone mediante MCP la administración de facturación, la administración de claves de API, la membresía de la organización ni la administración de roles.

## Empieza por el contexto

Para ayudar a tu agente a usar el contexto y los ID de recursos correctos, sigue esta secuencia:

1. Llama a `get_current_context` para confirmar la organización seleccionada y las capacidades disponibles.
2. Llama a `list_targets` y luego a `get_target` antes de realizar trabajo específico de un objetivo.
3. Reutiliza los ID de objetivos, credenciales, evaluaciones, hallazgos, comprobaciones de cobertura e informes que devuelve MindFort.
4. Revisa las advertencias de las herramientas antes de iniciar pruebas activas o realizar acciones destructivas.
5. Consulta periódicamente las operaciones asíncronas con su herramienta de lectura correspondiente.

El servidor también expone el recurso fijo `mindfort://guides/start-here`. Los clientes MCP que admiten recursos pueden descubrirlo y leerlo para obtener la secuencia operativa resumida. Para conocer la semántica en detalle, usa esta documentación y el [índice de documentación legible por agentes](https://docs.mindfort.ai/llms.txt).

## Capacidades y funciones habilitadas

El catálogo de herramientas es explícito y puede variar según la organización.

| Área | Flujo de trabajo típico |
| - | - |
| **Targets** | `list_targets` -> `get_target` -> crear, actualizar o eliminar con confirmación |
| **Credentials** | Listar metadatos seguros; crear, rotar o eliminar credenciales de prueba de solo escritura |
| **Coverage** | Consultar escenarios actuales, resúmenes de ejecución y hallazgos vinculados |
| **Discovery** | Configurar Discovery, ejecutarlo y revisar objetivos candidatos cuando está habilitado |
| **Assessments** | `run_assessment` -> consultar `get_assessment` -> inspeccionar hallazgos |
| **Findings** | Listar/obtener, actualizar el ciclo de vida, comentar, anular la severidad, volver a probar e inspeccionar resúmenes de parches |
| **Analytics** | Consultar recuentos, distribuciones, salud, historial, series temporales, remediación, SLA y antigüedad |
| **Reports** | `create_report` -> consultar `get_report` -> `download_report` |

### Catálogo completo de herramientas

El catálogo base y el sujeto a funciones contienen las siguientes herramientas. Llama primero a `get_current_context`, ya que las herramientas sujetas a funciones pueden no estar disponibles para la organización seleccionada.

| Área | Herramientas |
| - | - |
| **Context** | `get_current_context` |
| **Targets** | `list_targets`, `get_target`, `create_target`, `update_target`, `delete_target` |
| **Credentials** | `list_target_credentials`, `create_target_credential`, `update_target_credential`, `delete_target_credential`, `generate_target_email_credential`, `check_email_mfa`, `get_authenticator_2fa_code`, `get_sms_credentials_access`, `list_sms_credential_countries`, `check_sms_code` |
| **Coverage** | `list_coverage_checks`, `get_coverage_overview` |
| **Discovery** | `get_discovery_status`, `update_discovery_schedule`, `update_discovery_context`, `start_discovery_run`, `cancel_discovery_run`, `list_discovery_suggestions`, `accept_discovery_suggestion`, `dismiss_discovery_suggestion` |
| **Assessments** | `list_assessments`, `get_assessment`, `run_assessment`, `cancel_assessment` |
| **Assessment schedules** | `list_assessment_schedules`, `get_assessment_schedule`, `create_assessment_schedule`, `update_assessment_schedule`, `delete_assessment_schedule`, `trigger_assessment_schedule`, `pause_assessment_schedule`, `resume_assessment_schedule` |
| **Findings** | `list_findings`, `get_finding`, `update_finding_status`, `update_finding_statuses`, `update_finding_severity`, `retest_finding`, `add_finding_comment`, `list_finding_comments`, `edit_finding_comment`, `delete_finding_comment`, `list_finding_patches`, `get_patch_count` |
| **Analytics** | `get_finding_counts`, `get_severity_distribution`, `get_target_health_score`, `get_category_distribution`, `get_severity_score_history`, `get_current_security_metrics`, `get_security_metrics_timeseries`, `get_remediation_metrics`, `get_sla_metrics`, `get_finding_aging` |
| **Reports** | `create_report`, `list_reports`, `get_report`, `download_report` |

Las capacidades sujetas a funciones incluyen:

* `discovery`: estado, contexto, programaciones, ejecuciones y sugerencias de Discovery
* `network-targets`: creación de objetivos de red y entradas de evaluación
* `sms-credentials`: variantes de credenciales SMS, metadatos de aprovisionamiento y comprobación de códigos
* `finding-severity-overrides`: establecer anulaciones de severidad; eliminar una anulación existente sigue estando disponible

Si cambian las funciones o permisos disponibles, vuelve a conectarte o inicia un chat nuevo para actualizar las herramientas disponibles para tu agente.

## Objetivos y credenciales

Los objetivos de aplicaciones web y API requieren un `web_domain` HTTP(S). Los objetivos de red requieren una `ip_address` y solo están disponibles cuando están habilitados para la organización. Los objetivos creados mediante REST o MCP empiezan sin verificar; completa la verificación de propiedad o de red en el panel de MindFort antes de realizar pruebas activas.

Las lecturas de listas y detalles de credenciales solo devuelven metadatos; no devuelven contraseñas, valores de claves de API ni semillas TOTP. Las herramientas auxiliares de autenticación dedicadas pueden devolver un código temporal o una URL de inicio de sesión, y el aprovisionamiento de correo electrónico devuelve un ID de bandeja de entrada pendiente para crear la credencial.

Para los objetivos de API, las credenciales `api_key` requieren unas `api_auth_instructions` no vacías a nivel de objetivo que expliquen:

* La ruta de validación y el método HTTP
* La estructura de solicitud requerida
* Dónde se coloca la clave, por ejemplo, un token bearer, un encabezado, un parámetro de consulta o un campo JSON
* La respuesta correcta esperada

Los secretos son de solo escritura. Rota un secreto mediante la herramienta de actualización en lugar de esperar poder leerlo de nuevo.

## Evaluaciones y progreso por etapas

Iniciar una evaluación da comienzo a pruebas de seguridad activas y puede consumir capacidad del plan. Usa solo un objetivo que el usuario tenga intención de probar.

Usa `stage_progress` en la respuesta de `get_assessment` para seguir las etapas de la evaluación:

* `NOT_STARTED` significa que no se ha registrado ningún estado.
* `RUNNING` o `ACTIVE` significa que hay trabajo en curso.
* Los demás valores son resultados finales de la etapa.
* Las etapas de pruebas activas pueden incluir campos de estado, intento y tiempos.

Los campos de nivel superior `created_at`, `updated_at`, `started_at` y `completed_at` describen la ejecución completa. Las ejecuciones fallidas pueden incluir un `failure_reason` que explica el problema. `cancel_assessment` solo acepta el ID de la evaluación. Registra cualquier contexto de la cancelación en tu propio flujo de trabajo.

## Hallazgos y nuevas pruebas

La herramienta `list_findings` acepta los mismos filtros que `GET /v1/findings`.

| Argumento | Valor predeterminado | Descripción |
| - | - | - |
| `target_id` | — | Limitar a un objetivo |
| `assessment_id` | — | Limitar a una ejecución de evaluación |
| `status` | `ACTIVE` | `ACTIVE`, `RESOLVED` o `ARCHIVED` |
| `exclude_secured` | `false` | Omitir las sondas informativas seguras cuando es `true` |
| `severity` | — | `critical`, `high`, `medium`, `low` o `secured` |
| `sort_by` | `severity` | `severity` o `created_at` |
| `limit` | Específico de la herramienta | Tamaño de página limitado |
| `cursor` | — | Cursor de continuación opaco del resultado anterior |

Usa `total` para obtener el recuento completo de coincidencias en lugar de la longitud de la primera página. Para que coincida con la pestaña Open del panel, usa `status=ACTIVE` y `exclude_secured=true`.

Las nuevas pruebas son asíncronas y se pueden iniciar para hallazgos `ACTIVE`, `RESOLVED` o `ARCHIVED`. Consulta `get_finding` periódicamente:

* `QUEUED` o `RUNNING`: la ejecución sigue activa.
* `FAILED`: `retest_failure_reason` explica por qué no se pudo completar la ejecución.
* `COMPLETED`: la validación terminó y se aplicó el resultado. Un resultado que indica que el problema está corregido en las condiciones probadas establece el hallazgo en `RESOLVED`; un resultado que indica que sigue siendo reproducible lo establece en `ACTIVE`.

Consulta la [API de hallazgos](https://docs.mindfort.ai/es/api-reference/findings) para ver ejemplos de REST y detalles de los campos.

## Paginación

Las herramientas de listado de MCP usan cursores opacos en lugar de desplazamientos (offsets) de REST. Cuando un resultado incluye `next_cursor`, devuélvelo sin cambios con los mismos filtros. Los cursores están vinculados a la operación y al conjunto de filtros, por lo que cambiar los filtros requiere iniciar una nueva secuencia de paginación.

`tools/list` devuelve el catálogo autorizado completo y no está paginado.

## Errores y acciones sensibles

Los fallos de las herramientas incluyen un código de error estable, un mensaje seguro, indicaciones de reintento cuando corresponde y un ID de solicitud para que el soporte pueda correlacionarlo. Los errores de validación también pueden incluir detalles a nivel de campo.

Si la conexión devuelve HTTP `429 Too Many Requests`, espera el intervalo indicado en `Retry-After` antes de reintentar y reduce la frecuencia de consulta.

Entre los códigos accionables habituales se incluyen:

* `target_not_verified`
* `api_auth_instructions_required`
* `assessment_already_running`
* `assessment_credits_insufficient`
* `assessment_queue_loading`
* `retest_already_running`

Las herramientas destructivas muestran advertencias destacadas y anotaciones destructivas de MCP. Invocar la herramienta realiza la acción tras la validación normal; MindFort no añade un segundo paso de aprobación. Revisa los nombres de los objetivos, los ID de recursos y las advertencias antes de eliminar, cancelar, archivar o realizar pruebas activas.

## Solución de problemas

> [accordion] El agente no puede conectarse
>
> Confirma que la URL sea exactamente `https://api.mindfort.app/mcp`, que tu red permita HTTPS y que tu cliente admita Streamable HTTP. Reinicia el cliente y vuelve a intentarlo.

> [accordion] El inicio de sesión no se completa
>
> Elimina la conexión MCP y vuelve a añadirla. En Claude Code, ejecuta `/mcp`, selecciona MindFort y vuelve a autenticarte. Si el problema continúa, contacta con [support@mindfort.ai](mailto:support@mindfort.ai).

> [accordion] Faltan herramientas esperadas
>
> Llama a `get_current_context` para confirmar la organización seleccionada y sus indicadores de funciones públicos. Después, vuelve a conectarte o inicia un chat nuevo para que el cliente actualice el descubrimiento de herramientas.

> [accordion] El hallazgo desaparece tras resolverlo
>
> Es lo esperado cuando `list_findings` usa el valor predeterminado `status=ACTIVE`. Pasa `status=RESOLVED` o `status=ARCHIVED` para explorar esos estados del ciclo de vida.

> [accordion] El recuento de la API o de MCP difiere del panel
>
> La pestaña Open del panel oculta de forma predeterminada las sondas informativas seguras. Pasa `exclude_secured=true` y `status=ACTIVE` para que coincida. Usa `assessment_id` cuando compares una sola evaluación.

> [accordion] Se rechaza un cursor
>
> Devuelve `next_cursor` sin cambios con la misma herramienta y los mismos filtros. Empieza de nuevo sin cursor después de cambiar los filtros.

## Cobertura y Discovery

Usa `list_coverage_checks` para escenarios individuales y `get_coverage_overview` para recuentos agregados. Mantén separados `covered`, `failing`, `incomplete`, `in_progress` y `not_run` al resumir los resultados. La cobertura es de solo lectura; no hay herramientas para crear, editar ni volver a ejecutar una comprobación.

[Discovery](https://docs.mindfort.ai/es/guides/discovery.md) propone objetivos candidatos. Aceptar una sugerencia crea un objetivo; revisa su estado de verificación antes de iniciar las pruebas. Las herramientas de Discovery solo aparecen cuando la función está habilitada.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.