Como registrar versões de esquemas de ferramentas em conectores do Claude

Registrar versões de esquemas de ferramentas separa um conector estável de um conector que quebra sem aviso. Em um servidor MCP, cada ferramenta tem nome, descrição e um inputSchema em JSON Schema. Quando um desses elementos muda, chamadas antigas podem continuar chegando com o formato anterior. O conector não adivinha: envia o que aprendeu na lista e recebe erro ou, pior, um resultado diferente.

A prática recomendada é simples de enunciar e trabalhosa de executar. Trate o esquema como contrato público: registre cada mudança em changelog, classifique entre compatível e incompatível, teste com chamadas reais e mantenha a versão anterior disponível para rollback. O restante mostra como fazer isso sem inflar o catálogo.

Resumo rápido

• Nome, tipo, campo obrigatório e enum são parte do contrato, não detalhe interno.
• Renomear ferramenta ou campo quebra allowlists e chamadas antigas, mesmo que o código novo funcione.
• Mudanças aditivas com campos opcionais são compatíveis. Tornar campo obrigatório e mudar tipo não são.
• Versione com sufixo no nome apenas quando a ruptura for real, e mantenha as duas versões convivendo por um ciclo definido.
• Changelog, teste de regressão e artefato anterior pronto para redeploy são o mínimo para reverter.

O que muda quando um esquema muda

Na especificação do MCP, uma ferramenta é identificada por um nome único e descrita por metadados. O cliente descobre o que existe com tools/list e invoca com tools/call, enviando o nome e os argumentos. O inputSchema define os parâmetros esperados, e o outputSchema opcional define a estrutura do resultado. Nada disso é decorativo: é o contrato que o modelo lê para decidir o que chamar e como preencher os argumentos.

Uma mudança de nome tem efeito imediato. O nome é o identificador da ferramenta e também a chave usada em allowlists e denylists de conectores. No conector MCP do Claude, a configuração por ferramenta fica em configs, com o nome da ferramenta como chave. A documentação da Anthropic informa que um nome inexistente no servidor gera aviso no backend, mas não retorna erro, porque servidores podem expor ferramentas de forma dinâmica. Traduzindo: renomear uma ferramenta pode deixar sua allowlist silenciosamente sem efeito.

Mudança de tipo e campo obrigatório novo quebram do mesmo jeito. Se um campo era string e passa a number, a chamada antiga chega com o tipo errado. Se o esquema passa a exigir um dado que o chamador não enviava, a validação falha. A especificação prevê erro de protocolo para argumentos inválidos e ferramenta desconhecida, e o fluxo perde contexto. Enum fechado também pode recusar um valor novo do lado de quem chama.

Há ainda a mudança invisível. Alterar apenas a descrição não mexe no JSON Schema, mas muda a decisão do modelo, porque a seleção considera nome e descrição. A documentação do conector diz que descrições claras melhoram a precisão. Uma descrição reescrita pode fazer o modelo chamar a ferramenta errada, sem nenhum erro de validação.

Compatível e incompatível na prática

A tabela serve como triagem. A classificação não substitui teste, mas evita discussão sobre se a mudança é grande ou pequena.

O ponto delicado é a última linha. Schema igual não garante contrato igual. Se desconto passa a ser percentual em vez de valor absoluto, nenhum validador reclama e o resultado muda. O changelog precisa registrar semântica, não apenas forma.

Como versionar sem inflar o catálogo

Existem duas estratégias viáveis. A primeira é sufixo de versão no nome da ferramenta, como emitir_nota_v2, mantendo a versão anterior ativa. A segunda é evoluir a mesma ferramenta apenas com mudanças compatíveis, usando campos opcionais e períodos de transição. A escolha depende do tipo de ruptura.

