Model Context Protocol (MCP) - Corgea Documentation

Corgea es compatible con Model Context Protocol (MCP), lo que permite que asistentes de IA como Claude interactúen directamente con tus escaneos, hallazgos y políticas de seguridad. MCP permite a los modelos de IA comprender el contexto de seguridad y ofrecer una asistencia más pertinente.

¿Qué es MCP?

Model Context Protocol es un estándar abierto que permite a los modelos de IA conectarse de forma segura a herramientas y fuentes de datos externas. Con la integración MCP de Corgea, los asistentes de IA pueden:

Consultar los resultados de tus escaneos de seguridad
Recuperar detalles de vulnerabilidades
Enumerar y filtrar hallazgos de seguridad
Enumerar y filtrar hallazgos de calidad del código
Accede a datos de SCA, IaC e inventario de dependencias
Exporta el inventario de dependencias como CSV
Revisa las normas y políticas de bloqueo

Primeros pasos

Instala Corgea MCP con corgea mcp install (CLI 1.13.0 o posterior). Tras corgea login, la CLI escribe la URL del servidor y el token en la configuración del agente. Esa página cubre npx, los agentes compatibles, --scope, --dir y --set-default. Reinicia el agente después de instalarlo. Prefiere el instalador a editar la configuración a mano. El resto de esta página describe la URL del servidor, las herramientas disponibles y la configuración manual del cliente.

Requisitos previos

Una cuenta de Corgea. corgea login proporciona el token que escribe el instalador.
Un cliente compatible con MCP (por ejemplo, Claude Desktop, Cursor, Continue o cualquier cliente MCP)
Solo para la configuración manual: un token de la API de Corgea, disponible en Settings → Automation → API token

Detalles de la conexión

URL del servidor MCP:

https://www.corgea.app/mcp

En despliegues de un único tenant:

https://<your-instance>.corgea.app/mcp

Autenticación: Todas las solicitudes MCP deben autenticarse mediante el token de API de Corgea incluido en la cabecera CORGEA-TOKEN.

Corgea admite solicitudes MCP sin estado mediante POST con respuestas JSON. No admite streams independientes de eventos enviados por el servidor (SSE).

Herramientas disponibles

El servidor MCP de Corgea proporciona las siguientes herramientas para asistentes de IA:

get_scan_info

Obtén información detallada sobre un escaneo SAST concreto. Parámetros:

scan_id (cadena, obligatorio): Identificador único del escaneo

Devuelve: Información detallada del escaneo que incluye el estado, el recuento de hallazgos, la fecha del escaneo y la información del repositorio. Ejemplo:

{
  "scan_id": "abc123",
  "status": "completed",
  "created_at": "2024-11-01T10:30:00Z",
  "findings_count": 15,
  "project": "my-project",
  "repository": "https://github.com/myorg/myrepo"
}

get_issue_info

Obtén información detallada sobre un hallazgo de seguridad concreto. Parámetros:

issue_id (cadena, obligatorio): Identificador único del hallazgo
include_reachability (booleano, opcional): Incluye detalles sobre la alcanzabilidad del endpoint para el hallazgo

Regresa: Detalles completos del hallazgo, incluidos el tipo de vulnerabilidad, la gravedad, la ubicación, las recomendaciones de corrección, el estado de remediación y, opcionalmente, la accesibilidad de los endpoints. Ejemplo:

{
  "issue_id": "issue-456",
  "title": "SQL Injection",
  "severity": "high",
  "file": "src/database.py",
  "line": 42,
  "description": "User input not properly sanitized",
  "fix_available": true
}

get_sca_issue_info

Obtén información detallada sobre un hallazgo concreto del análisis de composición de software (SCA). Parámetros:

issue_id (cadena, obligatorio): Identificador único del hallazgo de SCA

Regresa: Detalles del hallazgo de SCA, como el paquete, la gravedad, el CVE, la versión corregida, la ubicación del archivo y el análisis de alcanzabilidad de las dependencias. Ejemplo:

