MCP Server de Pesquisa
Pesquisa pessoal em padrões de design para servidores MCP úteis de verdade - além do hello-world, com auth, paginação e tratamento de erros transparente para o agente.
Quase todo exemplo de MCP para no brinquedo. A engenharia mora na produção.
O Model Context Protocol é um protocolo aberto que deixa agentes de IA se conectarem a ferramentas e dados externos via servidores que expõem tools, resources e prompts - por stdio ou HTTP. A ideia é ótima, mas a maioria dos exemplos para em uma tool que soma dois números e nunca encosta no que realmente importa.
O que importa é justamente a parte chata: autenticação e autorização para servidores remotos, paginação de resultados grandes para não inundar o agente, e erros transparentes e acionáveis em vez de stack traces opacos. É aí que mora a engenharia de verdade - e é o que quase ninguém documenta.
Projeto pessoal: mapear os padrões que separam um servidor MCP de brinquedo de um servidor de produção.
- - Autenticação e autorização: OAuth 2.1 com PKCE para servidores remotos, tokens com escopo por tool e checagem antes de qualquer ação sensível - nada de credencial única para tudo.
- - Paginação token-aware: cursores em operações de listagem, com o limite descrito no próprio schema para o modelo saber que a resposta é paginada.
- - Tratamento de erros transparente: erros estruturados em JSON-RPC que o agente consegue interpretar e dos quais consegue se recuperar.
- - Design de tools e resources: contratos tipados com Zod, idempotência onde faz sentido e respostas conscientes do orçamento de tokens.
- - Claude Agent SDK como bancada: uso o SDK como harness para exercitar o servidor com um agente real e ver onde os padrões quebram na prática.
Sair do hello-world e tratar o servidor como uma API de verdade.
A maioria dos exemplos para em uma tool que soma dois números. A engenharia real começa quando o servidor expõe dados de produção e precisa de contrato, limite e versionamento.
Desenhar tools pensando no orçamento de tokens do agente.
Schema de tool é custo fixo - carrega toda vez que a tool está disponível. Nomes curtos e sem ambiguidade, descrições enxutas e respostas que cabem na janela em vez de despejar tudo de uma vez.
Paginar resultados grandes para não inundar o modelo.
Operações de listagem usam cursor e limite, com o comportamento explícito no schema. O agente pede a próxima página quando precisa - o servidor não tenta entregar dez mil linhas em uma resposta só.
Errar de forma que o modelo consiga se recuperar.
Erro estruturado, com código e mensagem acionável, em vez de stack trace opaco. O agente lê o erro, entende o que fazer (renovar token, ajustar argumento, tentar de novo) e segue - sem travar a tarefa.
Em vez de mais uma tool de brinquedo, está virando um conjunto honesto de padrões para servidores MCP que aguentariam usuário real - com as arestas ainda aparentes.
- - Os padrões estão sendo documentados conforme apareceram, não como teoria fechada - cada um nasceu de uma falha concreta ao exercitar o servidor com o agente.
- - Auth via OAuth com escopo por tool já está mapeada; o trade-off entre service-account e on-behalf-of ainda está em aberto.
- - Paginação por cursor reduziu de forma clara o estouro de janela em listagens grandes; falta padronizar o formato do cursor entre tools.
- - Continua sendo pesquisa pessoal e em curso, não um produto entregue - o objetivo é o playbook, não o servidor em si.