Ir para o conteúdo

Servidor MCP

O BombVault tem um servidor integrado para o Model Context Protocol (MCP), o protocolo com que assistentes de IA como o Claude Code e o Claude Desktop chegam a ferramentas externas. Através dele, um assistente pode ler como estão os teus backups e, se o permitires, iniciar um backup ou cancelar um que ele próprio iniciou. Está desligado até criares uma chave ou ligares a autenticação por OAuth: até lá, o endpoint /mcp responde 404 a tudo.

O que um assistente pode e não pode fazer

Ferramenta O que faz Tipo
get_health Versão, nome da instância, se há um backup em curso e o que esta chave pode fazer leitura
get_status Estado de proteção por secção: último backup bem-sucedido, intervalo esperado, verificações e controlos externos, próximas execuções agendadas, backups à espera de que a app fique inativa e, para os contentores, o teste de arranque mais recente leitura
get_coverage O que o BombVault protege e o que não protege, com o motivo de cada caso leitura
list_items Cada contentor, VM e conjunto de pastas protegido, a pen flash e a configuração da app, com o agendamento, o que um backup para, o último backup e quanto demorou. Os contentores de base de dados indicam também o último dump. Os datasets ZFS também aparecem, com o resultado da sua última verificação. Cada entrada traz a sua última verificação de restauro, e um contentor o seu último teste de arranque ou o motivo por que não pode ser testado. Um contêiner recriado com outras configurações desde o último backup indica o que mudou leitura
list_runs Histórico de execuções, as mais recentes primeiro, filtrável por secção, entrada, estado, tipo e data. Um backup lento travado por uma única coisa nomeia-a leitura
list_restore_points Pontos de restauro de uma entrada no seu repositório principal e, para um contentor, os seus dumps de base de dados. Um dataset ZFS tem um ponto de restauro por backup, com um snapshot de cada dataset abaixo dele leitura
get_activity O que está a correr agora, com fase e percentagem leitura
get_storage_stats Histórico de tamanho do repositório principal de uma secção e o seu crescimento semanal, com o espaço usado, livre e total no disco ou remoto de cada um dos seus repositórios leitura
get_size_breakdown Que pastas e arquivos ocupam espaço no backup mais recente de um contêiner, uma VM ou um conjunto de pastas, e quanto disso o último backup acrescentou leitura
search_files Procura arquivos e pastas pelo nome nos backups de todas as entradas, de uma secção ou de uma entrada (as VM não são pesquisadas) e mostra cada backup que contém cada resultado leitura
list_anomalies Anomalias que o BombVault detetou nos backups, filtráveis por estado, gravidade e secção, com um resumo do que está em aberto leitura
get_anomaly Uma dessas ocorrências, com a nota deixada quando foi reconhecida leitura
start_backup Faz já o backup de uma entrada início
start_domain_backup Faz o backup de cada entrada protegida de uma secção início
start_backup_everything Corre a passagem Backup total início
cancel_backup Cancela um backup em curso que esta chave iniciou cancelamento

Fica na interface web: os restauros de qualquer tipo (incluindo descarregar, guardar ou importar um dump de base de dados), apagar backups, prune, unlock, as verificações e os exercícios, a replicação externa, as definições, as credenciais e as chaves MCP, e cancelar um backup iniciado pelo agendamento, pela interface web ou por outra chave. O mesmo vale para reconhecer uma anomalia ou marcá-la como esperada, o que se faz na página Anomalias. O motivo: as respostas das ferramentas contêm nomes e mensagens de erro do teu servidor, e qualquer um deles pode trazer texto escrito para manipular o assistente. Um assistente que caia nesse texto pode, no pior caso, iniciar um backup dentro dos limites abaixo ou cancelar um que ele próprio iniciou.