{
  "status": "ok",
  "issue": {
    "id": "sca-789",
    "package": {
      "name": "lodash",
      "version": "4.17.15",
      "ecosystem": "npm",
      "fix_version": "4.17.21"
    },
    "cve": "CVE-2021-23337",
    "severity": "high",
    "reachability": {
      "status": "vulnerable_usage_reachable",
      "description": "Vulnerable function is reachable from application code",
      "usages": []
    }
  }
}

list_security_issues

Enumera hallazgos de seguridad y permite filtrarlos. Parámetros:

scan_id (cadena, opcional): Filtra los hallazgos por ID de escaneo
project (cadena, opcional): Filtra los hallazgos por nombre de proyecto
repo (cadena, opcional): Filtra los hallazgos por URL del repositorio
include_reachability (booleano, opcional): Incluye un resumen de alcanzabilidad de endpoints para cada hallazgo

Regresa: Lista de hallazgos de seguridad que coinciden con los filtros indicados. Ejemplo:

{
  "status": "ok",
  "count": 25,
  "issues": [
    {
      "id": "issue-123",
      "title": "Cross-Site Scripting (XSS)",
      "severity": "medium",
      "status": "open"
    }
  ]
}

list_code_quality_issues

Enumera los hallazgos de calidad del código por separado de los de seguridad y permite filtrarlos. Parámetros:

scan_id (cadena, opcional): Problemas de filtro por ID de escaneo
project (cadena, opcional): Problemas de filtro por nombre del proyecto
repo (cadena, opcional): Problemas de filtrado por URL del repositorio
filters (objeto, opcional): Filtrar por urgency, status, language, file_path, classification, sla_status, branch, show_false_positives, o sort_by
page (entero, opcional): Número de página
page_size (entero, opcional): Número de resultados por página, hasta 50

El campo classification contiene la etiqueta de calidad del código, como Maintainability, en lugar de un CWE. Los falsos positivos se excluyen de forma predeterminada. Regresa: Solo hallazgos de calidad del código que coinciden con el ámbito y los filtros indicados.

list_sca_security_issues

Enumera hallazgos de seguridad de Software Composition Analysis (SCA) y permite filtrarlos. Parámetros:

scan_id (cadena, opcional): Problemas de filtro por ID de escaneo
project (cadena, opcional): Problemas de filtro por nombre del proyecto
repo (cadena, opcional): Problemas de filtrado por URL del repositorio
filters (objeto, opcional): Filtrar por campos como severity, package, ecosystem, cve, path, has_fix, branch, reachability, o sort_by
include_reachability (booleano, opcional): Incluye el estado de alcanzabilidad de la dependencia y la descripción de cada hallazgo de SCA

Los valores admitidos para el filtro reachability son not_direct_dependency, pending, vulnerable_usage_reachable, vulnerable_usage_unreachable y dead_dependency. Regresa: Lista de hallazgos de SCA, incluidas las dependencias vulnerables, los CVE y la información de versiones. Ejemplo:

{
  "status": "ok",
  "count": 12,
  "sca_issues": [
    {
      "id": "sca-789",
      "package": "lodash",
      "current_version": "4.17.15",
      "fixed_version": "4.17.21",
      "cve": "CVE-2021-23337",
      "severity": "high"
    }
  ]
}

list_iac_security_issues

Lista los hallazgos de seguridad de infraestructura como código (IaC) con filtros opcionales. Parámetros:

scan_id (cadena, opcional): Problemas de filtro por ID de escaneo
project (cadena, opcional): Problemas de filtro por nombre del proyecto
repo (cadena, opcional): Problemas de filtrado por URL del repositorio
filters (objeto, opcional): Filtrar por severity, provider, service, iac_type, rule_id, avd_id, path, search, sort_by, o branch
page (entero, opcional): Número de página
page_size (entero, opcional): Número de resultados por página, hasta 50

Regresa: Lista de hallazgos de IaC con su gravedad, servicio afectado, identificadores de reglas, ubicación del archivo y contexto del escaneo. Ejemplo:

