Engenharia Webship

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

ConfigurarWebshipisoladoMCPplano de controle comTLS 1.3, um token portador forte, vínculo 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

# Conecte com segurança os Agentes de IA ao Servidor MCP do Webship

Uma conexã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 o roteamento e a política de segurança, recarregar certificados, ativar lançamentos estáticos, coordenar mudanças na frota e instalar uma atualização assinada Webship.

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

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

Comece com o limite de confiança

O tráfego público do Webship e o tráfego do MCP usam listeners separados. O plano de controle do MCP está desativado por padrão e nunca compartilha o listener normal HTTP, HTTP/2, HTTP/3 ou WebTransport. Quando ativado, ele serve MCP por meio de um endpoint dedicado de TLS 1.3 HTTP/1.1.

Uma implantação segura possui quatro controles independentes:

Alcance da rede: o listener MCP se conecta a 127.0.0.1, não a um endereço público ou LAN privada.
Identidade de transporte: o cliente verifica um certificado emitido por uma AC em que confia.
Autenticação de aplicação: cada requisição carrega um token bearer forte.
Acesso administrativo: operadores acessam o listener de loopback por meio de uma conta SSH autenticada e túnel.

Nenhum desses controles substitui outro. TLS sem um caminho de rede privado ainda expõe uma superfície de autenticação. Um túnel sem verificação de certificado torna a identidade do endpoint ambígua. Um token de portador dentro de um arquivo legível por todos não é um segredo.

Prepare o certificado e o token

Emita um certificado MCP dedicado a partir da sua CA interna. Para o túnel mostrado abaixo, inclua localhost e 127.0.0.1 nos nomes alternativos do assunto do certificado, e depois instale a CA emissora no repositório 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 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 em um arquivo de configuração legível apenas pela conta de serviço Webship e seu grupo administrativo. Não coloque o token em uma unidade systemd, histórico de shell, ticket, mensagem de chat ou prompt enviado a um modelo de IA.

Em um 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 usuário 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 seçã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. Clientes loopback permanecem permitidos por padrão. expose_remote = false torna o limite pretendido explícito: se alguém posteriormente alterar listen para um endereço não loopback, Webship rejeita a configuração em vez de publicar silenciosamente o plano de controle.

Webship também rejeita um listener MCP habilitado sem TLS, sem um token, com um token curto ou contendo espaços em branco, ou com caminhos de certificado vazios. Tokens públicos de espaço reservado 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 controle, portanto, eles exigem uma reinicialização do processo. Valide a configuração completa primeiro:

/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 no loopback:

ss -ltn | grep '127.0.0.1:9443'

Não adicione a porta 9443 às regras públicas de firewall do host. A próxima etapa acessa ela através do SSH.

Criar o túnel privado

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

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

O cliente MCP agora se conecta ao https://localhost:19443/mcp. O TCP alcança o servidor SSH, o SSH leva a conexão para o host, e o host abre a conexã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 seus controles normais de acesso ao host. Se um host intermediário for necessário, mantenha o listener MCP na interface de loopback do host Webship e estenda o caminho SSH em vez de alargar o listener.

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 ele tiver um. Caso contrário, restrinja a configuração do cliente à conta atual do sistema operacional. O cliente HTTP—não o modelo—deve anexar o cabeçalho de autorização. Nunca cole o token ativo em uma conversa.

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

Torne a primeira sessão somente leitura

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

Peça por tools/list; sua resposta é o esquema de argumento autorizado para a versão em execução.
Ligue para webship.get_config e registre a versão atual da configuração.
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 retornada oculta tokens de portador.

Somente então teste uma mutação em um ambiente que não seja de produção. As mutações de configuração do Webship requerem o ID da versão atual. Uma gravação desatualizada é rejeitada em vez de sobrescrever uma mudança 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 rebaixamentos de segurança ativos selecionados. Uma solicitação MCP não pode desligar um WAF ativo, camada DDoS, API Shield, desafio de bot, 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 uma reinicialização deliberada.

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

Se a ligação remota for inevitável

Loopback mais SSH é o design recomendado. Se seu ambiente exigir um ouvinte de rede privada, faça 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, use um certificado correspondente ao nome DNS privado e aplique o mesmo intervalo de origem nos firewalls de host e de rede. Nunca use 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 aplicativo vê o endereço de origem que realmente chega ao Webship; verifique o comportamento quando um balanceador de carga, gateway NAT ou service mesh estiver na frente dele.

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

Operar o plano de controle deliberadamente

Use este checklist para produção:

Mantenha MCP desativado onde nenhum agente ou operador precisar dele.
Vincule ao loopback e use um túnel SSH por padrão.
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 arquivos.
Separe as credenciais de desenvolvimento, teste e produção.
Inicie as sessões com ferramentas de status e simulação de políticas antes das mutações.
Preserve e revise os eventos de auditoria de segurança de Webship.
Gire o token e reinicie Webship após suspeita de exposição.
Feche os túneis quando a sessão administrativa terminar.

Para resposta a incidentes, feche túneis ativos, restrinja a conta SSH, substitua o token MCP no TOML protegido, reinicie o Webship e revise os registros recentes de auditoria de segurança e versão 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 ele seja rejeitado.

Um plano de controle deve permanecer um plano de controle

MCP é útil porque um agente pode inspecionar o estado real e aplicar alterações validadas sem encaminhar essas operações pelo caminho de solicitação pública. Essa vantagem desaparece se o listener de controle se tornar outro ponto de extremidade na internet.

Mantenha o limite simples: um ouvinte separado, acessibilidade de loopback, TLS verificado, uma credencial de portador 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 as proteções de segurança; o operador decide quem pode acessá-las.

Este guia é baseado na documentação do operador Webship 1.3.1, exemplos de configuração fornecidos, código de validação e transporte MCP, proteções 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.