Se o repositório principal de uma entrada for remoto (S3, REST, SFTP, rclone), list_restore_points contacta-o e a chamada pode demorar algum tempo. As cópias externas não podem ser listadas por MCP. search_files só lê repositórios remotos, cópias externas incluídas, quando o assistente o pede, porque demora mais e alguns fornecedores cobram os dados que descarrega. Uma pesquisa pode demorar minutos, por isso a primeira chamada inicia-a em segundo plano e uma chamada posterior recolhe o resultado. O que as verificações de anomalias analisam está descrito em Anomalias, e como uma entrada ZFS guarda um snapshot por conjunto de dados, em Conjuntos de dados ZFS.

O que faz um backup iniciado

O backup de um assistente é o mesmo que a interface web inicia. Um contentor em execução é parado até o seu backup terminar, junto com os contentores configurados para parar com ele. Uma VM com o método "graceful" é desligada e arrancada de novo. Um dataset ZFS para os contentores configurados para ele enquanto o seu snapshot é criado. Os conjuntos de pastas, a pen flash e a configuração continuam a correr. Depois, o BombVault aplica a política de retenção e pode copiar para o repositório externo. list_items diz ao assistente o que uma entrada para e quanto demorou o seu último backup, e as descrições das ferramentas pedem-lhe que lho diga antes de iniciar o que quer que seja.

Como um backup para serviços e faz sair pontos de restauro antigos, os inícios por MCP são limitados:

  • 12 backups iniciados por hora e por chave.
  • 15 minutos entre dois inícios MCP da mesma entrada, da mesma secção ou do Backup total.
  • No máximo 4 inícios MCP da mesma entrada em 24 horas.
  • Proteção da retenção. Quando uma secção mantém um número fixo de pontos de restauro (só "manter os últimos N", sem regra diária, semanal ou mensal, localmente ou num destino externo), cada backup novo faz sair o mais antigo. O BombVault recusa então um início MCP de uma entrada cujos N-1 backups bem-sucedidos mais recentes foram todos iniciados por MCP. Assim fica sempre no conjunto mantido pelo menos um ponto de restauro criado pelo agendamento ou por ti. Com "manter o último" (N = 1), um assistente não consegue fazer backup dessa entrada. O próximo backup agendado volta a abrir espaço. Uma regra anual sozinha conta como "manter o último" (N = 1), porque mantém um único ponto de restauro do ano corrente.

Um início de secção ou do Backup total deixa de fora as entradas que um limite retém e indica-os na resposta. A interface web e o agendamento não são afetados por nada disto. A quota horária vive em memória, por isso um reinício do BombVault repõe-na a zero.

Os inícios pela API e a partir do Home Assistant contam para os mesmos limites por entrada que os inícios por MCP, e para a proteção da retenção.

Ativar

  1. Abre Definições, Integrações, Servidor MCP clica em Escolher um cliente e escolhe o teu na janela. A pesquisa no canto superior direito encontra-o pelo nome. Um cliente que não está na lista liga-se através de Outro cliente.
  2. Em Chave, deixa Chave nova e o nome proposto, o do cliente, ou escreve um que diga onde a chave é usada, por exemplo «Claude Code no portátil». Uma chave por cliente permite revogar uma sem mexer nas outras. Chave existente dá ao cliente uma chave que criaste antes.
  3. Liga Permitir iniciar backups para uma chave que deva poder iniciar backups. Sem isso só pode ler. Podes mudar isto mais tarde nos Detalhes da chave, e a alteração vale a partir do pedido seguinte do assistente, sem nova ligação.
  4. Clica em Criar chave. A chave é mostrada uma vez. O BombVault guarda apenas uma impressão digital dela e não a pode mostrar outra vez, por isso copia-a agora. Se fechares a janela antes de o cliente ter usado a chave, o cartão continua a mostrá-la até confirmares que a copiaste.

Sem palavra-passe de início de sessão, a própria interface web está aberta a toda a tua rede, e quem a conseguir abrir também pode criar uma chave. O cartão avisa disso. Se abrires o BombVault com um nome que parece público (por exemplo bombvault.example.com atrás de um proxy inverso) e não houver palavra-passe de início de sessão, a partir desse endereço não é possível criar nem substituir chaves, para que nenhuma página da Internet consiga levar o teu navegador a criar uma. Define uma palavra-passe de início de sessão, ou abre o BombVault pelo endereço IP ou por um nome local como tower ou tower.local.

