Capítulo 3 — Primitivas de Servidor: Expondo Contexto e Capacidades

Terceira postagem do passeio capítulo a capítulo pelo LLM Primer IV: Projetando a Cognição da IA com MCP. Em que aprendemos o que um servidor MCP pode de fato dizer — três substantivos, três ciclos de vida, três modelos de erro — e por que a disciplina de escolher o certo decide se um servidor escala ou se acumula.

Por que este capítulo existe

Um protocolo é útil só na medida do que ele permite você dizer. O Capítulo 2 construiu o modelo mental de host, cliente e servidor, e assistiu a uma sessão ganhar vida através da negociação de capacidades. Uma vez completo o handshake e ambos os lados sabendo o que o outro pode fazer, o que está concretamente em jogo? O MCP responde com três substantivos: Resources, Prompts e Tools. Eles parecem superficialmente semelhantes — cada um é uma coisa nomeada, descrita por schema, que o servidor pode produzir ou rodar — mas mapeiam para três intenções distintas. Resources são estado de leitura. Prompts são andaime reutilizável. Tools são ações de escrita. O capítulo percorre cada um por vez: schema, ciclo de vida, modelo de erro, e os lugares onde engenheiros se confundem.

3.1 Resources: dados contextuais somente leitura

Um resource é dado que o servidor pode entregar ao modelo como contexto. A palavra definidora é somente leitura. Um resource não muta o mundo; ele o descreve. Se uma busca causa mudança de estado em outro lugar — uma linha de log de auditoria, um contador incrementado, um webhook disparado — não é resource, é tool fantasiada. Traçar essa linha com nitidez é a primeira disciplina de design de servidor MCP.

