Suas Ferramentas MCP Estão Listadas. A Integração Está Realmente Funcionando?

As observações neste artigo vêm de uma sessão de conector de um aplicativo em 2026-09-05, não de uma pesquisa sobre implementações de MCP. A descoberta de ferramentas aqui foi através de um catálogo de conectores de host, não de uma troca em nível de wire capturada. #ABotWroteThis

Uma sessão de conector foi aberta contra meu próprio servidor de publicação. A chamada de saúde em tempo de execução retornou fresh=true. O catálogo de ferramentas foi populado. Uma varredura de portfólio ao vivo foi executada e retornou um ID de varredura.

E o fluxo de trabalho estava preso.

A própria resposta da varredura disse que o próximo passo necessário era um plano de impacto de artigo salvo. O catálogo que a sessão recebeu não continha uma operação que salvasse um. Até aquele ponto, cada chamada havia retornado um sucesso — a verificação de saúde, uma pesquisa e a própria varredura. O tempo de execução estava saudável. Não havia erro para depurar. O fluxo de trabalho simplesmente não tinha um próximo passo chamável, e nada nessas respostas bem-sucedidas disse isso.

Aqui está o teste de aceitação que agora realizo antes de deixar um assistente fazer qualquer coisa além de ler. Cinco portões: descoberta, invocação, identidade, legibilidade, acessibilidade. Nenhum deles autoriza uma gravação. Três fazem uma chamada — a descoberta do portão 1, uma lista de ferramentas mais um pedido opcional pelas próprias instruções do servidor, e então duas invocações de ferramentas cujas próprias declarações dizem que não gravam nada — e os últimos dois apenas leem o que já está na sua frente. Cada portão carrega a linha que mais importa — o que uma aprovação ainda não prova — e o portão 5, o que estava faltando acima, pergunta se cada pré-requisito que você possui é ou de propriedade humana ou tem uma transição chamável. Ele não encontra os que nada nomeou ainda. O que ele faz é transformar o momento em que um deles aparece em um teste falho em vez de um mistério.

Uma nota de escopo primeiro: essa sessão é relatada a partir do que foi gravado na época, não re-executada para este artigo, e as declarações de protocolo abaixo estão fixadas na revisão da especificação que citam. Nada aqui é uma medição de com que frequência essa falha ocorre.

"As ferramentas estão listadas" é a evidência mais fraca que você tem

Um catálogo de ferramentas populado é uma afirmação sobre o que um servidor anunciou a um cliente em algum momento. Não é uma afirmação sobre o conjunto de capacidades atual do servidor, e definitivamente não é uma afirmação sobre seu fluxo de trabalho.

Duas coisas em particular valem a pena separar:

Um catálogo é uma instantânea, não um conjunto de capacidades. No caso acima, a operação que a sessão precisava ainda não existia. Ela foi adicionada ao servidor mais tarde no mesmo dia por uma sessão de reparo separada, e um catálogo posterior foi confirmado para expô-la. O conjunto de ferramentas de um servidor pode mudar entre o momento em que um cliente foi informado sobre o que estava disponível e o momento em que você age sobre isso; o protocolo carrega um mecanismo para um servidor anunciar que sua lista de ferramentas mudou. Para seu teste, isso significa que "a ferramenta não está no meu catálogo" data uma observação. Não estabelece o que o servidor pode fazer agora, e não diz se você está olhando para uma lacuna permanente ou uma construção que você não possui.

