VaultMCP

Cómo funciona

1. Inicia sesión con GitHub y crea un espacio de trabajo en vaultmcp.dev.
2. Almacena secretos una sola vez (cifrados en reposo; consulta Cifrado). Compártelos con compañeros cuando sea necesario.
3. Apunta tu IDE a https://vaultmcp.dev/mcp (o a tu /mcp autoalojado).
4. Usa herramientas como aws__… / github__…. Las credenciales se inyectan del lado del servidor; nunca se pegan en mcp.json.

flowchart LR
  subgraph clients [MCP clients]
    Claude[Claude]
    VSCode[VS Code]
    Cursor[Cursor]
    Windsurf[Windsurf]
    Zed[Zed]
  end

  subgraph vaultmcp [VaultMCP]
    API[Vault · OAuth · MCP gateway]
  end

  subgraph upstreams [Upstreams]
    MCP[AWS · GitHub · other MCP]
  end

  Claude --> API
  VSCode --> API
  Cursor --> API
  Windsurf --> API
  Zed --> API
  API -->|inject secrets| MCP

Características

• Bóveda de solo escritura — las listas de APIs, respuestas MCP y registros de auditoría nunca devuelven valores de secretos
• Inyección del lado del servidor — el descifrado solo ocurre dentro de la API al llamar a un servidor ascendente
• Secretos privados y compartidos — visibilidad por usuario o por espacio de trabajo
• OAuth de GitHub o tokens personales — inicio de sesión en navegador para IDEs, o tokens vmcp_… en Authorization
• Herramientas con espacios de nombres — registra los servicios ascendentes una vez; llámalos como provider__tool_name
• Un único puerto público — Docker Compose expone el puerto 80; la API y la interfaz permanecen en la red interna
• CLI opcional — inyecta secretos compartidos del espacio de trabajo en npm run dev local (y similares) sin compartir archivos .env

Inicio rápido (local)

Necesitas: Node.js 22+, pnpm 9, Docker (Postgres + Redis) y una aplicación OAuth de GitHub.

git clone https://github.com/Axiler-Lab/vaultmcp.git
cd vaultmcp
cp .env.example .env

Rellena al menos: VAULT_MASTER_KEY, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, PUBLIC_URL, WEB_ORIGIN, DATABASE_URL, REDIS_URL. Los valores predeterminados locales están en .env.example.

Aplicación OAuth de GitHub

Campo	Local (pnpm)	Docker Compose (puerto 80)
URL de inicio	http://localhost:5173	http://YOUR_SERVER_IP
URL de callback	http://localhost:3001/auth/github/callback	http://YOUR_SERVER_IP/auth/github/callback

El callback debe coincidir con PUBLIC_URL.

docker compose up -d postgres redis
pnpm install
pnpm --filter @vaultmcp/shared build
pnpm db:generate   # first time / after schema changes
pnpm db:migrate
pnpm dev:api       # :3001
pnpm dev:web       # :5173

Abre http://localhost:5173 → inicia sesión → crea un espacio de trabajo → agrega secretos → registra un servicio ascendente (ejemplo de AWS). Los servicios ascendentes de AWS uvx en el host necesitan uv en tu PATH.

Docker Compose

Un único punto de entrada público en el puerto 80. La API y la web no se publican directamente.

cp .env.example .env
# Set PUBLIC_URL, WEB_ORIGIN, GITHUB_*, VAULT_MASTER_KEY
# VITE_API_URL=          # empty = same-origin
# COOKIE_SECURE=false    # true behind HTTPS

docker compose up --build

Superficie	URL
Interfaz web	http://localhost/
Salud	http://localhost/health
MCP	http://localhost/mcp
Descubrimiento OAuth	http://localhost/.well-known/oauth-protected-resource

Las migraciones se ejecutan cuando el contenedor de la API inicia. Notas de producción: docs/DEPLOY.md.

Conecta Cursor (o cualquier cliente MCP)

La misma estructura de configuración para Cursor, Claude Desktop, VS Code, Windsurf, Zed y otros clientes MCP. Usa OAuth (inicio de sesión en navegador) o un token de acceso personal desde la pestaña Conectar del panel. Nunca pongas secretos del proveedor en la configuración del cliente.

