VaultMCP

Como funciona

1. Entre com o GitHub e crie um workspace em vaultmcp.dev.
2. Armazene segredos uma única vez (criptografados em repouso — veja Encryption). Compartilhe com colegas de equipe quando necessário.
3. Aponte seu IDE para https://vaultmcp.dev/mcp (ou seu /mcp auto-hospedado).
4. Chame ferramentas como aws__… / github__…. As credenciais são injetadas no lado do servidor — nunca coladas em 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

Recursos

• Cofre somente gravação — listas de APIs, respostas MCP e logs de auditoria nunca retornam valores de segredos
• Injeção no lado do servidor — a descriptografia só acontece dentro da API ao chamar um upstream
• Segredos privados e compartilhados — visibilidade por usuário ou por workspace
• OAuth do GitHub ou tokens pessoais — login no navegador para IDEs, ou tokens vmcp_… em Authorization
• Ferramentas com namespace — registre upstreams uma vez; chame-os como provider__tool_name
• Porta pública única — Docker Compose expõe a porta 80; API e interface permanecem na rede interna
• CLI opcional — injete segredos compartilhados do workspace em npm run dev local (e similares) sem compartilhar arquivos .env

Início rápido (local)

Necessário: Node.js 22+, pnpm 9, Docker (Postgres + Redis) e um GitHub OAuth App.

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

Preencha pelo menos: VAULT_MASTER_KEY, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, PUBLIC_URL, WEB_ORIGIN, DATABASE_URL, REDIS_URL. Os padrões locais estão em .env.example.

GitHub OAuth App

Campo	Local (pnpm)	Docker Compose (porta 80)
URL da página inicial	http://localhost:5173	http://YOUR_SERVER_IP
URL de callback	http://localhost:3001/auth/github/callback	http://YOUR_SERVER_IP/auth/github/callback

O callback deve corresponder a 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

Abra http://localhost:5173 → entre → crie um workspace → adicione segredos → registre um upstream (exemplo da AWS). Upstreams AWS uvx executados no host precisam de uv no seu PATH.

Docker Compose

Um único ponto de entrada público na porta 80. API e web não são publicados diretamente.

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

Superfície	URL
Interface web	http://localhost/
Health	http://localhost/health
MCP	http://localhost/mcp
Descoberta OAuth	http://localhost/.well-known/oauth-protected-resource

As migrações são executadas quando o contêiner da API inicia. Notas de produção: docs/DEPLOY.md.

Conecte o Cursor (ou qualquer cliente MCP)

Mesma estrutura de configuração para Cursor, Claude Desktop, VS Code, Windsurf, Zed e outros clientes MCP. Use OAuth (login no navegador) ou um token de acesso pessoal da aba Connect do painel. Nunca coloque segredos do provedor na configuração do cliente.

OAuth (hospedado)

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

Token pessoal (vmcp_… da aba Connect)

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

Self-host: substitua por https://YOUR_HOST/mcp. API local: http://localhost:3001/mcp.

Cursor: ~/.cursor/mcp.json ou .cursor/mcp.json. Outros clientes usam seu próprio caminho de configuração MCP.

Após a autenticação: list_workspaces → use_workspace → chame ferramentas com namespace (github__…, aws__…).

CLI de env local (opcional)

Para segredos compartilhados da equipe em aplicativos locais (não agentes MCP), use @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

Crie um PAT com o preset Runtime env (CLI) (somente escopo env). Tokens MCP e tokens de env não são intercambiáveis. Prefira run em vez de env para que os segredos permaneçam no processo filho.

Guia completo: docs/CLI.md.

Criptografia

Os valores dos segredos são criptografados em repouso com AES-256-GCM usando criptografia de envelope:

• Cada workspace tem sua própria chave de criptografia de dados (DEK)
• As DEKs são envolvidas por VAULT_MASTER_KEY (mantidas fora do banco de dados)
• O GCM AAD vincula o texto cifrado ao workspaceId, para que blobs não possam ser trocados entre workspaces
• A descriptografia acontece apenas no lado do servidor — para injeção upstream MCP ou exportação CLI opcional
• Os nomes dos segredos e outros metadados não são criptografados (para que a interface possa listar e autorizar sem descriptografar)

Trate VAULT_MASTER_KEY como uma credencial raiz. Gire os segredos do provedor na interface sem alterar a configuração do IDE.

Além disso: listas de APIs e logs de auditoria nunca retornam valores em texto puro; visualizadores não podem invocar ferramentas com segredos nem exportar env de runtime.

Detalhes: docs/CRYPTO.md.

Estrutura do repositório

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 que AGPL

O VaultMCP é frequentemente executado como um serviço de rede. Somente AGPL-3.0 significa que, se você o modificar e oferecer esse serviço por uma rede, deverá compartilhar o código-fonte correspondente. Isso mantém forks hospedados honestos, ao mesmo tempo que permite auto-hospedagem e contribuição.

Contribuindo

O VaultMCP é um projeto de código aberto da Axiler Labs. Adoraríamos ajuda da comunidade — issues e pull requests são muito bem-vindos, especialmente em relação a segurança, confiabilidade, documentação e compatibilidade MCP.

Formas de ajudar:

• Abra uma issue para bugs ou ideias claras de recursos
• Envie um pull request (alterações pequenas e focadas são mais fáceis de revisar)
• Melhore a documentação e exemplos para upstreams comuns

Ao contribuir, você concorda que seu trabalho é licenciado sob somente AGPL-3.0, igual ao restante do repositório. Nunca envie segredos; use .env.example apenas para nomes de variáveis.

Saiba mais em vaultmcp.dev · Axiler Labs: axiler.com.

Licença

Copyright © 2026 Axiler Labs.

O VaultMCP é licenciado sob a GNU Affero General Public License v3.0 somente (AGPL-3.0-only).