17 Lições Difíceis do MCP

Honestamente, eu não esperava estar aqui. Seis meses atrás, eu mal tinha ouvido falar do Protocolo de Contexto do Modelo. Hoje? Eu construí 76 servidores MCP diferentes em quatro projetos de código aberto, passei semanas depurando problemas estranhos e aprendi mais sobre MCP do que eu jamais quis saber.

Então, aqui está a questão — a maior parte do conteúdo sobre MCP que você vê online é ou tutoriais de "hello world" ou hype de marketing. Ninguém te conta sobre os casos estranhos, os sutis problemas de compatibilidade ou os erros que vão te custar três dias de depuração.

Eu cometi todos os erros que você pode cometer. Deixe-me poupar você da dor. Estas são as 17 lições mais difíceis que aprendi ao construir o MCP em produção.

1. Clientes diferentes colocam chaves de API em lugares diferentes

Esse é o erro que me custou três dias inteiros de depuração. Eu implementei a autenticação por cabeçalho X-API-Key como qualquer pessoa sensata — e metade dos clientes MCP que testei não conseguiam se conectar.

Acontece que:

• Alguns clientes usam o cabeçalho X-API-Key
• Alguns usam Authorization: Bearer <key>
• Alguns colocam em parâmetros de consulta como api_key
• Alguns colocam em parâmetros de consulta como apiKey

Lição: Suporte os quatro. É apenas algumas linhas de código, e a compatibilidade vai te poupar tanta dor de cabeça.

@Component
public class McpAuthFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) 
            throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;

        // Tente todos os locais comuns
        String apiKey = httpRequest.getHeader("X-API-Key");
        if (apiKey == null || apiKey.isEmpty()) {
            apiKey = httpRequest.getHeader("Authorization");
            if (apiKey != null && apiKey.startsWith("Bearer ")) {
                apiKey = apiKey.substring(7);
            }
        }
        if (apiKey == null || apiKey.isEmpty()) {
            apiKey = httpRequest.getParameter("api_key");
        }
        if (apiKey == null || apiKey.isEmpty()) {
            apiKey = httpRequest.getParameter("apiKey");
        }

        if (!validateApiKey(apiKey)) {
            HttpServletResponse httpResponse = (HttpServletResponse) response;
            httpResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Chave de API inválida");
            return;
        }

        chain.doFilter(request, response);
    }
}

A pegadinha: As requisições de pré-vôo CORS OPTIONS não incluem autenticação. Certifique-se de pular a autenticação para OPTIONS:

if ("OPTIONS".equalsIgnoreCase(httpRequest.getMethod())) {
    chain.doFilter(request, response);
    return;
}

2. Nunca retorne uma resposta vazia

Eu aprendi isso da maneira difícil quando meu servidor MCP não retornou nada para um resultado de busca vazio. O cliente simplesmente ficou travado para sempre. Sem mensagem de erro, sem timeout, apenas... nada.

Lição: Sempre retorne um texto legível por humanos, mesmo quando não houver resultados.

// ❌ Ruim
{