Vulnify MCP

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

Vulnify MCP

Pergunte ao Vulnify antes que um agente de IA leia, grave, exclua, exporte ou envie dados.
finalDecision é o resultado autoritativo: ALLOW, REVIEW ou BLOCK.

Docs  ·  MCP  ·  Changelog  ·  Node SDK

@vulnify/mcp é o servidor MCP para Vulnify, uma camada de autorização em tempo de execução para agentes de IA. O agente pergunta primeiro. Este processo faz proxy de https://api.vulnify.io. Ele não armazena eventos ou chaves de API.

Entre com o Vulnify (OAuth 2.1) em https://mcp.vulnify.io/mcp. Esse servidor hospedado fala HTTP Streamable sem estado. O caminho local é npx -y @vulnify/mcp com VULNIFY_API_KEY.

check_action é uma execução de teste. Ela pula a verificação de PII e não registra nada. decide_action registra uma decisão real. Um REVIEW aguarda uma pessoa. Este servidor não pode aprovar ou negar um.

Código de aplicação que deve decidir dentro do seu próprio processo usa o Node SDK (@vulnify/sdk). Este pacote não depende do SDK. O SDK transforma algumas falhas de transporte em uma decisão de falha fechada. Este servidor retorna essas falhas como erros de ferramenta MCP, para que um modelo não as leia como ALLOW.

Início rápido

A fonte da verdade é docs.vulnify.io/mcp. Os mesmos passos estão em docs/clients.md.

Entre com o Vulnify

Conecte-se a https://mcp.vulnify.io/mcp. Deixe os campos de chave de API e cliente OAuth vazios. O cliente recebe HTTP 401 e:

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"

O corpo é {"error":"unauthorized","message":"Sign in with Vulnify, or send an API key as Authorization: Bearer or X-Vulnify-Key:."}. Os metadados de recurso protegido listam o servidor de autorização https://api.vulnify.io.

Você escolhe uma organização e permite os escopos que o cliente solicita:

Escopo	Ferramentas
decisions:read	get_decision
decisions:write	decide_action
policies:read	list_policies
policies:test	check_action, test_policies

Depois que você permite o acesso, o servidor hospedado oferece essas cinco ferramentas. plan_policy_changes e check_mcp_tool_call não estão nessa lista. Elas precisam de uma chave de API. Um escopo ausente retorna como um erro de ferramenta que nomeia o escopo. Esse erro não é um ALLOW. Revogue a conexão em Configurações > Aplicativos conectados: app.vulnify.io/settings/connected-apps.

Claude

No Claude, abra Configurações > Conectores > Adicionar conector personalizado. Defina a URL como https://mcp.vulnify.io/mcp. Não cole uma chave de API. Adicionar Vulnify no Claude abre esse diálogo com o nome e a URL preenchidos. O Claude então inicia Entre com o Vulnify.

Cursor

Instalar no Cursor adiciona o servidor hospedado e inicia o login.

O mesmo servidor em .cursor/mcp.json, ou em ~/.cursor/mcp.json, é a URL sem cabeçalho:

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

Grok

Abra grok.com/connectors, depois Novo Conector > Personalizado. Nomeie como Vulnify. Defina a URL como https://mcp.vulnify.io/mcp. Deixe os campos OAuth vazios. O Grok inicia Entre com o Vulnify.

Claude Code

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

O Claude Code então faz login. Não passe uma chave de API neste comando.

Chave de API ou npx local

Use uma chave de API quando precisar de plan_policy_changes ou check_mcp_tool_call, quando o cliente não puder abrir um navegador, ou quando a chave tiver uma lista de permissões de IP. O processo local precisa de Node.js 20 ou mais recente e lê VULNIFY_API_KEY. Ele não abre a página de consentimento OAuth.

npx -y @vulnify/mcp

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

A chave é vln_live_... ou vln_test_.... Uma chave TEST armazena eventos de sandbox. Eles ficam fora dos painéis principais.

No servidor hospedado, ambos os cabeçalhos ainda funcionam. Envie a chave em cada solicitação:

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

Uma sessão com chave de API lista todas as sete ferramentas.

Cursor, hospedado:

{
  "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 no lugar de Authorization no servidor hospedado.

Claude Code com chave de API:

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

Prefira uma variável de ambiente em vez de uma chave escrita no histórico do shell. Para login, use o comando do Claude Code sem cabeçalho.

O Claude Desktop pode executar o processo local. No macOS, o arquivo é ~/Library/Application Support/Claude/claude_desktop_config.json. No Windows, é %APPDATA%\Claude\claude_desktop_config.json. Reinicie o aplicativo após salvar.

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

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

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

Como funciona

O campo finalDecision é o resultado autoritativo. Um erro de ferramenta não é um ALLOW.

Ferramentas

Cada ferramenta tem um título e readOnlyHint, destructiveHint, idempotentHint e openWorldHint. As dicas dizem ao cliente como apresentar a ferramenta. Elas não mudam o que a ferramenta faz.

Ferramenta	API	Registra?	readOnlyHint	Notas
check_action	POST /v1/policies/test (um caso)	Não	true	Pula a verificação de PII e não registra nada. Sem id de evento.
decide_action	POST /v1/events	Sim	false	Grava um evento de segurança e uma entrada de auditoria. finalDecision é o resultado autoritativo.
get_decision	GET /v1/events/{id}	Não	true	Lê uma decisão. Espera opcional faz polling de um REVIEW até ALLOW ou BLOCK (máximo de 30 segundos).
list_policies	GET /v1/policies	Não	true	Políticas como código, ordenadas por nome.
test_policies	POST /v1/policies/test	Não	true	Até 200 casos. Pula a verificação de PII. policies propostos não são salvos.
plan_policy_changes	POST /v1/policies/apply	Não	true	dryRun é forçado para true. Precisa de uma chave LIVE de toda a organização.
check_mcp_tool_call	POST /v1/gateway/mcp	Sim	false	Mapeia um nome de ferramenta para uma ação e registra a decisão. Não executa a ferramenta.

destructiveHint é false em todas as ferramentas. openWorldHint é false em todas as ferramentas, porque cada chamada permanece dentro da própria organização Vulnify do chamador. idempotentHint é true para as ferramentas somente leitura e false para decide_action e check_mcp_tool_call. Um idempotencyKey faz uma nova tentativa de uma decisão registrada retornar o mesmo evento.

Chamadas de lista de políticas, teste e plano são limitadas a 60 solicitações por minuto por chave. Faça lotes de execuções de teste com test_policies. POST /v1/events tem seu próprio limite. O texto do OpenAPI diz apenas que o limite foi excedido.

Segurança

Este servidor não pode alterar uma revisão e não pode salvar uma política.

• Não há ferramenta de aprovação e nem ferramenta de negação. Um humano resolve um REVIEW no Vulnify.
• Não há ferramenta de aplicação. plan_policy_changes chama POST /v1/policies/apply com dryRun: true em cada solicitação. A entrada da ferramenta não tem campo dryRun. O servidor define dryRun por último, então um chamador não pode desligar a execução de teste. A ferramenta retorna o diff.
• POST /v1/gateway/http não é uma ferramenta. Em ALLOW, esse endpoint de API encaminha a chamada HTTP. Este servidor não faz isso.

plan_policy_changes precisa de uma chave LIVE de toda a organização. Uma chave TEST ou uma chave vinculada a um agente recebe 403. Uma sessão OAuth não lista plan_policy_changes ou check_mcp_tool_call.

Escopos OAuth

O login do usuário é o servidor HTTP hospedado. O processo local stdio ainda usa uma chave de API. O servidor hospedado mapeia ferramentas para escopos:

Ferramenta	Escopo	Rota 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	Somente chave de API e stdio	Omitido do OAuth tools/list
check_mcp_tool_call	Somente chave de API e stdio	Omitido do OAuth tools/list

Um token que está sem o escopo recebe um erro de ferramenta que nomeia o escopo. Esse erro não é um ALLOW. Resultados de introspecção ativos são reutilizados por no máximo 60 segundos, e nunca além de exp.

Distinto do gateway MCP

https://mcp.vulnify.io/mcp (e o processo local stdio) é o servidor ao qual um cliente MCP se conecta. O cliente então chama as ferramentas acima.

check_mcp_tool_call é diferente. Ele envia uma chamada de ferramenta para POST /v1/gateway/mcp em api.vulnify.io, registra a decisão e para. Ele não executa a ferramenta, e conectar um cliente a este servidor não chama esse gateway.

Listas de permissão de IP

Uma chave de API pode listar IPs de origem permitidos. Chamadas através de https://mcp.vulnify.io/mcp com essa chave vêm do endereço de saída do servidor hospedado, não da máquina onde o Cursor ou o VS Code está rodando. Uma lista de permissão que contém apenas um endereço de escritório ou laptop rejeita o servidor hospedado. Use npx -y @vulnify/mcp em um host cujo endereço está na lista. Entre com o Vulnify não envia essa chave de API.

Produto

A captura de tela é de um workspace de demonstração. O agente é SupportBot.

Exportações de auditoria no aplicativo Vulnify são um download JSON ou CSV que inclui uma soma de verificação SHA-256. Exportação SIEM é linhas JSON ou CEF.

Configuração

Variável	Onde	Obrigatória	Propósito
VULNIFY_API_KEY	processo stdio	sim	Chave de API (vln_live_... ou vln_test_...). HTTP não recorre a esta variável.
VULNIFY_BASE_URL	ambos	não	URL base da API. Padrão https://api.vulnify.io.
OAUTH_INTROSPECTION_SECRET	HTTP	para login do usuário	Segredo Bearer para POST /oauth/introspect. Permanece no servidor. Chaves de API funcionam sem ele.
OPENAI_APPS_CHALLENGE	HTTP	não	Quando definido, GET /.well-known/openai-apps-challenge retorna este valor como text/plain. Não definido, esse caminho é 404.
PORT	HTTP	não	Porta de escuta. Padrão 8080.
HOST	HTTP	não	Endereço de bind. Padrão 0.0.0.0.

Use uma chave LIVE vinculada a um agente quando uma decisão registrada deve contar para um agente. plan_policy_changes precisa de uma chave LIVE de toda a organização.

VULNIFY_TEST_API_KEY é apenas para npm run test:live. O servidor não a lê.

Servidor HTTP

npx -y @vulnify/mcp --http

O contêiner executa o servidor HTTP como um usuário não root:

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

Nenhuma chave de API é necessária para iniciar o contêiner. Envie a chave em cada solicitação.

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

A verificação de saúde imprime JSON. O POST sem chave imprime 401.

GET /.well-known/mcp/server-card.json não requer uma chave. Ele lista as ferramentas que o servidor registra (nomes, descrições e esquemas de entrada), afirma que você pode entrar com OAuth ou enviar uma chave de API Vulnify em um cabeçalho, e vincula aos docs e a este repositório.

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

Erros

Falhas de ferramenta são erros de ferramenta MCP (isError). A chave de API não está incluída.

Status	Significado
401	A chave de API ou token de acesso está ausente, inválido, revogado ou expirado.
403	A chave está vinculada a outro agente, o IP do chamador não está na lista de permissão, o token de acesso não tem um escopo, ou plan_policy_changes foi chamado sem uma chave LIVE de toda a organização.
413	O corpo JSON está acima do limite de 200 KB da API.
429	A chave está com limite de taxa. Chamadas de política são 60 por minuto. Tente novamente uma decisão registrada com o mesmo idempotencyKey.

Segurança

Reporte uma vulnerabilidade para security@vulnify.io. A política de divulgação está em vulnify.io/disclosure. Veja SECURITY.md.

Chaves não são registradas. Logs de solicitação são método, caminho e status. content enviado para uma verificação de dados sensíveis é encaminhado para a API e não é gravado nos logs deste servidor. A API verifica esse texto em memória e não o armazena. Este pacote não executa um shell e não registra hooks. Não coloque uma chave em um argumento de ferramenta ou em um arquivo de configuração commitado.

Endpoints de rede que este processo utiliza:

• https://api.vulnify.io (ou VULNIFY_BASE_URL) para cada chamada de ferramenta, e para GET /v1/policies quando uma chave de API é verificada. Uma chave de API é enviada como Authorization: Bearer para /v1/*. Um token de acesso de usuário é enviado como Authorization: Bearer para /v1/mcp/*.
• POST /oauth/introspect na mesma origem, com Authorization: Bearer definido como OAUTH_INTROSPECTION_SECRET, para validar tokens vln_oat_.... O segredo não é enviado aos clientes e não é registrado em logs.
• https://mcp.vulnify.io/mcp é o transporte HTTP hospedado. O processo do servidor não chama essa URL.

Desenvolvimento

npm install
npm test
npm run lint
npm run build

npm run test:live chama list_policies em https://api.vulnify.io quando VULNIFY_TEST_API_KEY está definido, e pula quando não está. Ele não registra um evento.

A publicação é descrita em RELEASING.md.

Licença

MIT. Copyright 2026 Vulnify.