{
  "status": "ok",
  "page": 1,
  "total_pages": 1,
  "total_issues": 1,
  "issues": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "title": "Public S3 bucket",
      "severity": "HIGH",
      "provider": "aws",
      "service": "s3",
      "iac_type": "terraform",
      "location": {
        "path": "infra/main.tf",
        "start_line": 10
      }
    }
  ]
}

list_dependencies

Lista las dependencias de software descubiertas durante un escaneo con filtrado opcional. Parámetros:

scan_id (cadena, opcional): Filtrar dependencias por ID de escaneo
project (cadena, opcional): Filtrar dependencias por nombre del proyecto
repo (cadena, opcional): Filtrar dependencias por URL del repositorio
filters (objeto, opcional): Filtrar por name, version, type, path, purl, license, dep_type, search, sort_by, o branch
page (entero, opcional): Número de página
page_size (entero, opcional): Número de resultados por página, hasta 50

Regresa: Lista de dependencias que incluye nombre del paquete, versión, URL del paquete, datos de licencia, relación de dependencia y contexto de escaneo. Ejemplo:

{
  "status": "ok",
  "page": 1,
  "total_pages": 1,
  "total_dependencies": 1,
  "dependencies": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "django",
      "version": "4.2.0",
      "type": "pypi",
      "purl": "pkg:pypi/django@4.2.0",
      "path": "requirements.txt",
      "licenses": ["BSD-3-Clause"],
      "is_direct": true
    }
  ]
}

export_dependencies_csv

Genera un enlace para descargar los hallazgos de dependencias de un proyecto como archivo CSV. Parámetros:

project (cadena, obligatorio): Nombre o ID del proyecto
scan_id (cadena, opcional): Exporta un escaneo concreto; por defecto, el más reciente
branch (cadena, opcional): Filtra las dependencias por nombre de rama
ecosystem (cadena, opcional): Filtra por ecosistema, como pypi, npm o maven
severity (cadena, opcional): Filtra por severidad — critical, high, medium o low
reachability (cadena, opcional): Filtra por alcanzabilidad — reachable, unreachable, unused o analyzing
dependency_type (cadena, opcional): Filtra por relación de dependencia — direct, transitive, dev u optional
search (cadena, opcional): Filtra por nombre de paquete

Devuelve: Una download_url para entregar al usuario, no las filas del CSV. Usa list_dependencies cuando el asistente necesite los datos para razonar sobre ellos. El enlace resuelve la misma exportación que el icono de descarga de la pestaña Dependencies, por lo que requiere el permiso View SCA Issue y produce las columnas descritas en Exportación de hallazgos. Ejemplo:

{
  "download_url": "https://www.corgea.app/project/my-project/sca-findings/export/?urgency=critical",
  "message": "CSV export URL generated for project 'my-project'. Share this link with the user to download the file."
}

list_scans

Lista todos los escaneos SAST con filtrado opcional. Parámetros:

project (cadena, opcional): Escanea el filtro por nombre del proyecto
repo (cadena, opcional): Filtrar escaneos por subcadena de URL del repositorio
branch (cadena, opcional): Escanea el filtro por nombre exacto de la rama
pull_request_id (cadena, opcional): Escanea el filtro por identificador exacto de pull request o de fusión
sha (cadena, opcional): Filtrar escaneos por SHA de commit exacto
metadata_key (cadena, opcional): Filtrar escaneos que contengan esta clave de metadatos; combínala con metadata_value para coincidir con una clave y un valor exactos
metadata_value (cadena, opcional): Coincidir con un valor exacto de metadata_key, o buscar en los metadatos del escaneo cuando se usa sola

Regresa: Lista de escaneos con información básica que incluye ID, fecha, estado y recuento de resultados. Ejemplo:

{
  "status": "ok",
  "count": 50,
  "scans": [
    {
      "id": "scan-001",
      "project": "web-app",
      "created_at": "2024-11-01T09:00:00Z",
      "status": "completed",
      "findings": 8
    }
  ]
}

