Engenharia Webship

Ligar com segurança os Agentes de IA ao Servidor MCP da Webship

Configure o plano de controlo isolado de Webship com MCP usando TLS 1.3, um token de portador forte, ligação de loopback, um túnel SSH, validação de configuração e uma lista de verificação prática de resposta a incidentes.

Publicado 10 de setembro de 2026

# Ligar com segurança os Agentes de IA ao Servidor MCP da Webship

Uma ligação MCP a um servidor web não é um widget de chat. É uma interface de operações que pode inspecionar o estado de produção, alterar a política de encaminhamento e segurança, recarregar certificados, ativar lançamentos estáticos, coordenar alterações na frota e instalar uma atualização assinada Webship.

Trate-o em conformidade: como uma API administrativa privilegiada. A configuração Webship mais segura mantém o ouvinte MCP fora do plano de dados público, liga-o ao loopback, protege-o com TLS 1.3 e um token bearer forte, e acede a ele através de um túnel SSH autenticado.

Este guia cria essa configuração, explica por que cada limite existe e dá-lhe uma lista de verificação para operá-la sem transformar conveniência em exposição.

Comece com a fronteira de confiança

O tráfego público de Webship e o tráfego de MCP usam listeners separados. O plano de controlo de MCP está desativado por defeito e nunca partilha o listener normal de HTTP, HTTP/2, HTTP/3 ou WebTransport. Quando ativado, serve MCP através de um endpoint dedicado de TLS 1.3 HTTP/1.1.

Uma implementação segura tem quatro controlos independentes:

Acessibilidade da rede: o ouvinte MCP liga-se a 127.0.0.1, não a um endereço público ou da LAN privada.
Identidade de transporte: o cliente verifica um certificado emitido por uma CA em que confia.
Autenticação da aplicação: cada pedido transporta um token bearer forte.
Acesso administrativo: os operadores acedem ao ouvinte loopback através de uma conta SSH autenticada e túnel.

Nenhum destes controlos substitui outro. TLS sem um caminho de rede privado continua a expor uma superfície de autenticação. Um túnel sem verificação de certificado torna a identidade do ponto final ambígua. Um token de portador dentro de um ficheiro legível por todos não é um segredo.

Prepare o certificado e o token

Emita um certificado dedicado MCP a partir da sua CA interna. Para o túnel mostrado abaixo, inclua localhost e 127.0.0.1 nos nomes alternativos do sujeito do certificado, e depois instale a CA emissora no armazenamento de confiança da máquina cliente MCP. Não resolva um erro de confiança com uma opção TLS insegura.

Crie um token único com pelo menos 32 bytes ASCII imprimíveis e sem espaços em branco. Um valor aleatório de 32 bytes codificado em hexadecimal fornece-lhe 64 caracteres seguros:

umask 077
openssl rand -hex 32

Webship lê atualmente o token MCP diretamente da configuração protegida TOML; token_file não é suportado. Armazene o resultado num ficheiro de configuração legível apenas pela conta de serviço Webship e pelo seu grupo administrativo. Não coloque o token numa unidade systemd, histórico de shell, ticket, mensagem de chat ou prompt enviado a um modelo de IA.

Num host Debian típico:

sudo chown root:webship /etc/webship/production.toml
sudo chmod 0640 /etc/webship/production.toml
sudo chown root:webship /etc/webship/mcp-cert.pem /etc/webship/mcp-key.pem
sudo chmod 0644 /etc/webship/mcp-cert.pem
sudo chmod 0640 /etc/webship/mcp-key.pem

Adapte o utilizador e o grupo do serviço à sua instalação. A chave privada e a configuração devem ser legíveis por Webship, mas não por contas não relacionadas.

Ativar o ouvinte isolado

Adicione esta secção à configuração ativa Webship:

[security.mcp]
enabled = true
listen = "127.0.0.1:9443"
token = "replace-with-your-generated-64-character-token"
allowed_ips = []
expose_remote = false

[security.mcp.tls]
cert = "/etc/webship/mcp-cert.pem"
key = "/etc/webship/mcp-key.pem"

Uma lista allowed_ips vazia não abre o endpoint. Os clientes loopback continuam permitidos por defeito. expose_remote = false torna a fronteira pretendida explícita: se alguém mais tarde alterar listen para um endereço não loopback, Webship rejeita a configuração em vez de publicar silenciosamente o plano de controlo.

Webship também rejeita um ouvinte MCP ativado sem TLS, sem um token, com um token curto ou que contenha espaços, ou com caminhos de certificados vazios. Tokens públicos de marcador são rejeitados antes da exposição remota.

Validar antes de reiniciar

MCP listener, identidade TLS e alterações de token recompõem o plano de controlo, pelo que requerem um reinício do processo. Valide primeiro a configuração completa:

/usr/local/bin/webship --check-config --config /etc/webship/production.toml
sudo systemctl restart webship
sudo systemctl status webship --no-pager

Confirme que o ouvinte existe apenas na interface de loopback:

ss -ltn | grep '127.0.0.1:9443'

Não adicione a porta 9443 às regras públicas do firewall do anfitrião. O próximo passo acede a ela através de SSH.

Criar o túnel privado

A partir da estação de trabalho do administrador, encaminhe uma porta local para o ouvinte de loopback de Webship:

ssh -N \
  -L 127.0.0.1:19443:127.0.0.1:9443 \
  webship-admin@edge.example.com

O cliente MCP agora conecta-se a https://localhost:19443/mcp. O TCP alcança o servidor SSH, o SSH transporta a ligação para o anfitrião, e o anfitrião abre a ligação final para Webship no loopback. Fechar a sessão SSH remove esse caminho imediatamente.

