Saltar a contenido

Protocolo de Contexto de Modelo (MCP) — Vulseek


Tabla de Contenidos


1. Visión General y Arquitectura

1.1 ¿Qué es el Protocolo de Contexto del Modelo?

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto que permite a los asistentes y agentes de inteligencia artificial interactuar de forma segura con herramientas y fuentes de datos. Vulseek implementa MCP para habilitar que herramientas basadas en IA — como OpenCode, Claude Code, y otras — consulten tus datos de vulnerabilidades, activos y hallazgos en tiempo real.

Con Vulseek MCP puedes:

  • Hacer preguntas como "¿Cuáles son las vulnerabilidades más críticas en mi entorno?"
  • Automatizar consultas de seguridad mediante asistentes de IA.
  • Integrar datos de Vulseek en tu flujo de trabajo de desarrollo sin salir de tu editor o terminal.

1.2 Arquitectura y Diseño

Vulseek MCP es un servidor MCP integrado que se ejecuta directamente dentro de la plataforma de API de Vulseek. No hay un servicio separado que desplegar o mantener. La arquitectura sigue estos principios:

Propiedad Valor
Protocolo Protocolo de Contexto del Modelo (MCP)
Servidor Integrado dentro de la aplicación de Vulseek
Punto de montaje /mcp
Transporte HTTP sin estado (stateless)
Diseño Solo lectura — solo se exponen endpoints GET

El servidor está diseñado con un transporte HTTP sin estado, lo que significa que cada solicitud es autocontenida y no depende de conexiones persistentes. Esto lo hace simple, confiable y compatible con una amplia gama de clientes de IA.

1.3 Diseñado Exclusivamente para Solo Lectura

La seguridad es un principio fundamental de diseño. Vulseek MCP es estrictamente de solo lectura. Solo se exponen endpoints GET a través del protocolo. Todos los métodos que modifican datos (POST, PUT, PATCH, DELETE) están explícitamente excluidos.

Esto garantiza que:

  • Un asistente de IA puede consultar tus datos pero no modificarlos.
  • La modificación accidental o maliciosa de hallazgos, activos o vulnerabilidades es imposible a través de MCP.
  • Al configurarlo con un token con permisos de sólo lectura se garantiza que el asistente o agente de IA no pueda realizar modificaciones no intencionadas en tu entorno por fuera del MCP.

1.4 Herramientas expuestas

Vulseek MCP expone más de 30 herramientas de lectura sobre tu espacio de trabajo que te permiten realizar diversas consultas sobre la siguiente información:

  • Activos
  • Propiedades de activos
  • Hallazgos
  • Propiedades de hallazgos
  • Vulnerabilidades
  • Propiedades de Vulnerabilidades

Recomendación: Cada una de las herramientas incluye filtros. Intenta especificar el mayor detalle posible en tus prompts de consultas para que el asistente de IA los utilice y evitar respuestas con mucho contenido.

2. Seguridad y Autenticación

⚠️ IMPORTANTE: La seguridad es la máxima prioridad al integrar asistentes de IA con datos de seguridad. Lee esta sección cuidadosamente antes de configurar cualquier cliente.

2.1 Principio de Mínimo Privilegio

Al conectar un asistente o agente de IA a Vulseek, sigue siempre el Principio de Mínimo Privilegio:

  • Nunca uses tu contraseña personal o token de sesión con permisos de escritura en asistentes de IA.
  • Nunca uses credenciales de administrador para acceso a la API.
  • Nunca compartas ni incrustes secretos directamente en archivos de configuración que puedan ser enviados al control de versiones.
  • Crea siempre un token de integración dedicado con los permisos mínimos necesarios (sólo lectura).

2.2 Mecanismo de Autenticación

Vulseek MCP autentica las solicitudes utilizando el encabezado HTTP X-API-Key. Cada solicitud al servidor MCP debe incluir este encabezado con un token de integración válido.

X-API-Key: <id_de_integración>@<secreto>

Remote URL

  • Si tu entorno está en producción usar:
https://api.vulseek.io/mcp
  • Si tu entorno está en stage usar:
https://stage.api.vulseek.io/mcp

2.3 Creación de un Token de Integración de Solo Lectura

Para crear un token de acceso para asistentes de IA, sigue estos pasos en la interfaz web de Vulseek:

  1. Navega a Integraciones → Listado.
  2. Haz clic en el botón "+" para crear la integración.
  3. Ingresa un nombre descriptivo claro (ej: "Asistente OpenCode - Solo Lectura").
  4. Selecciona el rol: "Veedor" (solo lectura). Este rol proporciona acceso estrictamente de solo lectura limitado al espacio de trabajo.
  5. Haz clic en Guardar.
  6. Copia y almacena el token de forma segura inmediatamente. El token se muestra solo una vez, con el formato <id_de_integración>@<secreto>. Si lo pierdes, debes crear una nueva integración.

