Criando um Servidor MCP para se Autoinstalar: Três Hosts, Três Mecanismos, Armadilhas

A configuração de servidores MCP ainda exige, muitas vezes, a edição manual de um arquivo JSON — e cada host usa um arquivo e formato diferentes. Esse atrito impede que desenvolvedores usem servidores que, de outra forma, utilizariam. Este post detalha três hosts, seus mecanismos de instalação e as armadilhas que podem pegá-lo.

Três Hosts, Três Mecanismos

• VS Code: Possui uma API real — registerMcpServerDefinitionProvider. Declare um provedor no package.json e retorne a definição do servidor em tempo de execução. O VS Code exibe um prompt de consentimento. Sem edição de arquivo de configuração. É a forma mais limpa, mas exige o envio de uma extensão do VS Code.
• Cursor: Não possui API nativa. Escreva .cursor/mcp.json diretamente com a chave raiz mcpServers.
• Claude Code: Use a CLI. Não escreva o arquivo manualmente. Execute, por exemplo:
  claude mcp add --transport stdio --scope <user|local> --env … <name> -- node <path>

Seis Armadilhas para Evitar

1. Esse arquivo JSON não é seu. O mcp.json do Cursor contém outros servidores do usuário. Leia, mescle sua entrada, preserve chaves não relacionadas — não sobrescreva.
2. Sobreviva a um arquivo malformado. Se o arquivo existir mas for um JSON inválido, não o trate como vazio e sobrescreva. O mesmo para erros de leitura/permissão — relance. Tratar "não foi possível ler" como "não há nada" corromperá configurações.
3. Faça backup e escreva atomicamente. Copie o arquivo existente antes de tocá-lo, escreva em um arquivo temporário e renomeie sobre o destino. Um mcp.json gravado pela metade quebra o editor.
4. Instalar duas vezes deve ser uma operação neutra, não um erro. A CLI do Claude gera erro se a entrada já existir — então remova e depois adicione. Para hosts baseados em arquivos, use o nome do servidor como chave e substitua no lugar. Reexecutar deve convergir, não duplicar.
5. O escopo muda tudo. Instalação a nível de usuário vs. projeto altera onde o arquivo de configuração é salvo e o que o servidor precisa (ex.: diretório de dados explícito vs. descoberta ascendente). Escolha deliberadamente.
6. Você é responsável por se manter atualizado. A versão registrada se distancia do que você envia. Adicione uma verificação: "o que está instalado ainda é a versão que eu empacoto?" e um caminho de reinstalação limpa. Um botão mostra o estado: instalar, atualizar ou atualizado.

A meta-lição: a configuração manual falha porque um humano colando um trecho não sabe o caminho absoluto, o escopo correto, variáveis de ambiente ou como mesclar com segurança. O código de instalação sabe.