Vulnify MCP

npx add-mcp 'https://mcp.vulnify.io/mcp'

Vulnify MCP

Pregunta a Vulnify antes de que un agente de IA lea, escriba, elimine, exporte o envíe datos.
finalDecision es el resultado autoritativo: ALLOW, REVIEW o BLOCK.

Docs  ·  MCP  ·  Changelog  ·  Node SDK

@vulnify/mcp es el servidor MCP para Vulnify, una capa de autorización en tiempo de ejecución para agentes de IA. El agente pregunta primero. Este proceso actúa como proxy de https://api.vulnify.io. No almacena eventos ni claves de API.

Inicia sesión con Vulnify (OAuth 2.1) en https://mcp.vulnify.io/mcp. Ese servidor alojado habla HTTP Streamable sin estado. La ruta local es npx -y @vulnify/mcp con VULNIFY_API_KEY.

check_action es una ejecución de prueba. Omite el escaneo de PII y no registra nada. decide_action registra una decisión real. Un REVIEW espera a una persona. Este servidor no puede aprobar ni denegar uno.

El código de aplicación que deba decidir dentro de tu propio proceso usa el Node SDK (@vulnify/sdk). Este paquete no depende del SDK. El SDK convierte algunos fallos de transporte en una decisión de cierre por fallo. Este servidor devuelve esos fallos como errores de herramienta MCP, para que un modelo no los lea como ALLOW.

Inicio rápido

La fuente de verdad es docs.vulnify.io/mcp. Los mismos pasos están en docs/clients.md.

Inicia sesión con Vulnify

Conéctate a https://mcp.vulnify.io/mcp. Deja vacíos los campos de clave de API y de cliente OAuth. El cliente recibe HTTP 401 y:

WWW-Authenticate: Bearer realm="https://mcp.vulnify.io/mcp", resource_metadata="https://mcp.vulnify.io/.well-known/oauth-protected-resource/mcp", scope="decisions:read decisions:write policies:read policies:test"

El cuerpo es {"error":"unauthorized","message":"Sign in with Vulnify, or send an API key as Authorization: Bearer or X-Vulnify-Key:."}. Los metadatos del recurso protegido listan el servidor de autorización https://api.vulnify.io.

Eliges una organización y permites los alcances que el cliente solicita:

Alcance	Herramientas
decisions:read	get_decision
decisions:write	decide_action
policies:read	list_policies
policies:test	check_action, test_policies

Después de permitir el acceso, el servidor alojado ofrece esas cinco herramientas. plan_policy_changes y check_mcp_tool_call no están en esa lista. Necesitan una clave de API. Un alcance faltante se devuelve como un error de herramienta que nombra el alcance. Ese error no es un ALLOW. Revoca la conexión en Configuración > Aplicaciones conectadas: app.vulnify.io/settings/connected-apps.

Claude

En Claude, abre Configuración > Conectores > Agregar conector personalizado. Establece la URL en https://mcp.vulnify.io/mcp. No pegues una clave de API. Agregar Vulnify en Claude abre ese diálogo con el nombre y la URL ya completados. Claude luego inicia Inicia sesión con Vulnify.

Cursor

Instalar en Cursor agrega el servidor alojado e inicia el inicio de sesión.

El mismo servidor en .cursor/mcp.json, o en ~/.cursor/mcp.json, es la URL sin encabezado:

{
  "mcpServers": {
    "vulnify": {
      "url": "https://mcp.vulnify.io/mcp"
    }
  }
}

Grok

Abre grok.com/connectors, luego Nuevo Conector > Personalizado. Nómbralo Vulnify. Establece la URL en https://mcp.vulnify.io/mcp. Deja vacíos los campos OAuth. Grok inicia Inicia sesión con Vulnify.

Claude Code

claude mcp add --transport http vulnify https://mcp.vulnify.io/mcp

Claude Code luego inicia sesión. No pases una clave de API en este comando.

Clave de API o npx local