As suas chaves e o registo delas

Cada chave tem a sua própria linha em Chaves e clientes com sessão iniciada. Mostra o nome da chave, se pode iniciar backups ou só ler, os quatro últimos caracteres da chave, quando foi criada ou substituída pela última vez e quando um cliente a usou pela última vez. Detalhes abre uma janela onde mudas o nome da chave, alteras a permissão, substituis a chave ou revogas-a, e que mostra quantas chamadas fez hoje. Uma chave revogada passa para a lista de chaves revogadas, onde a podes apagar de vez quando nenhuma execução do histórico a nomear.

Ao lado do nome, a linha mostra o logótipo do cliente para o qual a chave foi criada. Uma chave criada através de Outro cliente, ou antes de o cartão listar clientes, mostra uma chave no seu lugar.

O Registo nos detalhes de uma chave mostra o que essa chave fez, e uma chave revogada mantém um botão Registo próprio. Primeiro vêm os backups que iniciou, cada um com o seu estado e uma ligação a essa execução no registo de atividade do painel. Por baixo estão as chamadas, das mais recentes para as mais antigas, com a ferramenta e o que aconteceu à chamada. Uma recusa diz porquê: a chave só pode ler, a proteção de retenção travou o backup, já havia outro backup em curso, um backup da entrada foi iniciado fora da interface web há poucos minutos, ou a chave enviou demasiados pedidos. Um cancelamento liga à execução a que se referia.

O BombVault guarda as entradas de cada chave durante 30 dias no máximo: os 500 inícios e cancelamentos bem-sucedidos mais recentes e, ao lado deles, as 200 outras chamadas mais recentes (leituras, recusas e erros). Assim, um assistente que consulta repetidamente um backup em curso, ou que repete uma chamada recusada, não consegue empurrar o seu início para fora do registo. De cada chamada guarda a ferramenta, o resultado e a execução indicada por um cancelamento. Nunca guarda o que o assistente enviou, nem a chave ou a sua impressão digital. O pacote de diagnóstico só conta as entradas, e uma exportação das definições deixa-as de fora.

Ligar um cliente

Escolher um cliente abre uma janela com cada cliente como um mosaico, em Neste computador ou em Na nuvem, e uma pesquisa no canto superior direito. Um mosaico abre a configuração do cliente na mesma janela, em três passos: a chave, a configuração para esse cliente, com o endereço com que abriste o cartão, um botão para a copiar, o sítio onde a configuração fica e, com o certificado próprio do BombVault, o que o cliente precisa para confiar nele. E a espera pela primeira chamada do cliente. A janela acompanha a última utilização da chave e fica verde quando essa chamada chega.

A configuração mantém a chave fora de qualquer linha de comandos. Quando o cliente a consegue ler de uma variável de ambiente (BOMBVAULT_MCP_KEY), de um pedido oculto ou de um ficheiro seu, a configuração apenas a nomeia. Quando o cliente não tem essa forma, a chave fica no ficheiro de configuração ou nas definições dele, e a configuração diz isso. Quando a documentação de um cliente não diz como trata um certificado que não conhece, a configuração escreve esse passo como o que fazer se o cliente recusar o certificado do BombVault.

