SikkerKey

Servidor MCP

Conecte clientes de IA compatíveis com MCP ao SikkerKey por meio de uma identidade de agente de IA dedicada, com escopo definido, auditada e que não enxerga texto puro.

O servidor MCP do SikkerKey conecta clientes de IA compatíveis com MCP ao plano de gerenciamento do SikkerKey. Ele permite que um assistente de IA ajude a administrar projetos, metadados de segredos, políticas, máquinas, alertas, atividades de auditoria e outras operações do cofre por meio de uma identidade dedicada de agente de IA.

O servidor MCP é cego para leitura de valores de segredos armazenados. Ele pode criar ou substituir valores que você forneça deliberadamente, mas nenhuma ferramenta pode recuperar o texto puro de um segredo armazenado existente.

---

Como funciona

O servidor MCP é executado localmente como um processo filho do seu cliente de IA e se comunica com ele por meio da entrada e saída padrão. Quando a IA invoca uma ferramenta do SikkerKey, o servidor assina a solicitação correspondente à API do SikkerKey com a identidade do agente de IA selecionado.

• Identidade local. A chave privada Ed25519 do agente de IA é gerada e armazenada no seu computador. Apenas a chave pública é registrada no SikkerKey.
• Solicitações assinadas. Cada solicitação cobre o método HTTP, caminho, carimbo de data/hora, nonce de uso único e hash do corpo da solicitação. Uma solicitação modificada ou repetida falha na verificação.
• Autorização com escopo. Os escopos de gerenciamento controlam operações em todo o cofre. Uma função de acesso controla os aplicativos, projetos, tipos de segredos, operações de máquina e capacidades de políticas que o agente pode alcançar.
• Vínculo com o criador ativo. O acesso efetivo do agente nunca pode exceder o acesso atual da pessoa que o criou. Se o acesso dessa pessoa for reduzido ou removido, as permissões do agente diminuem na próxima solicitação.
• Atribuição completa. Cada alteração bem-sucedida é registrada no Log de Auditoria sob a identidade do agente de IA.

---

Requisitos

• Um cofre SikkerKey
• Permissão para provisionar um agente de IA no cofre
• Um cliente de IA compatível com MCP
• Uma plataforma de desktop ou servidor compatível

O servidor empacotado suporta Linux em x64 e arm64, macOS em x64 e Apple silicon, e Windows em x64. Ele funciona com qualquer cliente MCP que possa iniciar um servidor via stdio.

Clientes com configuração gerada

• Claude Code
• Claude Desktop
• Cursor
• Codex

---

Instalar o servidor

Instale o comando globalmente com npm:

npm install -g sikkerkey-mcp

Você também pode executar um comando sem instalação global:

npx sikkerkey-mcp <subcommand>

---

Configurar um agente de IA

No painel do SikkerKey, abra Máquinas → Agentes de IA e escolha Inicializar agente de IA.

Escolha os escopos de gerenciamento e a função de acesso que o agente deve receber e copie o token de inicialização de uso único.

Registre a identidade no computador que executará o servidor MCP.

Aprove o agente de IA pendente no painel.

Gere a configuração para o seu cliente de IA, cole-a no arquivo de configuração indicado e reinicie o cliente.

Peça ao cliente conectado para chamar whoami e confirme o cofre, escopos, acesso a projetos e status do agente exibidos.

Registrar a identidade

sikkerkey-mcp install <bootstrap-token>

Adicione um nome de exibição local opcional durante o registro:

sikkerkey-mcp install <bootstrap-token> -name="Operations assistant"

O registro gera um par de chaves Ed25519 localmente e armazena a identidade em:

~/.sikkerkey/agents/<agent-id>/

O diretório do agente, o arquivo de identidade e a chave privada são criados com permissões restritas. O agente permanece pendente até que você o aprove pelo painel.

Gerar configuração do cliente

sikkerkey-mcp config claude-code
sikkerkey-mcp config claude-desktop
sikkerkey-mcp config cursor
sikkerkey-mcp config codex

Cada comando imprime um bloco de configuração pronto para colar e o local usado por esse cliente. A configuração gerada inicia sikkerkey-mcp serve e seleciona o agente com SIKKERKEY_AGENT_ID.

Use uma identidade de agente de IA separada para cada cliente, ambiente de automação ou limite de confiança. Isso mantém as permissões e a atribuição no Log de Auditoria fáceis de revisar.

---

Verificar a conexão