Usa una clave de API cuando necesites plan_policy_changes o check_mcp_tool_call, cuando el cliente no pueda abrir un navegador, o cuando la clave tenga una lista de permitidos de IP. El proceso local necesita Node.js 20 o más reciente y lee VULNIFY_API_KEY. No abre la página de consentimiento OAuth.

npx -y @vulnify/mcp

VULNIFY_API_KEY=vln_live_... npx -y @vulnify/mcp

La clave es vln_live_... o vln_test_.... Una clave TEST almacena eventos de sandbox. Esos permanecen fuera de los paneles principales.

En el servidor alojado, ambos encabezados siguen funcionando. Envía la clave en cada solicitud:

Authorization: Bearer <key>
X-Vulnify-Key: <key>

Una sesión con clave de API lista las siete herramientas.

Cursor, alojado:

{
  "mcpServers": {
    "vulnify": {
      "url": "https://mcp.vulnify.io/mcp",
      "headers": {
        "Authorization": "Bearer vln_live_..."
      }
    }
  }
}

Cursor, local:

{
  "mcpServers": {
    "vulnify": {
      "command": "npx",
      "args": ["-y", "@vulnify/mcp"],
      "env": {
        "VULNIFY_API_KEY": "vln_live_..."
      }
    }
  }
}

X-Vulnify-Key funciona en lugar de Authorization en el servidor alojado.

Claude Code con una clave de API:

claude mcp add --transport http vulnify https://mcp.vulnify.io/mcp --header "Authorization: Bearer vln_test_your_key"

Prefiere una variable de entorno sobre una clave escrita en el historial del shell. Para el inicio de sesión, usa el comando de Claude Code sin encabezado.

Claude Desktop puede ejecutar el proceso local. En macOS el archivo es ~/Library/Application Support/Claude/claude_desktop_config.json. En Windows es %APPDATA%\Claude\claude_desktop_config.json. Reinicia la aplicación después de guardar.

{
  "mcpServers": {
    "vulnify": {
      "command": "npx",
      "args": ["-y", "@vulnify/mcp"],
      "env": {
        "VULNIFY_API_KEY": "vln_live_..."
      }
    }
  }
}

VS Code, .vscode/mcp.json, alojado:

{
  "servers": {
    "vulnify": {
      "type": "http",
      "url": "https://mcp.vulnify.io/mcp",
      "headers": {
        "Authorization": "Bearer ${input:vulnify-api-key}"
      }
    }
  }
}

VS Code, local:

{
  "servers": {
    "vulnify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@vulnify/mcp"],
      "env": {
        "VULNIFY_API_KEY": "${input:vulnify-api-key}"
      }
    }
  }
}

Cómo funciona

El campo finalDecision es el resultado autoritativo. Un error de herramienta no es un ALLOW.

Herramientas

Cada herramienta tiene un título y readOnlyHint, destructiveHint, idempotentHint y openWorldHint. Las pistas le indican al cliente cómo presentar la herramienta. No cambian lo que hace la herramienta.

Herramienta	API	¿Registra?	readOnlyHint	Notas
check_action	POST /v1/policies/test (un caso)	No	true	Omite el escaneo de PII y no registra nada. Sin id de evento.
decide_action	POST /v1/events	Sí	false	Escribe un evento de seguridad y una entrada de auditoría. finalDecision es el resultado autoritativo.
get_decision	GET /v1/events/{id}	No	true	Lee una decisión. La espera opcional sondea un REVIEW hasta ALLOW o BLOCK (máximo 30 segundos).
list_policies	GET /v1/policies	No	true	Políticas como código, ordenadas por nombre.
test_policies	POST /v1/policies/test	No	true	Hasta 200 casos. Omite el escaneo de PII. Los policies propuestos no se guardan.
plan_policy_changes	POST /v1/policies/apply	No	true	dryRun se fuerza a true. Necesita una clave LIVE de toda la organización.
check_mcp_tool_call	POST /v1/gateway/mcp	Sí	false	Mapea un nombre de herramienta a una acción y registra la decisión. No ejecuta la herramienta.