Cliente Configuração De onde vem a chave
AnythingLLM ficheiro de configuração o ficheiro de configuração
Antigravity ficheiro de configuração variável de ambiente
Claude Code comando ficheiro da chave
Claude Desktop ficheiro de configuração ficheiro da chave
Cline ficheiro de configuração o ficheiro de configuração
Codex CLI ficheiro de configuração variável de ambiente
Continue ficheiro de configuração ~/.continue/.env
Copilot CLI ficheiro de configuração o ficheiro de configuração
Cursor ficheiro de configuração variável de ambiente
Gemini CLI ficheiro de configuração variável de ambiente
GitHub Copilot (VS Code) ficheiro de configuração pedido oculto
Goose ficheiro de configuração variável de ambiente
Jan formulário na app as definições da app
JetBrains (AI Assistant, Junie) ficheiro de configuração o ficheiro de configuração
Kimi Code ficheiro de configuração o ficheiro de configuração
LM Studio ficheiro de configuração o ficheiro de configuração
Mistral Vibe ficheiro de configuração variável de ambiente
Msty formulário na app as definições da app
n8n formulário na app as credenciais do n8n
Open WebUI formulário na app as definições da app
opencode ficheiro de configuração variável de ambiente
Perplexity (Mac) formulário na app ficheiro da chave
Qwen Code ficheiro de configuração variável de ambiente
Roo Code ficheiro de configuração variável de ambiente
Visual Studio ficheiro de configuração o ficheiro de configuração
Warp ficheiro de configuração o ficheiro de configuração
Windsurf ficheiro de configuração variável de ambiente
Zed ficheiro de configuração o ficheiro de configuração
Grok formulário, na nuvem os servidores do fornecedor
Le Chat formulário, na nuvem os servidores do fornecedor
ChatGPT autenticação por OAuth, na nuvem um token de acesso, ver abaixo
Claude (claude.ai) autenticação por OAuth, na nuvem um token de acesso, ver abaixo

As secções abaixo explicam com mais pormenor a configuração do Claude Code e do Claude Desktop e indicam o que qualquer outro cliente precisa.

Claude Code

O Claude Code chega ao BombVault através do mcp-remote, que precisa de Node.js nesse computador. Primeiro guarda a chave num ficheiro de texto à parte, numa única linha:

X-API-Key: <your key>

Depois executa uma vez num terminal o comando do cartão, com o caminho desse ficheiro. Atrás de um certificado em que o teu computador confia, fica assim:

claude mcp add bombvault --scope user -- npx -y mcp-remote@latest https://bombvault.example.com/mcp --header-file "<path of the file with your key>"

Com o certificado próprio do BombVault (ver TLS e certificados), o comando indica também ao Node.js o certificado descarregado:

claude mcp add bombvault --scope user -e "NODE_EXTRA_CA_CERTS=<path of the downloaded bombvault-cert.pem>" -- npx -y mcp-remote@latest https://192.168.1.10:3443/mcp --header-file "<path of the file with your key>"

Verifica a ligação com /mcp dentro do Claude Code. --scope user torna o BombVault disponível em todos os teus projetos. O Claude Code guarda só o caminho do ficheiro da chave, por isso a chave não aparece no comando nem no histórico da shell, nem na lista de processos. Guarda o ficheiro onde mais ninguém o possa ler, e fora de qualquer pasta de que faças commit. @latest faz o npx ir buscar um mcp-remote atual. Caso contrário seria usado um mais antigo instalado globalmente, que não conhece --header-file.

Não escrevas ${BOMBVAULT_MCP_KEY} nos argumentos do mcp-remote para o Claude Code. O Claude Code substitui essa referência a partir do seu próprio ambiente antes de iniciar o mcp-remote, por isso a chave acaba na linha de comandos desse processo, onde outros programas e utilizadores do computador a podem ler.

Sem Node.js, e só atrás de um certificado em que o teu computador confia, o Claude Code consegue ligar-se sozinho. Coloca um .mcp.json na pasta do projeto:

{
  "mcpServers": {
    "bombvault": {
      "type": "http",
      "url": "https://bombvault.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${BOMBVAULT_MCP_KEY}"
      }
    }
  }
}

Define BOMBVAULT_MCP_KEY onde o Claude Code arranca, por exemplo em "env" no ~/.claude/settings.json ou no perfil da tua shell, editado num editor de texto em vez de escrito na linha de comandos. Aqui a referência é segura, porque o Claude Code não inicia um segundo processo que a leve consigo. O certificado próprio do BombVault não funciona desta forma: a ligação que o próprio Claude Code abre recusa-o, mesmo com NODE_EXTRA_CA_CERTS definido. Nunca faças commit de um .mcp.json com a chave escrita lá dentro.