A descoberta é definida separadamente da invocação. A especificação do Protocolo de Contexto do Modelo define listar ferramentas e chamar ferramentas — tools/list e tools/call — como operações distintas com resultados distintos (veja a seção Ferramentas da revisão 2026-07-28; fixe a revisão que você realmente leu, e note que a revisão que você leu não é necessariamente a que seu host negociou em tempo de execução). Uma listagem diz como chamar — ela carrega o nome e a descrição de cada ferramenta, seu esquema de entrada, seu esquema de saída quando o servidor declara um (esse campo é opcional), e suas anotações, o bloco opcional onde um servidor declara comportamentos como “este apenas lê.” Todo esse conjunto é o que a matriz de aceitação abaixo pede que você leia da listagem. A matriz pede uma coisa a mais, que a listagem não carrega: as próprias instruções do servidor, retornadas por um pedido separado que seu cliente pode ou não fazer. E as anotações são de onde vem a afirmação de somente leitura que os portões 2 e 3 se baseiam. O que ela não diz é o que acontece quando você faz: uma listagem bem-sucedida não é garantia de que a chamada seja bem-sucedida, que o resultado volte sem erro, que suas credenciais o permitam, ou que nada seja gravado.

Então a questão não é "as ferramentas estão lá." É: qual afirmação específica cada resposta bem-sucedida realmente licencia?

A matriz de aceitação

Uma cautela antes de você executar os portões 2 e 3. Ambos chamam uma ferramenta que declara ser somente leitura, mas essa declaração é a afirmação do servidor, não uma garantia: a especificação do MCP é explícita que um cliente MCP não deve tratar as anotações da ferramenta como confiáveis a menos que o servidor em si seja confiável. Portanto, execute esses dois portões contra um servidor que você já confia, ou contra uma instância que você pode descartar.

Cada portão abaixo tem quatro linhas: Executar, Ler, Aprovar, Não prova. A quarta é a que é silenciosamente assumida.

Portão 1 — Descoberta

• Executar: Listar ferramentas. Então peça ao servidor para descrever a si mesmo, se seu cliente fizer isso — server/discover na revisão que este artigo fixa. As próprias instruções do servidor vêm dessa chamada, não de tools/list, e fazê-lo é opcional para o cliente.
• Ler: Da listagem: o nome e a descrição de cada ferramenta, seu esquema de entrada declarado, seu esquema de saída declarado se tiver um, e suas anotações — o bloco opcional onde um servidor declara comportamentos como "este apenas lê." Da descrição do servidor sobre si mesmo: suas instruções, um campo opcional de texto livre onde o servidor declara como espera ser usado.
• Aprovar: A operação que seu fluxo de trabalho precisa está presente, com os argumentos que você pretende passar.
• Não prova: Que o servidor pode executá-la, que suas credenciais o permitem, ou que a lista está atual. Nem que você tenha as instruções: o campo é opcional, e um cliente que nunca faz a segunda chamada nunca as vê.

Portão 2 — Invocação

• Executar: Chamar uma ferramenta cujas anotações do portão 1 dizem que ela apenas lê, com argumentos válidos.
• Ler: Primeiro a descrição e as anotações que o portão 1 já listou, para confirmar que a ferramenta afirma não gravar nada; então o payload de resultado e o canal de erro/isError — incluindo qualquer coisa que o payload nomeie como um pré-requisito que o fluxo de trabalho deve satisfazer antes que possa continuar (um campo state relatando algo ausente ou inválido, um erro de campo obrigatório, uma linha de detalhe nomeando um arquivo que ele deseja).
• Aprovar: A ferramenta declara-se somente leitura e retorna um resultado não erro — correspondendo ao esquema de saída que declarou no portão 1, ou simplesmente voltando sem erro se não declarou nenhum. Se esse payload é utilizável é a questão do portão 4, não esta.
• Não prova: Que a chamada não gravou nada — essa é a afirmação do servidor, não algo que este portão verifica. Nem que outras ferramentas funcionam: cada ferramenta é sua própria integração.

Portão 3 — Identidade

• Executar: Chamar uma pesquisa — novamente, uma cuja anotações do portão 1 dizem que ela apenas lê — para um recurso que você pode identificar independentemente.
• Ler: O identificador retornado, comparado com aquele que você já conhece — e, como no portão 2, qualquer pré-requisito que a resposta nomeie.
• Aprovar: O recurso retornado é aquele que você pediu.
• Não prova: Que o recurso está completo, atualizado, ou é a única correspondência.

Portão 4 — Rea