Use autenticação SSH baseada em chave, restrinja quais administradores podem abrir o túnel e aplique os seus controlos normais de acesso ao host. Se for necessário um host de salto, mantenha o ouvinte MCP na interface loopback do host Webship e prolongue o caminho SSH em vez de alargar o ouvinte.

Configure o cliente MCP

Os formatos de configuração do cliente diferem, mas uma entrada típica de HTTP MCP é assim:

{
  "mcpServers": {
    "webship-production": {
      "url": "https://localhost:19443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Use o mecanismo de segredo protegido do cliente quando este o tiver. Caso contrário, restrinja a configuração do cliente à conta do sistema operativo atual. O cliente HTTP—não o modelo—deve anexar o cabeçalho de autorização. Nunca cole o token em uso numa conversa.

Mantenha a verificação do certificado ativada. Se o cliente rejeitar o certificado, repare os nomes alternativos do assunto do certificado ou instale a CA interna correta. Não adicione uma bypass permanente.

Tornar a primeira sessão apenas de leitura

Após o túnel e o cliente serem conectados, comece com a descoberta e a inspeção:

Peça tools/list; a sua resposta é o esquema de argumento autorizado para a versão em execução.
Chame webship.get_config e registe a versão de configuração atual.
Inspecione webship.reverse_proxy.get_status, webship.security.get_status, webship.ddos.get_status e webship.tls.get_status conforme aplicável.
Use webship.policy.explain ou webship.security.simulate antes de alterar uma política.
Confirme que a configuração devolvida oculta tokens de portador.

Só então teste uma mutação num ambiente que não seja de produção. As mutações de configuração do Webship exigem o ID da versão atual. Uma escrita desatualizada é rejeitada em vez de sobrescrever uma alteração mais recente. A política candidata pode ser verificada com verificação sombra e cenários de laboratório de tráfego antes da ativação.

Webship também rejeita reduções de segurança em tempo real selecionadas. Um pedido MCP não pode desligar um WAF ativo, camada DDoS, API Shield, desafio de bots, política de autenticação de borda ou camada de cabeçalho de resposta. Alterações vinculadas a listener, protocolo, worker, runtime e autenticação MCP exigem um reinício deliberado.

Esses guardas reduzem erros; eles não tornam cada ação autorizada inofensiva. O token concede uma superfície de controlo poderosa, incluindo operações de atualização e de liberação. Revise as chamadas de ferramentas propostas exatamente como revisaria um comando de shell de um administrador.

Se a ligação remota for inevitável

Loopback mais SSH é o design recomendado. Se o seu ambiente exigir um ouvinte de rede privada, torne a exceção explícita:

[security.mcp]
enabled = true
listen = "10.20.0.15:9443"
expose_remote = true
allowed_ips = ["10.20.10.0/24"]
token = "replace-with-your-generated-64-character-token"

Mantenha o bloco TLS do exemplo anterior, utilize um certificado que corresponda ao nome DNS privado e aplique a mesma faixa de origem nos firewalls do host e da rede. Nunca utilize 0.0.0.0/0 ou ::/0 como uma lista de permissões de conveniência. Lembre-se de que uma lista de permissões de aplicações vê o endereço de origem que realmente chega a Webship; verifique o comportamento quando um balanceador de carga, gateway NAT ou malha de serviços estiver à frente dele.

A exposição remota aumenta o valor dos registos de acesso centralizados, das janelas operacionais curtas e da rotação rápida. Não é necessária apenas porque o cliente MCP corre numa outra máquina; é exatamente isso que o túnel SSH resolve.

Operar o plano de controlo deliberadamente

Use esta lista de verificação para produção:

Mantenha MCP desativado onde nenhum agente ou operador o necessite.
Ligar ao loopback e usar um túnel SSH por defeito.
Use uma identidade TLS dedicada e mantenha a verificação do certificado ativada.
Gere um token de portador único para cada ambiente Webship.
Proteja o TOML, a configuração do cliente, a chave TLS e as chaves SSH com permissões do sistema de ficheiros.
Separe as credenciais de desenvolvimento, teste e produção.
Inicie as sessões com ferramentas de estado e simulação de políticas antes das mutações.
Preserve e reveja os eventos de auditoria de segurança de Webship.
Rode o token e reinicie Webship após suspeita de exposição.
Feche os túneis quando a sessão administrativa terminar.

Para a resposta a incidentes, feche túneis ativos, restrinja a conta SSH, substitua o token MCP no TOML protegido, reinicie Webship e reveja os registos recentes de auditoria de segurança e de versões de configuração. Se a chave privada TLS puder estar exposta, emita um novo certificado e chave como parte da mesma reinicialização. Teste o token antigo posteriormente e confirme que é rejeitado.

Um plano de controlo deve permanecer um plano de controlo

MCP é útil porque um agente pode inspecionar o estado real e aplicar alterações validadas sem encaminhar essas operações através do caminho público de pedidos. Essa vantagem desaparece se o ouvinte de controlo se tornar outro ponto de extremidade na internet.

Mantenha o limite simples: um ouvinte separado, acessibilidade de loopback, TLS verificado, uma credencial de suporte protegida, um túnel autenticado, alterações verificadas por versão e um processo de revisão humana para operações poderosas. Webship fornece o protocolo e os guardiões de segurança; o operador decide quem pode aceder a eles.

Este guia baseia-se na documentação do operador Webship 1.3.1, exemplos de configuração fornecidos, código de validação e transporte MCP, salvaguardas de configuração em tempo de execução e catálogo de ferramentas. Revise a atual documentação Webship e a resposta tools/list do servidor em execução antes de aplicá-la a outra versão.