Cada resource tem uma URI estável num scheme que o servidor escolhe (file://, postgres://, linear://issue/ENG-1234), mais metadados: nome, descrição opcional, tipo MIME, tamanho opcional. Nenhum desses campos é decorativo. Um resource sem descrição é um que o modelo não consegue avaliar. O ciclo de vida é direto: resources/list para enumerar, resources/read para buscar. Não há resources/write — se o servidor quer escritas, deve expor uma tool. A assimetria mantém a fronteira de confiança visível.

Dois padrões tornam resources práticos em escala. Templates de URI permitem ao servidor expor um endpoint de leitura parametrizado (db://orders/{order_id}) em vez de enumerar milhões de linhas. Subscriptions permitem ao host registrar interesse numa URI e receber notifications/resources/updated quando o dado subjacente muda — a alternativa é fazer polling em cadência de LLM, o que é desperdício de mão dupla. A armadilha a evitar é despejar todo objeto interno na lista de resources no início de sessão: uma lista de três mil resources come dezenas de milhares de tokens antes que o usuário digite qualquer coisa. Exponha um topo curado mais templates, e deixe o modelo buscar na cauda longa.

3.2 Prompts: templates e workflows reutilizáveis

Prompts no MCP não têm nada a ver com o system prompt de um LLM. São templates reutilizáveis definidos pelo servidor que um usuário — ou um host em nome de um usuário — pode invocar para começar uma interação particular. Um prompt é mais próximo de um comando slash do que de uma personalidade. O ponto é deixar um servidor entregar padrões de interação validados junto com as tools e resources que expõe, para que o humano no teclado não precise lembrar como frasear o pedido.

Um prompt tem um nome, uma descrição opcional, e uma lista de argumentos. O host chama prompts/list para descobrir, depois prompts/get para expandir um prompt numa sequência de mensagens que o host pode alimentar no seu loop de modelo. O prompt pode referenciar resources por URI, caso em que o host os inlina antes de enviar. O servidor escreve o roteiro dos turnos de abertura; o modelo segue dali.

A distinção entre prompts e mensagens de sistema importa. Um usuário invocando /review_pr vê, no seu log de conversa, o assistente começando a trabalhar numa revisão — ele entende o que começou, pode interromper, pode auditar. Se o servidor em vez disso anexasse silenciosamente instruções ao system prompt do host, o usuário não teria ideia de por que o assistente subitamente se comportou diferente. Prompts são andaime visível ao usuário; system prompts são o enquadramento do host. Os dois não devem ser confundidos. A disciplina é que qualquer conteúdo de prompt que o usuário não aprovaria se mostrado explicitamente é um defeito.

3.3 Tools: ações, saídas estruturadas, idempotência

Tools são onde o MCP fica interessante e perigoso em medida igual. Resources são leitura; prompts são andaime; tools são escrita — criam linhas, mandam mensagens, fazem deploy de serviços, cobram cartões. Cada tool tem um nome, uma descrição, e um schema de entrada em JSON Schema. A descrição é o campo mais importante em toda a superfície MCP, porque é o texto que o modelo usa para decidir se chama a tool, quando chama, e com que argumentos. Uma tool cuja descrição diz "manda um email" é uma à qual o modelo recorre sempre que aparece intenção em formato de email. Uma tool cuja descrição diz "manda um email transacional pela plataforma de marketing, somente para endereços de cliente verificados; não para correspondência pessoal" é uma que o modelo usa com mais discriminação.

O modelo de erro tem dois canais. Um erro de protocolo (argumentos malformados, tool desconhecida) retorna um erro JSON-RPC e é falha de framing. Um erro de tool (destinatário rejeitado, disco cheio) retorna uma resposta de sucesso com isError: true e um bloco de conteúdo explicando o que aconteceu. A distinção importa: o modelo deveria ver erros de tool e se adaptar; o host deveria ver erros de protocolo e recuperar o transporte. Confundir os dois rouba do modelo a informação que ele precisa.

MCP moderno suporta structuredContent ao lado do array de conteúdo em prosa, conforme com um outputSchema declarado. O efeito composto ao longo de um trace longo é real: saídas curtas e estruturadas deixam o modelo com folga para raciocínio de verdade; saídas longas e em prosa comem o orçamento de contexto. Duas disciplinas adicionais merecem nome. Minimalidade: doze tools bem descritas batem sessenta em quase todo benchmark; exponha find_users com filtro estruturado em vez de list_users, get_user, search_users, count_users. Idempotência: tempestades de retry são inevitáveis; uma tool que aceita uma chave de idempotência ou usa um esquema de identificador determinístico transforma oscilações de rede em no-ops em vez de incidentes de integridade de dados.

3.4 Composição: como as três primitivas cooperam

As primitivas são mais úteis quando trabalham juntas. Um servidor bem desenhado tipicamente expõe um pouco de cada: alguns prompts para semear interações comuns, um pequeno conjunto de tools para as ações que importam, e um conjunto possivelmente grande de resources que fornecem o contexto. Um servidor de suporte ao cliente pode expor perfis de cliente e histórico de tickets como resources, reply_to_ticket e escalate_ticket como tools, e /triage_ticket como prompt que carrega os resources certos e pede ao modelo para classificar. Prompts semeiam; resources preenchem a situação; tools mudam o mundo.

A tentação, uma vez que você vê quão flexíveis são as primitivas, é empurrar tudo por uma só. Você pode fingir resources com tools somente-leitura, fingir tools com prompts que cutucam o modelo a emitir comandos, fingir prompts com resources contendo instruções. Cada uma comprime o espaço de design e perde algo. Resources fingidas como tools não podem ser cacheadas, assinadas, nem inlinadas numa expansão de prompt. Tools fingidas como prompts não podem ser autorizadas no ponto de chamada e não têm canal de saída estruturado. As primitivas não são arbitrárias; são fatoradas para que o host saiba como tratar cada uma com segurança. Honrar a fatoração é parte do contrato do protocolo.

O que o Capítulo 3 prepara

Você percorreu o lado servidor do acordo. Um servidor expõe Resources, Prompts e Tools, cada um com seu próprio schema, ciclo de vida e modelo de erro. A disciplina é escolher a primitiva certa para cada coisa que o servidor pode fazer, nomeá-las e descrevê-las com cuidado, e resistir à sobrecarga. Mas o MCP não é via de mão única. Um host também pode expor capacidades de volta ao servidor — e é aí que moram as escolhas de design mais interessantes e mais sensíveis à segurança do protocolo.

Próximo — Capítulo 4: Primitivas de Cliente — Sampling, Roots, Elicitation. A superfície inversa — o que o host devolve ao servidor — e as implicações de segurança de cada capacidade entregue através da fronteira de confiança.