Claude Desktop

O Claude Desktop chega ao BombVault através do mcp-remote, que precisa de Node.js nesse computador. Guarda primeiro a chave num ficheiro de texto próprio, numa única linha, como descrito para o Claude Code. Abre o ficheiro de configuração no Claude Desktop em Settings, Developer, Edit Config. Fica em %APPDATA%\Claude\claude_desktop_config.json no Windows e em ~/Library/Application Support/Claude/claude_desktop_config.json no macOS. Acrescenta a entrada do cartão dentro de "mcpServers", ao lado dos servidores que já lá estejam, e reinicia o Claude Desktop:

{
  "mcpServers": {
    "bombvault": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://192.168.1.10:3443/mcp", "--header-file", "<path of the file with your key>"],
      "env": {
        "NODE_EXTRA_CA_CERTS": "<path of the downloaded bombvault-cert.pem>"
      }
    }
  }
}
  • NODE_EXTRA_CA_CERTS só está lá para o certificado próprio do BombVault. Atrás de um certificado em que o teu computador já confia, retira-o.
  • --allow-http só é acrescentado para um endereço http:// simples.
  • No Windows, escreve os caminhos com barras normais, por exemplo C:/Users/sam/bombvault-key.txt, porque uma barra invertida sozinha não é JSON válido. Mantém o caminho do ficheiro da chave sem espaços: o Claude Desktop no Windows passa ao npx um caminho com um espaço em dois pedaços.
  • A configuração só indica o ficheiro da chave, por isso a chave não aparece nela nem na lista de processos. Guarda o ficheiro onde mais ninguém o possa ler.

Clientes na nuvem

O ChatGPT, o Claude em claude.ai, o Grok e o Le Chat chamam o BombVault a partir dos servidores do seu fornecedor, por isso o BombVault tem de estar acessível a partir da Internet com um certificado de confiança pública, por exemplo atrás de um proxy inverso. O Le Chat recusa certificados autoassinados. Um início de sessão no proxy pode proteger a interface web, mas /mcp tem de chegar ao BombVault sem ele: estes serviços não conseguem iniciar sessão num proxy, e o BombVault verifica ele próprio a chave ou o token. O Grok e o Le Chat enviam uma chave fixa, e os seus botões configuram-nos como os outros. O ChatGPT, e o Claude em claude.ai na maioria das organizações, só se ligam através de uma autenticação por OAuth, descrita a seguir.

Autenticação por OAuth

Para um cliente que não aceita uma chave, o BombVault é o seu próprio servidor de autorização OAuth. O cliente regista-se sozinho, envia-te para uma página do BombVault, e aí entras com a tua palavra-passe de acesso (e o segundo fator, se o configuraste) e autoriza-lo. O cliente recebe depois um token que só serve para o endpoint MCP deste BombVault, e renova-o sozinho.

  1. Define uma palavra-passe de acesso em Definições, Segurança. Sem ela o BombVault não oferece nenhuma autenticação, porque não haveria ninguém a quem pedir consentimento.
  2. Torna o BombVault acessível a partir da Internet por https com um certificado em que os browsers confiem, normalmente através de um proxy inverso. O cliente chama /mcp, /oauth/ e /.well-known/ a partir dos seus próprios servidores, por isso um proxy com início de sessão próprio tem de deixar passar esses três caminhos até ao BombVault. A página de consentimento em /oauth/authorize abre no teu próprio browser e pode ficar atrás do início de sessão do proxy. Indica também o proxy em TRUSTED_PROXY (ver Configuração). O BombVault limita os registos de clientes por endereço e, sem isso, todos os clientes parecem vir do proxy.
  3. No cartão MCP, liga Autenticação por OAuth e introduz o Endereço público: o endereço https sem caminho, por exemplo https://backup.example.com. Cada token fica ligado a este endereço, por isso após uma alteração cada cliente tem de se autenticar de novo.
  4. Escolhe o ChatGPT ou o Claude em Escolher um cliente. A janela mostra o URL do conector, ou seja, o endereço público seguido de /mcp, e onde entra nesse cliente. No ChatGPT, liga o modo de programador em Definições, Apps e conectores, Definições avançadas, escolhe Criar, cola o URL do conector como URL do servidor MCP e escolhe OAuth como autenticação. Em claude.ai, abre Definições, Conectores, Adicionar conector personalizado, cola o URL do conector, deixa vazios o ID de cliente e o segredo OAuth e escolhe Ligar.
  5. O cliente abre a página de consentimento. Mostra quem pede, para onde a tua resposta te leva de volta e o interruptor Permitir iniciar backups, que começa desligado. Escolhe Permitir ou Recusar.