destructiveHint es false en cada herramienta. openWorldHint es false en cada herramienta, porque cada llamada permanece dentro de la propia organización Vulnify del llamante. idempotentHint es true para las herramientas de solo lectura y false para decide_action y check_mcp_tool_call. Un idempotencyKey hace que un reintento de una decisión registrada devuelva el mismo evento.

Las llamadas de lista de políticas, prueba y plan están limitadas a 60 solicitudes por minuto por clave. Ejecuta pruebas por lotes con test_policies. POST /v1/events tiene su propio límite. El texto de OpenAPI solo dice que se excedió el límite.

Seguridad

Este servidor no puede cambiar una revisión ni guardar una política.

• No hay herramienta de aprobar ni de denegar. Un humano resuelve un REVIEW en Vulnify.
• No hay herramienta de aplicar. plan_policy_changes llama a POST /v1/policies/apply con dryRun: true en cada solicitud. La entrada de la herramienta no tiene campo dryRun. El servidor establece dryRun al final, para que un llamante no pueda desactivar la ejecución de prueba. La herramienta devuelve el diff.
• POST /v1/gateway/http no es una herramienta. En ALLOW, ese endpoint de API reenvía la llamada HTTP. Este servidor no lo hace.

plan_policy_changes necesita una clave LIVE de toda la organización. Una clave TEST o una clave vinculada a un agente recibe 403. Una sesión OAuth no lista plan_policy_changes ni check_mcp_tool_call.

Alcances OAuth

El inicio de sesión de usuario es el servidor HTTP alojado. El proceso local stdio aún usa una clave de API. El servidor alojado mapea herramientas a alcances:

Herramienta	Alcance	Ruta OAuth
check_action	policies:test	POST /v1/mcp/policies/test
test_policies	policies:test	POST /v1/mcp/policies/test
decide_action	decisions:write	POST /v1/mcp/events
get_decision	decisions:read	GET /v1/mcp/events/{id}
list_policies	policies:read	GET /v1/mcp/policies
plan_policy_changes	Solo clave de API y stdio	Omitido de OAuth tools/list
check_mcp_tool_call	Solo clave de API y stdio	Omitido de OAuth tools/list

Un token al que le falta el alcance recibe un error de herramienta que nombra el alcance. Ese error no es un ALLOW. Los resultados de introspección activos se reutilizan durante como máximo 60 segundos, y nunca más allá de exp.

Distinto de la puerta de enlace MCP

https://mcp.vulnify.io/mcp (y el proceso local stdio) es el servidor al que se conecta un cliente MCP. El cliente luego llama a las herramientas anteriores.

check_mcp_tool_call es diferente. Envía una llamada de herramienta a POST /v1/gateway/mcp en api.vulnify.io, registra la decisión y se detiene. No ejecuta la herramienta, y conectar un cliente a este servidor no llama a esa puerta de enlace.

Listas de permitidos de IP

Una clave de API puede listar IPs de origen permitidas. Las llamadas a través de https://mcp.vulnify.io/mcp con esa clave provienen de la dirección de salida del servidor alojado, no de la máquina donde se ejecuta Cursor o VS Code. Una lista de permitidos que solo contenga una dirección de oficina o portátil rechaza el servidor alojado. Usa npx -y @vulnify/mcp en un host cuya dirección esté en la lista. Inicia sesión con Vulnify no envía esa clave de API.

Producto

La captura de pantalla es de un espacio de trabajo de demostración. El agente es SupportBot.

Las exportaciones de auditoría en la aplicación Vulnify son una descarga JSON o CSV que incluye una suma de verificación SHA-256. La exportación SIEM es líneas JSON o CEF.

Configuración