get_blocking_rules

Configura todas las reglas de bloqueo para tu organización. Parámetros: Ninguno Regresa: Lista de reglas de bloqueo que impiden despliegues basados en políticas de seguridad. Ejemplo:

{
  "status": "ok",
  "rules": [
    {
      "id": "rule-1",
      "name": "Block Critical Vulnerabilities",
      "condition": "severity >= critical",
      "action": "block",
      "enabled": true
    }
  ]
}

Configuración de clientes MCP

Usa las secciones siguientes solo si prefieres editar la configuración de un agente a mano. En la mayoría de los agentes, corgea mcp install escribe la misma configuración por ti.

Claude Desktop

Añade Corgea a la configuración de Claude Desktop:

Abre la configuración de Claude Desktop
Navega a la sección “Desarrollador”
Edita tu archivo de configuración MCP
Añade el servidor MCP de Corgea:

{
  "mcpServers": {
    "corgea": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.corgea.app/mcp",
        "--header",
        "CORGEA-TOKEN:${CORGEA_TOKEN}"
      ],
      "env": {
        "CORGEA_TOKEN": "your_api_token_here"
      }
    }
  }
}

Claude Desktop no sustituye variables en este archivo. ${CORGEA_TOKEN} lo resuelve mcp-remote, que lo lee del entorno que le proporciona el bloque env, así que el token debe escribirse ahí. Omita el espacio después de CORGEA-TOKEN:: en Windows, Claude Desktop no escapa los espacios dentro de args y la cabecera llega corrupta.

Reinicia Claude Desktop para que los cambios entren en vigor

Cursor IDE

Añade Corgea a tu configuración de Cursor MCP:

Abre la configuración de Cursor (Cmd/Ctrl + Shift + J)
Ve a “Configuración de Cursor” → “Modelos” → “MCP”
O edita directamente tu archivo de configuración MCP en:
- macOS/Linux: ~/.cursor/mcp.json
- Windows: %APPDATA%\Cursor\User\mcp.json
Añade el servidor MCP de Corgea:

{
  "mcpServers": {
    "corgea": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.corgea.app/mcp",
        "--transport",
        "http-only",
        "--header",
        "CORGEA-TOKEN:${env:CORGEA_TOKEN}"
      ]
    }
  }
}

Cursor resuelve ${env:NAME} por sí mismo, así que el token puede vivir en su entorno en lugar de en el archivo. Esta forma es propia de Cursor: en Claude Desktop, ${env:CORGEA_TOKEN} no se resuelve y la cabecera se envía vacía. Igual que antes, omita el espacio después de CORGEA-TOKEN:.

Cursor lee la variable de su propio entorno de proceso. export CORGEA_TOKEN=... en una terminal solo afecta a esa shell y a sus procesos hijos, así que un Cursor iniciado desde el Dock, el menú Inicio o un lanzador de escritorio nunca la ve y la cabecera se envía vacía. Defínala donde la sesión de escritorio pueda encontrarla y reinicie Cursor:

macOS: launchctl setenv CORGEA_TOKEN <valor>, válido hasta que reinicie el equipo.
Windows: setx CORGEA_TOKEN <valor>, que persiste para su cuenta de usuario.
Linux: añada CORGEA_TOKEN=<valor> a ~/.config/environment.d/corgea.conf y vuelva a iniciar sesión.

Iniciar Cursor desde una shell que ya tenga la variable exportada funciona en cualquier sistema y es la forma más rápida de confirmar que esta es la causa. Una cabecera CORGEA-TOKEN vacía y un 401 son el síntoma.

El puente mcp-remote es obligatorio aquí, no una comodidad. El transporte "url" integrado de Cursor se conecta y después abre un flujo de server-sent events que este servidor no admite, por lo que la conexión falla con Failed to open SSE stream: Not Acceptable y no aparece ninguna herramienta.