OAuth (alojado)

{
  "mcpServers": {
    "vaultmcp": {
      "url": "https://vaultmcp.dev/mcp"
    }
  }
}

Token personal (vmcp_… desde Conectar)

{
  "mcpServers": {
    "vaultmcp": {
      "url": "https://vaultmcp.dev/mcp",
      "headers": {
        "Authorization": "Bearer vmcp_…"
      }
    }
  }
}

Autoalojamiento: reemplaza con https://YOUR_HOST/mcp. API local: http://localhost:3001/mcp.

Cursor: ~/.cursor/mcp.json o .cursor/mcp.json. Otros clientes usan su propia ruta de configuración MCP.

Después de la autenticación: list_workspaces → use_workspace → llama a herramientas con espacios de nombres (github__…, aws__…).

CLI de entorno local (opcional)

Para secretos compartidos del equipo en aplicaciones locales (no agentes MCP), usa @vaultmcp-axiler/cli:

npx @vaultmcp-axiler/cli@latest login --token vmcp_… --url https://YOUR_HOST
npx @vaultmcp-axiler/cli@latest run -w your-slug -- npm run dev

Crea un PAT con el ajuste preestablecido Runtime env (CLI) (solo ámbito env). Los tokens MCP y los tokens de entorno no son intercambiables. Prefiere run sobre env para que los secretos permanezcan en el proceso hijo.

Guía completa: docs/CLI.md.

Cifrado

Los valores de los secretos se cifran en reposo con AES-256-GCM mediante cifrado de sobre:

• Cada espacio de trabajo tiene su propia clave de cifrado de datos (DEK)
• Las DEK se envuelven con VAULT_MASTER_KEY (se mantienen fuera de la base de datos)
• El AAD de GCM vincula el texto cifrado al workspaceId, de modo que los blobs no pueden intercambiarse entre espacios de trabajo
• El descifrado solo ocurre del lado del servidor: para inyección ascendente de MCP o exportación CLI opcional
• Los nombres de los secretos y otros metadatos no se cifran (para que la interfaz pueda listar y autorizar sin descifrar)

Trata VAULT_MASTER_KEY como una credencial raíz. Rota los secretos del proveedor en la interfaz sin cambiar la configuración del IDE.

Además: las listas de APIs y los registros de auditoría nunca devuelven valores en texto plano; los visores no pueden invocar herramientas respaldadas por secretos ni exportar el entorno de ejecución.

Detalles: docs/CRYPTO.md.

Estructura del repositorio

apps/api            Gateway, OAuth, REST, upstream proxy
apps/web            Control plane UI
packages/shared     Crypto helpers + shared schemas
packages/cli        Local env injection CLI
deploy/             Reverse proxy config
docs/               Deploy, CLI, and crypto guides
examples/           Upstream walkthroughs

Por qué AGPL

VaultMCP a menudo se ejecuta como un servicio de red. AGPL-3.0-only significa que si lo modificas y ofreces ese servicio a través de una red, debes compartir el código fuente correspondiente. Esto mantiene honestas las bifurcaciones alojadas, mientras permite el autoalojamiento y la contribución.

Contribución

VaultMCP es un proyecto de código abierto de Axiler Labs. Nos encantaría la ayuda de la comunidad: los problemas y las solicitudes de cambios son muy bienvenidos, especialmente en seguridad, confiabilidad, documentación y compatibilidad con MCP.

Formas de ayudar:

• Abre un problema para errores o ideas claras de funciones
• Envía una solicitud de cambios (los cambios pequeños y enfocados son los más fáciles de revisar)
• Mejora la documentación y los ejemplos para servicios ascendentes comunes

Al contribuir, aceptas que tu trabajo se licencia bajo AGPL-3.0-only, igual que el resto del repositorio. Nunca commitees secretos; usa .env.example solo para nombres de variables.

Obtén más información en vaultmcp.dev · Axiler Labs: axiler.com.

Licencia

Copyright © 2026 Axiler Labs.

VaultMCP se distribuye bajo la GNU Affero General Public License v3.0 only (AGPL-3.0-only).