Cada cliente autenticado recebe uma linha própria na mesma lista, com o seu logótipo. Os seus Detalhes guardam o seu registo, Revogar e Permitir iniciar backups, e tem os mesmos limites de uma chave. A revogação tem efeito imediato. Quando o mesmo cliente se autentica de novo, a nova autorização substitui a anterior, e uma autorização que ninguém usou durante 30 dias expira. Podem estar autenticados até 10 clientes ao mesmo tempo, além das 10 chaves.

A página de consentimento só aceita um pedido de um cliente registado que indique exatamente um dos seus endereços de regresso registados: https, ou um endereço de loopback em qualquer porta para um cliente no teu próprio computador. Só é aceite o fluxo de código de autorização com PKCE (S256), e a tua resposta fica ligada à tua sessão, por isso nenhum outro site a pode enviar por ti. Os tokens de acesso duram uma hora. Um token de atualização é substituído a cada utilização, e se voltar a aparecer depois, o BombVault revoga a autorização, porque outra pessoa tem uma cópia. Um cliente que repete a sua última atualização em menos de 30 segundos, porque a resposta nunca lhe chegou, recebe em vez disso tokens novos. O BombVault não descarrega metadados de clientes da Internet, por isso os clientes registam-se através do registo dinâmico de clientes.

Outros clientes

Serve qualquer cliente que fale Streamable HTTP:

  • URL: o endereço da interface web mais /mcp, por exemplo https://192.168.1.10:3443/mcp.
  • A chave em Authorization: Bearer <key> ou em X-API-Key: <key>. Se forem enviados os dois, têm de levar a mesma chave.
  • POST com Content-Type: application/json e Accept: application/json, text/event-stream.
  • Uma mensagem JSON-RPC por pedido. Os lotes (batches) são recusados.
  • Versões do protocolo 2026-07-28, 2025-11-25, 2025-06-18 e 2025-03-26.

TLS e certificados

O BombVault serve HTTPS com um certificado emitido por ele próprio, e de início esse certificado só nomeia localhost, 127.0.0.1 e ::1. O Claude Code e o mcp-remote recusam-no num endereço da rede local. As saídas, pela ordem que serve à maioria das instalações Unraid:

  1. Acrescentar o endereço no cartão MCP. Se abrir o cartão por HTTPS num endereço que o certificado não nomeia, ele avisa e oferece Acrescentar este endereço ao certificado. O BombVault emite de novo o certificado com esse endereço (o navegador avisa mais uma vez, como da primeira). Depois clica em Descarregar certificado. Os excertos definem NODE_EXTRA_CA_CERTS para o ficheiro descarregado, e o cliente passa a confiar exatamente nesse certificado. Isto também significa que qualquer cliente configurado com um ficheiro descarregado antes deixa de se ligar assim que o certificado é emitido de novo, neste computador e em todos os outros, até receber o ficheiro novo.
  2. Um proxy inverso com um certificado de confiança (Nginx Proxy Manager, SWAG, Caddy, Traefik). O cliente vê então o certificado do proxy e não precisa de mais nada, e o cartão não avisa sobre o do BombVault.
  3. Tailscale. tailscale serve à frente do contentor, ou a integração Tailscale do Unraid, dá-lhe um nome ts.net com um certificado de confiança.
  4. HTTP_ONLY=true, só atrás de um proxy que termine o TLS ou numa rede em que confie totalmente. Passa toda a interface web para HTTP simples, exige uma alteração nas definições do contentor e envia a chave sem cifra.