Configuración alternativa (HTTP directo): Para un cliente que envía JSON directamente y no abre un flujo SSE independiente:

{
  "mcpServers": {
    "corgea": {
      "url": "https://www.corgea.app/mcp",
      "headers": {
        "CORGEA-TOKEN": "your_api_token_here"
      }
    }
  }
}

No todos los clientes que anuncian transporte HTTP cumplen esto. Cursor es uno que no: allí use la configuración con mcp-remote de arriba. Un 406 o Not Acceptable al conectar significa que el cliente intenta abrir el flujo SSE.

Extensión Continue para IDE

Continue lee archivos de bloque MCP independientes en .continue/mcpServers/, no una entrada contextProviders en config.json. Añade Corgea como ~/.continue/mcpServers/corgea.yaml (ámbito de usuario) o .continue/mcpServers/corgea.yaml en el espacio de trabajo (ámbito de proyecto):

name: Corgea MCP
version: 0.0.1
schema: v1
mcpServers:
  - name: corgea
    type: streamable-http
    url: https://www.corgea.app/mcp
    requestOptions:
      headers:
        CORGEA-TOKEN: your_api_token_here

El esquema de configuración de Continue descarta las claves desconocidas. Las cabeceras HTTP van en requestOptions: un mapa headers de primer nivel se descarta en silencio.

Casos de uso

Revisión de Código Consciente de la Seguridad

Conecta tu asistente de IA con Corgea y haz preguntas como:

“¿Cuáles son los hallazgos críticos de seguridad de mi último escaneo?”
“Muéstrame todas las vulnerabilidades de inyección SQL en el módulo de autenticación”
“¿Hay algún hallazgo de SCA de gravedad alta en mis dependencias?”

Análisis de vulnerabilidades

Deja que la IA te ayude a entender y priorizar vulnerabilidades:

“Explica el hallazgo de seguridad issue-456 y sugiere cómo corregirlo”
“¿Qué vulnerabilidades debería corregir primero según la gravedad y la explotabilidad?”
“¿Cuáles son las reglas de bloqueo que impedirían este despliegue?”

Planificación automatizada de remediación

Utiliza IA para planificar soluciones de seguridad:

“Crea un plan de remediación para todos los hallazgos de gravedad alta del escaneo scan-123”
“¿Qué dependencias hay que actualizar para corregir los hallazgos de SCA?”
“Genera un informe de todos los hallazgos de seguridad abiertos agrupados por archivo”

Mejores prácticas

Asegura tu token de API

Nunca incluyas el token de API en un commit
Rota los tokens periódicamente
Utiliza variables de entorno o gestores de secretos seguros
Revoca los tokens de inmediato si se ven comprometidos

Filtrar eficazmente

Utiliza filtros de proyecto, repositorio, rama y pull request para limitar los resultados
Empieza por escaneos concretos al depurar
Filtra por gravedad al priorizar el trabajo

Optimizar el rendimiento

Solicita solo los datos que necesitas
Utiliza ID concretos de hallazgo o escaneo cuando sea posible
Almacena los resultados en caché cuando corresponda
Respeta los límites de frecuencia

Autenticación

Todas las llamadas a herramientas MCP requieren un token válido de la API de Corgea en la cabecera CORGEA-TOKEN. Consiguiendo tu token:

Inicia sesión en tu cuenta de Corgea
Ve a Settings → Automation → API token
Generar un nuevo token de API
Copia el token y añádelo a la configuración de tu cliente MCP

Mantén tu token de API seguro. Cualquier persona con acceso a tu token puede consultar tus datos de seguridad a través de la interfaz MCP.Cuando el cliente pueda leer el token desde su entorno, prefiera esa opción a escribirlo en el archivo de configuración, y mantenga fuera del control de versiones cualquier archivo que lo contenga. No existe una sintaxis común: Cursor usa ${env:NAME}, Claude Code usa ${NAME} y Claude Desktop no tiene ninguna propia.

Formato de respuesta