Após reiniciar o cliente de IA, peça a ele para usar whoami. Esta chamada está sempre disponível e relata:

• O ID e o nome do agente de IA
• Status de aprovação e habilitação
• Escopos de gerenciamento concedidos
• A função de acesso e os aplicativos e projetos alcançáveis
• Capacidades por projeto
• As 20 entradas de auditoria mais recentes atribuídas ao agente

Use whoami no início de uma sessão sensível ou após alterar a função do criador, os escopos do agente ou sua função de acesso.

---

O que as ferramentas podem gerenciar

Você pode descrever o resultado desejado em linguagem natural. O cliente de IA seleciona a ferramenta e a ação apropriadas, enquanto o SikkerKey verifica independentemente a autorização atual do agente para cada solicitação.

Ferramenta	Finalidade
whoami	Confirmar o agente ativo, permissões, acesso a projetos, status e atividade recente atribuída.
manage_projects	Navegar pelos aplicativos e projetos que o agente pode alcançar.
manage_secrets	Gerenciar metadados de segredos, valores, versões, rotação e segredos gerenciados agendados nos projetos permitidos.
manage_temporary_secrets	Criar e inspecionar compartilhamentos de segredos de uso único e autodestrutivos.
manage_policies	Criar e gerenciar políticas de acesso e seus vínculos de segredos.
manage_canaries	Plantar, configurar, armar ou desarmar segredos canários e recuperar projetos congelados.
manage_machines	Listar, inspecionar, aprovar, negar, renomear ou revogar identidades de máquinas.
manage_project_machines	Vincular máquinas a projetos e gerenciar suas concessões explícitas por segredo.
manage_enrollment	Emitir, inspecionar e revogar tokens de inscrição para máquinas efêmeras.
manage_ai_agents	Inspecionar e gerenciar o estado do ciclo de vida do agente de IA, nomes e aprovações.
manage_alerts	Escolher quais ações de auditoria acionam alertas.
manage_webhooks	Criar e gerenciar webhooks assinados de entrega de alertas.
manage_ipallowlist	Gerenciar a lista de permissões de IP do cofre usada pela autenticação e inscrição de máquinas.
manage_trash	Listar, restaurar ou purgar permanentemente segredos com exclusão suave.
read_audit	Consultar atividade, exportar evidências de auditoria e revisar estatísticas de uso.
support	Abrir, ler, responder e avaliar tickets de suporte.
manage_sdks	Consultar orientações de instalação e início rápido para SDKs oficiais de runtime.

As ferramentas exibidas a um cliente de IA são estáveis, mas uma ação individual só é bem-sucedida quando o agente selecionado tem o escopo e a capacidade de projeto necessários no momento da chamada.

---

Escopos de gerenciamento e acesso a projetos

Um agente de IA recebe dois conjuntos de permissões complementares.

Escopos de gerenciamento

Os escopos de gerenciamento controlam áreas de todo o cofre, como máquinas, agentes de IA, inscrição, auditoria, alertas, webhooks, lista de permissões de IP, Lixeira e suporte. Escopos de leitura e escrita podem ser concedidos separadamente onde o recurso os suporta.

Função de acesso

A função de acesso controla o plano de projetos. Ela decide quais aplicativos e projetos independentes aparecem para o agente e o que ele pode fazer em cada projeto, incluindo tipos de segredos permitidos, vinculação e concessões de máquinas, políticas e canários.

O SikkerKey cruza ambos os conjuntos de permissões com o acesso atual do usuário criador em cada solicitação. O agente não pode usar ferramentas MCP para substituir seus próprios escopos de gerenciamento ou função de acesso.

Comece com o menor conjunto de escopos e capacidades de projeto que cubra o fluxo de trabalho pretendido. Adicione acesso posteriormente pelo painel quando o agente realmente precisar.

---

Como os valores de segredos armazenados são tratados

A superfície MCP separa a administração de segredos da recuperação de segredos em runtime.

• Leituras de metadados. Listar um segredo, abrir seus detalhes ou visualizar seu histórico de versões retorna identificadores, nomes, tipos, nomes de campos, notas, versões e carimbos de data/hora — não valores armazenados.
• Criar e atualizar. Quando você fornece deliberadamente um valor para criação ou substituição, esse valor passa pelo cliente de IA na solicitação de escrita assinada e é criptografado pelo SikkerKey. A resposta retorna metadados e não ecoa o valor.
• Rotação gerada pelo servidor. A rotação e a criação de segredos gerenciados podem gerar o novo valor dentro do SikkerKey. A IA recebe a nova versão e os metadados de agendamento, não o texto puro gerado.
• Recuperação em runtime. Os aplicativos leem segredos por meio de um SDK oficial ou da CLI usando uma identidade de máquina separada. Uma identidade de agente de IA não pode autenticar como máquina.