Nunca definas NODE_TLS_REJECT_UNAUTHORIZED=0. Isso desliga a verificação de certificados para tudo aquilo com que esse processo Node.js fala.

Um proxy inverso tem de deixar passar o cabeçalho Authorization (ou X-API-Key), o que os proxies fazem a menos que lhes digam o contrário, e não pode reter em buffer nem reescrever /mcp. Um bloco location para Nginx ou Nginx Proxy Manager que também verifica o certificado do BombVault:

location /mcp {
    proxy_pass https://192.168.1.10:3443;
    proxy_ssl_verify on;
    proxy_ssl_trusted_certificate /data/bombvault-cert.pem;
    proxy_ssl_name localhost;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_set_header Host $host;
}

Atrás de um proxy, cada pedido traz o endereço do proxy. Cinco chaves erradas vindas de um único cliente mal configurado bloqueiam então durante um minuto todos os clientes MCP atrás desse proxy. Indica o proxy em TRUSTED_PROXY (ver Configuração) para contar por cliente.

Modelo de segurança

  • Sem uma chave ativa e com a autenticação por OAuth desligada, /mcp responde 404.
  • A autenticação por OAuth só é oferecida enquanto houver uma palavra-passe de acesso. Tokens, códigos e segredos de cliente são guardados apenas como impressão digital, e um token só serve para o endereço para o qual foi emitido.
  • Um cliente pode registar-se no máximo 10 vezes por hora a partir do mesmo endereço, e o BombVault guarda no máximo 100 clientes registados com que ninguém se autenticou, cada um durante um dia. Códigos e tokens de atualização errados contam para o mesmo bloqueio que as chaves erradas.
  • As autorizações comportam-se como as chaves ao restaurar um backup da configuração ou ao mudar o APP_KEY: após um restauro, cada cliente tem de se autenticar de novo.
  • Nenhum endereço está isento. Pedidos vindos de localhost, do anfitrião Unraid, de um proxy inverso ou de tailscale serve precisam de uma chave como qualquer outro, também quando a interface web não tem palavra-passe de início de sessão.
  • As chaves só são guardadas como impressão digital, mostradas uma vez, e podem ser renomeadas, substituídas e revogadas. Até 10 chaves ativas, cada uma com o seu interruptor Permitir iniciar backups.
  • Cada criação, substituição, mudança de permissão e revogação envia uma notificação pelos seus canais de notificação, com o endereço de onde veio, a não ser que as notificações estejam desligadas.
  • 5 chaves erradas por minuto e por endereço, depois 429. 120 pedidos por minuto e 12 backups iniciados por hora e por chave, mais a espera e a proteção da retenção descritas acima.
  • Pedidos de uma página de navegador de outra origem são recusados.
  • Enquanto não houver palavra-passe de início de sessão, não é possível criar chaves a partir de um nome de anfitrião que pareça público.
  • Cada backup que um assistente inicia, e as execuções de prune e de cópia externa que daí resultam, fica marcado "via MCP" com o nome da chave no registo de atividade, no painel de erros e na notificação do backup.
  • Cada chamada a uma ferramenta é escrita no registo do contentor com o id da chave e os seus últimos quatro caracteres (nunca o nome) e contada em /metrics (bombvault_mcp_requests_total, bombvault_mcp_tool_calls_total, bombvault_mcp_active_keys).
  • Restaurar um backup da configuração revoga todas as chaves, porque a base de dados restaurada pode conter chaves que revogaste depois de ela ter sido guardada. Cria chaves novas a seguir.
  • Uma chave deixa de funcionar quando APP_KEY muda (uma reinstalação, ou um restauro noutro contentor). O cartão deteta isso e marca a chave, e Substituir chave volta a dar-lhe um segredo válido.
  • Trata uma chave como uma palavra-passe. Um cliente que não consegue ler a chave de uma variável de ambiente, de um pedido ou de um ficheiro da chave guarda-a em texto simples na sua configuração ou nas suas definições, e a configuração dele diz isso. Num computador em que confias menos, prefere uma chave só de leitura.

