Checklist Pré-Publicação do Servidor MCP

Antes de publicar um servidor MCP, execute 10 verificações. A maioria dos servidores falha em pelo menos três — e as falhas são invisíveis até que um agente escolha a ferramenta errada, alucine um argumento ou silenciosamente desconecte seu servidor. Esta é a lista de verificação que construímos mcp-probe para impor, destilada para o que realmente quebra no mundo real.

Resumo — Um servidor MCP publicável se conecta de forma limpa, nomeia ferramentas de maneira inequívoca, descreve cada argumento, valida entradas e envia metadados de instalação. A falha mais comum é descrições de ferramentas superficiais: mesmo os cinco servidores de referência oficiais da Anthropic têm uma pontuação máxima de 60/100 na qualidade da descrição.

Por que "funciona no Inspector" não é suficiente

O MCP Inspector responde "meu servidor se conecta e lista ferramentas?" Isso é necessário, mas não suficiente. O agente não experimenta seu servidor da maneira que você faz em uma interface — ele experimenta suas descrições de ferramentas e esquemas como texto em uma janela de contexto, e escolhe ferramentas lendo-as. Um servidor pode passar no Inspector e ainda ser funcionalmente não publicável porque o modelo não consegue distinguir suas ferramentas.

Portanto, a pergunta pré-publicação não é "ele funciona?" É "ele é publicável?" — um agente real, sem documentação e sem humanos no loop, usará isso corretamente?

A lista de verificação de 10 pontos

Conexão & protocolo

1. Conecta sem erros de transporte — stdio ou HTTP, o handshake é concluído e a versão do protocolo está atual.
2. Lista ferramentas, recursos e prompts — tudo que você pretende expor realmente aparece após initialize.
3. Sem tempo limite de inicialização — listas de ferramentas grandes podem exceder o tempo limite de sondagem do cliente e serem silenciosamente descartadas. Mantenha initialize rápido.

Legibilidade da ferramenta (onde a maioria dos servidores falha)

1. Cada ferramenta tem uma descrição real — não um nome reexpresso. "create_issue: cria um problema" não diz nada ao modelo. A descrição deve fazer o trabalho de desambiguação.
2. Sem colisões de nomes — create_issue existe em uma dúzia de servidores. Se o seu colidir, o modelo adivinha. Namespace ou especifique.
3. Argumentos são descritos, não apenas digitados — cada parâmetro precisa de uma descrição, campos obrigatórios marcados, enums enumerados. Argumentos aninhados fazem o modelo perder campos obrigatórios.
4. Mutations são legíveis — uma ferramenta que escreve/deleta/cobra deve dizer isso. O modelo nunca deve descobrir um efeito colateral em tempo de execução.

Esquema & entradas

1. Entradas validam — entrada válida tem sucesso, entrada inválida produz um erro útil, não um rastreamento de pilha ou uma passagem silenciosa.
2. Restrições de enum e forma são explícitas — se um campo aceita um de quatro valores, o esquema diz isso. "string" onde você quer dizer um enum é uma armadilha.

Distribuição

1. Metadados de instalação são enviados — nome de pacote claro, exemplo executável, README atualizado e um server.json para que o Registro MCP oficial possa descobrir você. Os desenvolvedores encontram ferramentas no momento da instalação, não no momento da pesquisa.

Como pontuá-lo em 3 segundos

Você pode percorrer esta lista manualmente ou executá-la:

npx @incultnitollc/mcp-probe score "node ./your-server.js"

mcp-probe se conecta ao seu servidor, executa todas as dez verificações e retorna uma pontuação de publicabilidade de 0–100 em cinco eixos — qualidade da descrição, correção de enum/forma, legibilidade de mutações, cláusulas anti-"repetir o nome" e metadados de distribuição. Um servidor que passa limpa ~80. Os servidores de referência oficiais ficam em 60 (o limite de descrição é acionado em todos eles). Um servidor comunitário típico de primeiro rascunho fica na casa dos 40.

Integre isso ao CI para que seja executado em cada lançamento:

# .github/workflows/publishability.yml
- run: npx @incultnitollc/mcp-probe score "node ./dist/server.js" --fail-under 80

O código de saída controla a publicação. Seu servidor não pode regredir abaixo da barra que você definiu.

A única coisa a corrigir primeiro

Se você não fizer nada mais: reescreva suas descrições de ferramentas para que um modelo sem contexto possa escolher corretamente entre a sua e uma ferramenta com nome semelhante. Essa única correção move mais servidores para a linha de publicabilidade do que qualquer outra nesta lista — e é a que quase todos pulam.

mcp-probe é uma CLI de código aberto para testar e pontuar servidores MCP antes de você publicar. npx @incultnitollc/mcp-probe · github.com/incultnitollc/mcp-probe