Variable	Dónde	Requerida	Propósito
VULNIFY_API_KEY	proceso stdio	sí	Clave de API (vln_live_... o vln_test_...). HTTP no recurre a esta variable.
VULNIFY_BASE_URL	ambos	no	URL base de la API. Predeterminada https://api.vulnify.io.
OAUTH_INTROSPECTION_SECRET	HTTP	para inicio de sesión de usuario	Secreto Bearer para POST /oauth/introspect. Permanece en el servidor. Las claves de API funcionan sin él.
OPENAI_APPS_CHALLENGE	HTTP	no	Cuando se establece, GET /.well-known/openai-apps-challenge devuelve este valor como text/plain. Sin establecer, esa ruta es 404.
PORT	HTTP	no	Puerto de escucha. Predeterminado 8080.
HOST	HTTP	no	Dirección de enlace. Predeterminada 0.0.0.0.

Usa una clave LIVE vinculada a un agente cuando una decisión registrada deba contar para un agente. plan_policy_changes necesita una clave LIVE de toda la organización.

VULNIFY_TEST_API_KEY es solo para npm run test:live. El servidor no la lee.

Servidor HTTP

npx -y @vulnify/mcp --http

El contenedor ejecuta el servidor HTTP como un usuario no root:

docker build -t vulnify-mcp .
docker run --rm -p 8080:8080 -e PORT=8080 vulnify-mcp

No se requiere clave de API para iniciar el contenedor. Envía la clave en cada solicitud.

curl -sS localhost:8080/health
curl -sS -o /dev/null -w '%{http_code}\n' -X POST localhost:8080/mcp \
  -H 'content-type: application/json' -d '{}'

La verificación de salud imprime JSON. El POST sin clave imprime 401.

GET /.well-known/mcp/server-card.json no requiere clave. Lista las herramientas que el servidor registra (nombres, descripciones y esquemas de entrada), indica que puedes iniciar sesión con OAuth o enviar una clave de API de Vulnify en un encabezado, y enlaza a la documentación y a este repositorio.

curl -sS https://mcp.vulnify.io/.well-known/mcp/server-card.json

Errores

Los fallos de herramientas son errores de herramienta MCP (isError). La clave de API no se incluye.

Estado	Significado
401	La clave de API o el token de acceso falta, no es válido, fue revocado o expiró.
403	La clave está vinculada a otro agente, la IP del llamante no está en la lista de permitidos, al token de acceso le falta un alcance, o plan_policy_changes se llamó sin una clave LIVE de toda la organización.
413	El cuerpo JSON supera el límite de 200 KB de la API.
429	La clave está limitada por tasa. Las llamadas de política son 60 por minuto. Reintenta una decisión registrada con el mismo idempotencyKey.

Seguridad

Reporta una vulnerabilidad a security@vulnify.io. La política de divulgación está en vulnify.io/disclosure. Consulta SECURITY.md.

Las claves no se registran. Los registros de solicitudes son método, ruta y estado. content enviado para un escaneo de datos sensibles se reenvía a la API y no se escribe en los registros de este servidor. La API escanea ese texto en memoria y no lo almacena. Este paquete no ejecuta un shell y no registra hooks. No coloque una clave en un argumento de herramienta ni en un archivo de configuración confirmado.

Los endpoints de red que utiliza este proceso:

• https://api.vulnify.io (o VULNIFY_BASE_URL) para cada llamada de herramienta, y para GET /v1/policies cuando se verifica una clave de API. Una clave de API se envía como Authorization: Bearer a /v1/*. Un token de acceso de usuario se envía como Authorization: Bearer a /v1/mcp/*.
• POST /oauth/introspect en ese mismo origen, con Authorization: Bearer establecido en OAUTH_INTROSPECTION_SECRET, para validar tokens vln_oat_.... El secreto no se envía a los clientes y no se registra.
• https://mcp.vulnify.io/mcp es el transporte HTTP alojado. El proceso del servidor no llama a esa URL.

Desarrollo

npm install
npm test
npm run lint
npm run build

npm run test:live llama a list_policies en https://api.vulnify.io cuando VULNIFY_TEST_API_KEY está establecido, y se omite cuando no lo está. No registra un evento.

La publicación se describe en RELEASING.md.

Licencia

MIT. Copyright 2026 Vulnify.