Todas las respuestas de la herramienta MCP siguen el formato estándar de respuesta de la API de Corgea: Respuesta de éxito:

{
  "status": "ok",
  "data": { }
}

Respuesta de error:

{
  "status": "error",
  "message": "Description of the error",
  "error": "Detailed error information"
}

Límites de tasas

Las solicitudes MCP están sujetas a los mismos límites de velocidad que las solicitudes estándar de API:

100 solicitudes por minuto por token
1000 solicitudes por hora por token

Si superas los límites de tarifa, recibirás un 429 Too Many Requests respuesta.

Resolución de problemas

Problemas de conexión

Problema: No se puede conectar al servidor MCP Soluciones:

Verifica que el token de API sea válido mediante el endpoint /verify
Comprueba que el CORGEA-TOKEN el encabezado está correctamente configurado
Asegúrate de que tu red permita conexiones HTTPS corgea.app

Errores de autenticación

Problema: Recibiendo respuestas no autorizadas 401 Soluciones:

Verifica que tu token de API no haya caducado
Comprueba que el token se ha pasado en el CORGEA-TOKEN encabezado (no Autorización)
Asegúrate de que tu token tenga los permisos necesarios

Resultados vacíos

Problema: Las consultas no devolven datos Soluciones:

Verifica que existan datos en tu cuenta de Corgea
Comprueba que los parámetros del filtro (scan_id, proyecto, repositorio, rama, pull_request_id) sean correctos
Asegúrate de consultar el entorno correcto (multi-inquilino vs inquilino único)

Apoyo

Documentación de API

Descubre más sobre la API de Corgea

Únete a nuestra comunidad

Busca ayuda en la comunidad de Corgea

Guía de autenticación

Aprende sobre la autenticación por API

Especificación MCP

Lee la documentación oficial del MCP

Próximos pasos

Instala Corgea MCP con corgea mcp install
Reinicia el agente para que cargue el nuevo servidor
Prueba la conexión preguntando a tu asistente de IA sobre tus escaneos
Explora casos de uso como el análisis de seguridad y la remediación de vulnerabilidades

¡Empieza a integrar la inteligencia de seguridad de Corgea en tu flujo de trabajo de desarrollo impulsado por IA hoy mismo!

​¿Qué es MCP?

​Primeros pasos

​Requisitos previos

​Detalles de la conexión

​Herramientas disponibles

​get_scan_info

​get_issue_info

​get_sca_issue_info

​list_security_issues

​list_code_quality_issues

​list_sca_security_issues

​list_iac_security_issues

​list_dependencies

​export_dependencies_csv

​list_scans

​get_blocking_rules

​Configuración de clientes MCP

​Claude Desktop

​Cursor IDE

​Extensión Continue para IDE

​Casos de uso

​Revisión de Código Consciente de la Seguridad

​Análisis de vulnerabilidades

​Planificación automatizada de remediación

​Mejores prácticas

​Autenticación

​Formato de respuesta

​Límites de tasas

​Resolución de problemas

​Problemas de conexión

​Errores de autenticación

​Resultados vacíos

​Apoyo

Documentación de API

Únete a nuestra comunidad

Guía de autenticación

Especificación MCP

​Próximos pasos

¿Qué es MCP?

Primeros pasos

Requisitos previos

Detalles de la conexión

Herramientas disponibles

get_scan_info

get_issue_info

get_sca_issue_info

list_security_issues

list_code_quality_issues

list_sca_security_issues

list_iac_security_issues

list_dependencies

export_dependencies_csv

list_scans

get_blocking_rules

Configuración de clientes MCP

Claude Desktop

Cursor IDE

Extensión Continue para IDE

Casos de uso

Revisión de Código Consciente de la Seguridad

Análisis de vulnerabilidades

Planificación automatizada de remediación

Mejores prácticas

Autenticación

Formato de respuesta

Límites de tasas

Resolución de problemas

Problemas de conexión

Errores de autenticación

Resultados vacíos

Apoyo

Próximos pasos