O que sai da máquina

Tudo o que um assistente lê vai para o fornecedor de IA por trás dele: nomes das entradas, agendamentos, histórico de execuções com mensagens de erro, ids e horas dos pontos de restauro, nomes dos motores de base de dados e tamanhos dos dumps, atividade em curso, números de armazenamento, cobertura e estado. Uma pesquisa de arquivos envia também os arquivos que encontra: os nomes, os tamanhos e os caminhos dentro do backup. O BombVault retira caminhos do anfitrião, localizações dos repositórios, nomes de anfitrião, credenciais, comandos de hook e chaves antes de alguma coisa sair.

Resolução de problemas

O que vê O que significa
404 Não há nenhuma chave ativa e a autenticação por OAuth está desligada, ou o caminho está errado, como /api/mcp. O endpoint é /mcp.
401 A chave falta, está mal escrita, revogada ou substituída. Pode ser que um proxy descarte o cabeçalho Authorization (experimenta X-API-Key). Se o cartão marcar a chave como já não válida, APP_KEY mudou: substitui a chave.
403 O pedido veio de uma página de navegador de outra origem. Usa um cliente de secretária ou de linha de comandos.
405 em GET Normal. O ponto de ligação só aceita POST.
400 "Accept must contain both 'application/json' and 'text/event-stream'" O cliente é demasiado antigo para Streamable HTTP. Atualiza-o.
400 "batch requests are not accepted" O cliente envia lotes JSON-RPC. Envie uma mensagem por pedido.
429 Demasiadas chaves erradas deste endereço, ou mais de 120 pedidos por minuto com uma chave. Espera um minuto e verifica se o assistente está preso num ciclo.
Erros com "certificate", "self-signed" ou "unable to verify" O cliente não confia no certificado do BombVault. Ver TLS e certificados.
busy Outro backup ou uma tarefa de manutenção ocupa essa secção. Tenta de novo quando terminar.
cooldown Esta entrada, esta secção ou o Backup total foi iniciado fora da interface web há menos de 15 minutos.
retention_guard Mais um backup MCP deixaria só pontos de restauro vindos de MCP numa janela "manter os últimos N", ou a entrada já recebeu 4 backups por MCP nas últimas 24 horas, contando os que falharam e os cancelados. No primeiro caso o próximo backup agendado abre espaço, no segundo a entrada fica livre outra vez 24 horas depois do mais antigo desses backups. Em qualquer dos casos podes iniciá-lo na interface web.
rate_limited A chave gastou os seus 12 inícios desta hora.
not_permitted num início A chave é só de leitura. Liga Permitir iniciar backups no cartão. Não é preciso voltar a ligar. Num cancelamento significa que a execução não foi iniciada por esta chave.
domain_off Essa secção está desligada em Definições, Geral.
not_found O BombVault não protege essa entrada. Acrescenta-a primeiro na interface web. O MCP nunca cria configuração.
O cliente não encontra o servidor de autorização A autenticação por OAuth está desligada, não há palavra-passe de acesso, ou o proxy não deixa passar /.well-known/ até ao BombVault.
A página de consentimento diz que o endereço de regresso não está registado O cliente enviou um endereço de regresso que não registou. Remove o conector no cliente e volta a adicioná-lo.
Um cliente autenticado recebe 401 A sua autorização foi revogada, expirou após 30 dias sem uso, ou o endereço público mudou. O cliente autentica-se de novo.

Não definas a variável de ambiente MCPGODEBUG no contentor. Altera o comportamento da biblioteca MCP, e um valor mal formado para o BombVault no arranque antes de escrever uma única linha de registo.