Coloque um valor em texto puro em uma conversa de IA somente quando você intencionalmente quiser que esse cliente de IA o envie em uma escrita de segredo. Após o armazenamento, o MCP não pode ler o valor de volta.

Credenciais de uso único

Algumas ações de gerenciamento retornam credenciais recém-geradas uma única vez para que você possa concluir sua configuração. Isso inclui tokens de inscrição, um novo segredo de assinatura de webhook e o token e a frase secreta para um compartilhamento temporário de segredo. Armazene ou entregue-os no momento da criação; ações posteriores de listagem e detalhes não os revelam.

Um compartilhamento temporário de segredo é destinado a um destinatário humano. Abrir seu link consome a revelação de uso único, então a IA deve entregar os detalhes do compartilhamento em vez de abrir o link.

---

Auditoria, aprovação e revogação

O SikkerKey registra cada ação de gerenciamento com o ID e o nome do agente de IA. Você pode revisar a atividade pelo Log de Auditoria do painel ou por meio de read_audit. Regras de alerta e webhooks podem notificá-lo quando ações selecionadas do agente ocorrerem.

Seu cliente de IA controla seus próprios prompts de confirmação antes de enviar uma chamada de ferramenta. Configure esse cliente para exigir confirmação para alterações que merecem revisão humana, particularmente exclusão permanente, alterações de acesso, revogação de máquina, alterações de políticas, alterações na lista de permissões de IP e mensagens entregues externamente.

Desabilitar ou revogar um agente

• Desabilitar. Recusa imediatamente as solicitações assinadas do agente, preservando seus escopos e função de acesso para reabilitação posterior.
• Revogar. Exclui a identidade do agente de IA no lado do servidor e torna o par de chaves local inutilizável para solicitações futuras.

Ambos entram em vigor na próxima solicitação. Gerencie o ciclo de vida no lado do servidor pelo painel. Após a revogação, remova o slot de identidade local:

sikkerkey-mcp revoke <agent-id>

O comando de revogação local remove arquivos deste computador. Ele não revoga o agente de IA no painel do SikkerKey.

---

Usar mais de um agente de IA

Um computador pode armazenar várias identidades de agentes de IA. Liste as identidades locais registradas com:

sikkerkey-mcp whoami

A configuração gerada do cliente cria uma entrada de servidor separada para cada identidade. Se você configurar o servidor manualmente, defina SIKKERKEY_AGENT_ID para o agente exato que esse cliente deve usar:

{
  "mcpServers": {
    "sikkerkey": {
      "command": "sikkerkey-mcp",
      "args": ["serve"],
      "env": {
        "SIKKERKEY_AGENT_ID": "agent_..."
      }
    }
  }
}

Quando exatamente uma identidade está instalada, o servidor a seleciona automaticamente. Quando várias existem e nenhum ID de agente está configurado, a inicialização para e pede que você escolha, em vez de selecionar uma implicitamente.

---

Variáveis de ambiente

Variável	Finalidade
SIKKERKEY_AGENT_ID	Selecionar a identidade local do agente de IA usada pelo servidor MCP.
SIKKERKEY_HOME	Alterar a raiz de identidade local do SikkerKey do padrão ~/.sikkerkey.

---

Referência de comandos

Comando	Finalidade
sikkerkey-mcp install <token>	Registrar uma nova identidade local de agente de IA a partir de um token de painel de uso único.
sikkerkey-mcp whoami	Listar identidades de agentes de IA registradas localmente.
sikkerkey-mcp config <client>	Imprimir configuração para Claude Code, Claude Desktop, Cursor ou Codex.
sikkerkey-mcp serve	Executar o servidor MCP via stdio.
sikkerkey-mcp revoke [agent-id]	Remover um slot de identidade local de agente de IA.
sikkerkey-mcp	Executar o servidor MCP; equivalente a serve.

---

Código-fonte e licença

O servidor MCP do SikkerKey é totalmente open source sob a Licença MIT. Revise a autenticação, o armazenamento de identidade, o tratamento de protocolo, os esquemas de ferramentas e o comportamento de solicitações por meio da organização SikkerKeyOfficial no GitHub.