𝗢 𝗘𝘀𝗰𝗵𝗲𝗺𝗮 𝗱𝗮 𝗙𝗲𝗿𝗿𝗮𝗺𝗲𝗻𝘁𝗮 𝗠𝗖𝗣 𝗠𝘂𝗱𝗼𝘂. 𝗢 𝗦𝗲𝘂 𝗔𝗴𝗲𝗻𝘁𝗲 𝗡ã𝗼 𝗣𝗲𝗿𝗰𝗲𝗯𝗲𝘂.
Sua chamada de ferramenta não falhou. Ela retornou um código de status 200 e um JSON válido.
Mas ela foi executada contra o contrato errado. O servidor upstream renomeou um campo três dias atrás. Seu agente continuou enviando o nome antigo. O servidor simplesmente o descartou. O resultado voltou vazio. Nenhum erro apareceu. Ninguém percebeu por uma semana.
Esta é a falha silenciosa. Não é do tipo barulhento, onde os logs ficam vermelhos. É do tipo em que o servidor responde com um sorriso, mas os dados estão errados.
Servidores MCP podem alterar o contrato de uma ferramenta entre as chamadas. Eles podem renomear um parâmetro ou alterar a descrição de um campo. Essas mudanças geralmente permanecem estruturalmente válidas. A validação JSON passa. O servidor responde 200. Seu agente age com dados errados sem um único erro.
A correção é simples: • Fixe um hash SHA-256 de cada contrato de ferramenta. • Inclua tanto o esquema quanto a descrição nesse hash. • Verifique o hash antes de cada chamada. • Interrompa a chamada se o contrato sofrer um desvio (drift).
Nós focamos se uma ferramenta responde. Verificamos códigos de status. Definimos timeouts. Tentamos novamente em erros 5xx. Quase ninguém verifica se o contrato mudou entre o momento em que o agente aprendeu o esquema e o momento em que fez a chamada.
Um servidor MCP expõe ferramentas através de tools/list. Cada ferramenta possui um inputSchema e uma descrição. Seu agente lê isso uma vez no início de uma sessão.
Se o servidor for atualizado, ele pode:
- Renomear um parâmetro (como de
queryparaq) enquanto deixa propriedades extras abertas. O parâmetro antigo é descartado silenciosamente. - Alterar o significado de um campo. Um limite pode mudar de "max results" para "page index". O tipo continua sendo um inteiro, então a validação passa.
- Restringir um enum. Um valor válido pode ser convertido para um novo padrão.
A especificação MCP diz que um servidor DEVE (SHOULD) notificar um cliente se uma lista mudar. Ela não diz que ele TEM QUE (MUST). Muitos servidores não enviarão essa notificação. Mesmo que enviem, eles podem não informar que o esquema de uma ferramenta específica mudou.
Pare de confiar apenas na validação estrutural. Ela não consegue detectar uma mudança de significado.
Trate suas ferramentas MCP como dependências de software. Use uma abordagem de lockfile. No primeiro contato, gere um hash SHA-256 do esquema e da descrição da ferramenta. Antes de cada chamada, recompute o hash. Se eles coincidirem, prossiga. Se não coincidirem, sinalize o desvio e pare.
Fazer o hash da descrição é o segredo. Se um parâmetro mudar de "max results" para "page index", o esquema parecerá o mesmo. O hash mudará porque as palavras mudaram. Isso captura o desvio semântico que a validação deixa passar.
Não tente adivinhar quando um contrato sofrer um desvio. Não tente novamente às cegas. Pause, registre a diferença e corrija o contrato.
Fonte: https://dev.to/0012303/the-mcp-tool-your-agent-calls-changed-its-schema-it-didnt-notice-5g6m
Comunidade de aprendizado opcional: https://t.me/GyaanSetuAi