1. Use sufixo quando a ruptura é real. Renomeou campo, mudou tipo, mudou semântica ou tornou algo obrigatório? Crie uma ferramenta nova e mantenha a antiga funcionando. O sufixo deixa a diferença visível para o modelo e para quem opera o conector.
2. Não use sufixo para mudança aditiva. Um campo opcional novo não justifica uma segunda ferramenta. Versione o esquema no repositório e no changelog, mas mantenha um único nome em produção.
3. Defina uma janela de convivência. As duas versões ficam ativas por um ciclo completo de uso, por exemplo um ciclo de faturamento ou de fechamento, e só depois a antiga é desligada. O prazo precisa estar escrito, com dono e critério de saída.
4. Marque a versão antiga na descrição. Diga que ela está em desuso e indique a substituta. Isso ajuda o modelo a preferir a versão nova e ajuda quem lê o catálogo a entender o estado.
5. Evite três versões ao mesmo tempo. Se v1, v2 e v3 convivem, a seleção fica ambígua e o custo de manutenção sobe. Duas é o limite prático.
6. Aproveite o pin de lista de ferramentas. Com o cabeçalho beta mcp-client-2026-09-15, o conector registra a lista retornada pelo servidor e permite fixá-la no toolset. Assim, uma alteração no servidor não muda o que o Claude vê no meio de uma conversa.

Vale conhecer a diferença de nomenclatura. O MCP usa inputSchema, em camelCase. O bloco de listagem e o campo de pin do conector usam input_schema, em snake_case. Normalize os dois antes de comparar, para não acusar mudança onde só existe convenção.

Permissões andam junto. Uma ferramenta nova herda a política da anterior apenas se o nome for o mesmo. Ao criar emitir_nota_v2, verifique se operações concedeu acesso. Um guia está em permissões de conectores do Claude para equipes.

Rotina de teste antes de publicar

Teste de esquema não é teste de comportamento. Os dois são necessários, e a ordem importa.

1. Diff de esquema automatizado. Compare o JSON Schema publicado com o candidato. Liste campos adicionados, removidos, renomeados e com tipo alterado. O diff entra no pull request.
2. Validação de contrato. Rode um validador de JSON Schema contra um conjunto de chamadas representativas, incluindo argumentos antigos que ainda devem funcionar.
3. Chamadas de ouro. Guarde um conjunto de chamadas reais com entrada e saída esperada. Reexecute na versão nova e compare o resultado campo a campo.
4. Teste de allowlist. Confirme que cada nome configurado no conector existe no servidor. Nome inexistente gera apenas aviso, então esse teste precisa ser explícito.
5. Teste de seleção. Rode prompts reais e verifique se o modelo escolhe a ferramenta certa com a descrição nova. Descrição alterada pode mudar a escolha sem erro técnico.
6. Ensaio de rollback. Antes de publicar, faça o redeploy da versão anterior em ambiente de teste. Rollback não testado é esperança, não plano.

Ambiente separado não é luxo. O servidor de teste precisa de dados representativos e credenciais próprias, sem apontar para produção. Um roteiro está em ambientes de teste e produção em MCP com Claude. Se o servidor exigir autenticação e limite de requisições, teste esse caminho antes de liberar a versão, como descrito em autenticação e rate limiting em servidores MCP.

Exemplo: servidor MCP de notas fiscais de uma distribuidora

Cenário hipotético, sem vínculo com empresa real. Uma distribuidora de médio porte expõe um servidor MCP interno com a ferramenta emitir_nota. O esquema aceita cnpj, valor, serie e itens. O conector do time financeiro usa uma allowlist com essa ferramenta e mais duas de consulta.

A primeira mudança é aditiva: incluir centro_custo como campo opcional. A lista de obrigatórios fica intacta, chamadas antigas continuam válidas e nenhuma ferramenta nova é criada.

A segunda costuma dar errado. O time renomeia valor para valor_total no mesmo nome de ferramenta. O schema fica válido, mas chamadas antigas falham na validação e o histórico de conversas fica inconsistente. A versão segura seria criar emitir_nota_v2, manter a v1 ativa durante o ciclo de faturamento, marcar a antiga como em desuso e só desligá-la após o volume migrar.