2.5 Tokens Dedicados por Cliente

Genera siempre un token de integración único para cada herramienta o asistente de IA que utilices. Por ejemplo:

Asistente / Herramienta Nombre del Token
Asistente OpenCode "Asistente OpenCode - Solo Lectura"
Agente de Seguridad Claude Code "Agente de Seguridad Claude Code"
Script de automatización personalizado "Automatización - Informe Semanal"

Beneficios de los tokens dedicados:

  • Auditoría granular: Las marcas de tiempo last_login_at de cada token se registran de forma independiente.
  • Acceso aislado: Revocar un token no afecta a otras integraciones.
  • Revocación sencilla: Si un asistente específico se descontinúa o se ve comprometido, solo debes eliminar su token.

3. Configuración del Cliente

3.1 Configuración usando OpenCode

Requisitos

Paso 1: Crea el MCP

Crea o edita ~/.opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vulseek": {
      "type": "remote",
      "url": "https://api.vulseek.io/mcp",
      "enabled": true,
      "headers": {
        "X-API-Key": "<id_de_integración>@<secreto>"
      }
    }
  }
}

Paso 2: Verifica que el servidor MCP esté bien configurado

Ejecuta el siguiente comando en tu terminal:

opencode mcp ls

El output del comando debería ser similar al siguiente:

●  ✓ vulseek connected
│      https://api.vulseek.io/mcp

3.2 Configuración usando Claude Code

Requisitos

  • Claude Code instalado en el equipo.
  • Subscripción activa de Anthropic.

Paso 1: Establece la API Key a través de variable de ambiente

Crea o edita el archivo ~/.claude/settings.json con el siguiente contenido:

{
  "env": {
    "VULSEEK_API_KEY": "<id_de_integración>@<secreto>"
  }
}

Paso 2: Crea el MCP

claude mcp add --scope user --transport http vulseek \
  https://api.vulseek.io/mcp \
  --header "X-API-Key: ${VULSEEK_API_KEY}"

Paso 3: Verifica que el servidor MCP esté bien configurado

Ejecuta el siguiente comando en tu terminal:

claude mcp list

El output del comando debería ser similar al siguiente:

vulseek: https://api.vulseek.io/mcp (HTTP) - ✔ Connected

3.3 Configuración usando Antigravity (Google)

Requisitos

Paso 1: Crea el MCP

Crea o edita ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "vulseek": {
      "serverUrl": "https://api.vulseek.io/mcp/",
      "headers": {
        "X-API-Key": "<id_de_integración>@<secreto>"
      },
      "timeoutSeconds": 600
    }
  }
}

Paso 2: Verifica que el servidor MCP esté bien configurado

Ejecuta el siguiente comando en tu terminal:

agy mcp list

El output del comando debería ser similar al siguiente:

●  vulseek  http  enabled  https://api.vulseek.io/mcp/

3.4 Configuración usando GitHub Copilot

Requisitos

Paso 1: Crea el MCP

Crea o edita ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "vulseek": {
      "type": "http",
      "url": "https://api.vulseek.io/mcp",
      "headers": {
        "X-API-Key": "<id_de_integración>@<secreto>"
      },
      "tools": ["*"]
    }
  }
}

Paso 2: Verifica que el servidor MCP esté bien configurado

Ejecuta el siguiente comando en tu terminal:

copilot mcp list

El output del comando debería ser similar al siguiente:

User servers:
  vulseek (http)

4 Ejemplos Prácticos de Prompts

Una vez que tu cliente esté configurado, puedes hacer preguntas como estas:

"Muéstrame todas las vulnerabilidades críticas en mi entorno de Vulseek."

El asistente devolverá un listado de vulnerabilidades con severidad crítica.

"¿Cuántos hallazgos abiertos tenemos cargados en Vulseek correspondientes a IP públicas?"

El asistente devolverá una cantidad (a veces con un resumen) de hallazgos asociados a direcciones IP públicas filtrado por estado open.

"Dame un resumen de nuestra postura de seguridad por severidad."

El asistente debería mostrar un resumen de los hallazgos por nivel de severidad.

"Tengo que resolver los hallazgos detectados en Vulseek y no dispongo de mucho tiempo. ¿Por dónde debería comenzar? ¿Qué me recomiendas?"

Esta consulta puede desencadenar el llamado a varias herramientas del MCP para que el asistente obtenga información detalla de los activos, vulnerabilidades y hallazgos. Debería ofrecer una guía para comenzar con los problemas de seguridad más relevantes.

"Realiza un reporte en base a los hallazgos de severidad crítica y alta identificados en mi entorno de Vulseek"

Esta consulta puede desencadenar el llamado a varias herramientas del MCP para que el asistente obtenga información detalla de los activos, vulnerabilidades y hallazgos. Debería armar un reporte general (usualmente en formato Markdown) pero se puede ajustar el tono, contenido y formato especificando más detalles en el prompt.