Executando uma Página de Status Pública para Seu Servidor MCP

Publicado originalmente no blog da Merlonix.

Se você opera um servidor MCP ao qual os agentes de outras equipes se conectam, você tem um problema de suporte que um operador de API REST não tem: quando seu servidor apresenta problemas, o desenvolvedor do outro lado está depurando um agente, não lendo seus logs. O sintoma deles é "o agente parou de chamar a ferramenta" ou "o agente alucina um argumento que costumava funcionar" — não "GET /mcp retornou 500." Sem um lugar para verificar primeiro, eles gastam uma hora bisectando seu próprio prompt, seu próprio código cliente e sua própria versão de modelo antes de sequer considerar que o problema está do seu lado. Uma página de status é como você tira essa hora deles.

Uma página de status de uptime genérica — o tipo construído para uma API REST ou um site de marketing — é necessária, mas não suficiente aqui. Ela informa ao visitante "alcance" ou "não alcançado." Um servidor MCP pode estar acessível e ainda assim estar quebrado para todos os agentes que tentam usá-lo: o handshake pode falhar enquanto o endpoint retorna 200, tools/list pode lançar uma exceção enquanto a URL base está boa, o esquema de entrada de uma ferramenta pode mudar de forma da noite para o dia sem nenhum sinal visível de HTTP. Se sua página de status apenas relata a acessibilidade HTTP, ela mostrará "operacional" durante uma interrupção que seus próprios clientes estão enfrentando.

Por que "acessível" não é "funcionando" para MCP

Essa é a mesma lacuna coberta em como verificar a saúde de um servidor MCP remoto: um servidor HTTP Streamable correto que apenas faz solicitação/resposta é permitido pela especificação a retornar 405 em um GET simples, e uma página de erro de CDN pode retornar um 200 limpo. Nenhum desses fatos é visível para um monitor que apenas verifica se a URL responde. A mesma lacuna aparece no lado da comunicação. Quando algo dá errado, "servidor MCP enfrentando problemas" não diz nada que um desenvolvedor de agente possa agir. Compare isso com "o handshake initialize está falhando — novas sessões não podem começar, mas sessões ativas não são afetadas" ou "o esquema de entrada da ferramenta search_docs mudou às 14:02 UTC, o que quebrará qualquer cliente que ainda esteja enviando o antigo formato de argumento." O segundo tipo de mensagem encerra imediatamente a sessão de depuração do desenvolvedor. O primeiro tipo a estende.

O que realmente precisa ser visível, especificamente porque é MCP e não uma página da web:

• Estado do handshake. A solicitação initialize JSON-RPC foi bem-sucedida? Um servidor pode ser acessível pela rede e ainda recusar ou gerar erro em cada sessão.
• Transporte. HTTP Streamable vs o transporte legado HTTP+SSE — veja Streamable HTTP vs SSE para o que cada um parece no tráfego. Uma mudança de transporte entre dois pontos no tempo é em si mesma digna de divulgação, porque clientes fixados no antigo comportamento podem quebrar no momento em que você migra, com cada sinal HTTP comum permanecendo verde.
• Inventário de ferramentas e desvio. Quais ferramentas estão atualmente anunciadas, e uma ferramenta desapareceu, apareceu ou teve seu esquema alterado desde a última verificação? Uma ferramenta removida ou remodelada quebra qualquer agente que já a esteja chamando — silenciosamente, porque nada na camada HTTP parece doente.
• Autenticação necessária vs fora do ar. Um 401/403 significa que o servidor está ativo e simplesmente requer uma credencial. Agrupar isso no mesmo bucket de "fora do ar" que uma verdadeira interrupção treina seu público a ignorar sua página de status.
• Latência do handshake. Um initialize lento não falha uma solicitação, mas cada sessão de agente contra seu servidor parecerá lenta para iniciar. Isso vale um "degradado", não silêncio.

O que uma configuração de status MCP feita sob medida oferece

Vale a pena ser preciso sobre quais partes disso são específicas do MCP e quais são infraestrutura de página de status ordinária, porque elas vivem em partes diferentes do produto.

A parte genérica é o produto da página de status: crie uma página para um cliente, adicione componentes (cada um respaldado por um ativo monitorado), publique-a em status.merlonix.com/<seu-slug> (ou um domínio personalizado com marca branca no Agency+), poste incidentes com uma linha do tempo de status (investigando → identificado → monitorando → resolvido) e nível de impacto, execute janelas de manutenção programadas e envie e-mails para assinantes confirmados em cada atualização de incidente. Nada disso é consciente do MCP — é a mesma maquinaria de página de status que você usaria para um banco de dados ou um fluxo de checkout.

A parte específica do MCP é a verificação monitorada mcp_health. Ative-a em um ativo e a Merlonix executa o verdadeiro handshake JSON-RPC initialize — não um GET — em uma programação, e registra: sucesso do handshake, o transporte que detectou (streamable_http vs sse), qual geração de especificação o servidor respondeu (o handshake stateful clássico vs o núcleo stateless de 2026-07-28 — veja por que o MCP initialize falha para o que um handshake rejeitado em um servidor migrado parece e por que não está necessariamente fora do ar), o inventário completo de ferramentas com um resumo de contrato por ferramenta para detecção de desvio, se o endpoint está protegido por autenticação, a latência de ida e volta do handshake e uma nota de segurança de A a F cobrindo sinais de envenenamento de descrição de ferramenta, requisito de autenticação e segurança de transporte. Ele alerta sobre quatro transições distintas: o servidor ficando fora do ar, se recuperando, uma ferramenta ou capacidade desviando (com uma bandeira breaking quando uma ferramenta foi removida ou seu esquema mudou em vez de apenas ganhar uma capacidade), e um cartão de servidor publicado /.well-known/mcp.json discordando do que o servidor ao vivo realmente serve. Este é o mesmo probe por trás do verificador de saúde MCP gratuito, executado continuamente com memória de desvio em vez de como uma verificação única.

Como os dois se conectam: o distintivo público de um componente da página de status (operacional / degradado / fora do ar) lê os probes de disponibilidade no ativo por trás dele — a verificação de uptime, heartbeat, porta e mcp_health — e toma o pior veredicto. Assim, um handshake initialize que falha muda o tile para "fora do ar" por conta própria, e um resultado mcp_health de degradado (um servidor que responde, lenta ou incompletamente) aparece como degradado em vez de ser arredondado para qualquer extremo. Problemas de certificado e DNS ainda derrubam um componente de forma independente, porque um host que responde a um handshake enquanto serve um certificado expirado também não está saudável.

Vale a pena dizer claramente: o distintivo não é o incidente. Um tile automatizado pode informar seu público que algo está errado; ele não pode dizer o que, e para um servidor MCP o "o que" é todo o conteúdo útil — uma falha de handshake, um tools/list que está com timeout e um esquema de ferramenta alterado são três incidentes diferentes com três soluções diferentes. Trate o distintivo como a coisa que impede as pessoas de se perguntarem, e a postagem do incidente como a coisa que encerra sua sessão de depuração. É sobre isso que a próxima seção trata.

Configurando um

1. Adicione o nome do host do seu endpoint MCP como um ativo monitorado, e ative mcp_health. Esta é a verificação que realmente fala JSON-RPC com seu servidor em vez de apenas fazer um GET.
2. Crie uma página de status para o cliente que a possui, e adicione o ativo como um componente. Dê ao componente um rótulo que um desenvolvedor de agente reconheceria — "API MCP" ou o nome do servidor do seu s