Changelog e rollback

O changelog precisa permitir que alguém de fora entenda a mudança e reverta. Uma entrada por alteração publicada, com os campos abaixo.

Reverter exige três coisas prontas antes da publicação: o artefato da versão anterior, o deploy que troca a versão sem alterar o nome da ferramenta e o conjunto de testes que comprova a volta. Se a mudança criou _v2, desabilite a v2 e reative a v1 na allowlist. Se foi no mesmo nome, redeploy do artefato anterior.

Há uma proteção adicional. A lista fixada no toolset impede que uma alteração no servidor mude o que o Claude vê no meio de uma conversa. Não substitui o rollback do servidor, mas evita que uma publicação pegue uma sessão em andamento.

Avise quem usa. Conector remoto só é confiável com domínio, certificado e política de acesso estáveis. Se a mudança envolver URL ou certificado, valide antes com o roteiro de verificação de domínio em conector remoto do Claude.

Erros comuns

• Renomear ferramenta sem alias. A allowlist continua com o nome antigo e o aviso no backend não aparece para o usuário. Mantenha a versão antiga ativa durante a transição.
• Confiar no aviso silencioso. Nome inexistente em configs gera aviso, não erro. Teste a allowlist de forma explícita, comparando a lista do servidor com a configuração do conector.
• Versionar tudo no nome. Criar _v2 para um campo opcional infla o catálogo e confunde a seleção. Use sufixo apenas para ruptura real.
• Testar só o schema. JSON válido não garante resultado igual. Inclua chamadas de ouro e comparação de saída.
• Esquecer a semântica. Mudar a unidade ou o significado de um campo sem mudar o tipo passa em qualquer validador e altera o resultado.
• Planejar rollback no papel. Sem artefato anterior e sem ensaio de redeploy, a reversão vira incidente durante o incidente.

Perguntas frequentes

Toda mudança precisa de uma nova versão da ferramenta?

Não. Adicionar campo opcional ou tornar um campo obrigatório em opcional preserva chamadas antigas. Nesses casos, mantenha o mesmo nome e registre a mudança no changelog e no histórico do repositório.

O sufixo _v2 no nome é obrigatório?

Não é regra do protocolo, é convenção. O nome é livre, mas precisa ser único. O sufixo ajuda quando a ruptura é visível para o modelo e para a allowlist. Em mudanças compatíveis, atrapalha.

Mudar apenas a descrição pode quebrar alguma coisa?

Pode alterar o comportamento sem erro técnico. A seleção considera nome e descrição. Se a descrição nova ficar ambígua ou prometer o que a ferramenta não faz, o modelo escolhe errado. Teste com prompts reais.

Como saber se o conector usa allowlist?

Verifique o toolset do conector. Quando há default_config com enabled: false e uma lista em configs, é allowlist. Toda ferramenta nova precisa ser habilitada explicitamente.

Para que serve fixar a lista de ferramentas?

Para congelar o que o Claude vê durante uma conversa. Sem o pin, uma alteração no servidor pode mudar a lista no meio da sessão. Com o pin, a lista registrada é usada naquele fluxo.

Quanto tempo as duas versões devem conviver?

O suficiente para cobrir um ciclo completo do processo afetado, com critério de saída claro. O prazo importa menos que a evidência: nenhuma chamada relevante na versão antiga e nenhum fluxo pendente.

Fontes e leitura recomendada

• Especificação MCP: Tools, com name, inputSchema, tools/list e tools/call
• MCP: visão geral da arquitetura, camada de dados e descoberta de capacidades
• Anthropic: conector MCP, toolset, allowlist e pin da lista de ferramentas
• Anthropic: visão geral de uso de ferramentas e definição de esquema
• Repositório oficial da especificação MCP, com histórico e changelog