Como implementar MCP Sampling: o guia para servidores proativos

O MCP Sampling permite que um servidor envie uma requisição 'sampling/createMessage' ao cliente, como o Claude Desktop, solicitando que este execute um prompt no modelo. Diferente de chamadas diretas de API, o sampling utiliza a chave de API e as configurações de segurança já presentes no host, permitindo que o servidor peça ao Claude para resumir dados, tomar decisões ou gerar logs sem que o servidor precise de credenciais próprias ou acesso direto à internet.

Desde o lançamento do Model Context Protocol (MCP), a maioria dos desenvolvedores foca no fluxo tradicional: o Claude (cliente) chama uma ferramenta (ferramenta/tool) em um servidor. No entanto, existe um recurso poderoso e muitas vezes subutilizado chamado Sampling. Esta funcionalidade inverte a lógica de controle, permitindo que o servidor ‘peça um favor’ ao modelo. Em arquiteturas de agentes complexos, o Sampling é o que diferencia um servidor estático de uma extensão de inteligência verdadeiramente integrada. Para entender a especificação técnica completa, consulte a documentação oficial em modelcontextprotocol.io.

O que é o MCP Sampling e por que ele é revolucionário?

Tradicionalmente, um servidor MCP é passivo; ele espera ser chamado para fornecer dados ou executar uma função. Com o Sampling, o servidor ganha a capacidade de iniciar uma interação com o LLM através do cliente (o host). Quando um servidor precisa, por exemplo, classificar um arquivo de log volumoso antes de enviá-lo ou decidir qual próxima ferramenta deve ser sugerida ao usuário, ele pode emitir uma chamada sampling/createMessage.

O grande diferencial aqui é a intermediação do cliente. O servidor não fala diretamente com a Anthropic; ele envia o pedido para o Claude Desktop ou para o Claude Code, que por sua vez solicita a aprovação do usuário (se configurado) e executa a tarefa. Isso mantém a soberania dos dados e o controle de custos nas mãos do usuário final, e não do desenvolvedor do servidor. Segundo a documentação da Anthropic, essa arquitetura reforça o princípio de privilégio mínimo, pois o servidor nunca toca na chave de API do usuário.

Sampling vs. Chamada Direta de API: Quando usar cada uma?

A escolha entre usar MCP Sampling ou fazer uma chamada direta via SDK da Anthropic no servidor depende de três fatores: segurança, custo e contexto. Se o seu servidor MCP precisa de acesso total e irrestrito ao modelo, sem depender da interface do usuário, a API direta é o caminho. Contudo, o Sampling brilha em cenários de ecossistema aberto.

O Sampling é ideal para servidores que serão distribuídos para terceiros, onde você não quer (ou não pode) gerenciar os custos de inferência dos seus usuários. Ao usar o Sampling, o processamento é cobrado na conta do usuário que está rodando o Claude.

Como configurar as permissões de Sampling no host?

Para que um servidor consiga realizar amostragem, o cliente (host) deve explicitamente conceder essa capacidade. No protocolo MCP, isso é definido durante a fase de inicialização (initialize). O servidor deve declarar que deseja a capacidade de amostragem, e o cliente deve responder confirmando que a suporta.

Se você estiver usando o Claude Desktop, as permissões são geralmente solicitadas via interface gráfica quando o servidor tenta a primeira chamada. Para desenvolvedores criando seus próprios clientes MCP, é crucial implementar um sistema de ‘consentimento por servidor’. Você não quer que um servidor malicioso use todo o seu saldo de tokens em segundo plano. Detalhes sobre o handshake de capacidades podem ser encontrados em docs.claude.com.

Passo a passo: Implementando ‘sampling/createMessage’ no servidor

Para implementar o Sampling no seu servidor (usando o SDK em TypeScript ou Python), o fluxo segue estes passos:

1. Verificação de Capacidade: Antes de solicitar o sampling, verifique se o result.capabilities.sampling está presente na resposta de inicialização do cliente.
2. Construção do Pedido: O servidor envia uma requisição sampling/createMessage contendo as mensagens (role e content), o sistema de prompt e os parâmetros do modelo (como temperatura e tokens máximos).
3. Inclusão de Contexto: Você pode solicitar que o cliente inclua recursos (resources) ou metadados da sessão atual na chamada para dar mais contexto ao Claude.
4. Processamento da Resposta: O cliente retorna um objeto contendo o texto gerado e informações sobre qual modelo foi utilizado.

Exemplo de lógica de prompt no servidor: “Claude, analise estes 50 nomes de arquivos que acabei de ler do disco e me diga quais parecem ser arquivos de configuração sensíveis”. O servidor recebe a resposta estruturada e pode então proceder com a lógica de negócio, como mover esses arquivos para uma pasta segura.

Melhores práticas para evitar loops infinitos de amostragem

Um risco real ao usar Sampling é a criação de loops infinitos: o Claude chama uma ferramenta, a ferramenta chama o Sampling, que gera uma resposta que faz o Claude chamar a ferramenta novamente. Para evitar isso, a especificação MCP sugere:

• Limitar a Profundidade: Sempre defina um contador de recursão no seu servidor.
• Prompts Específicos: Use prompts de sistema no Sampling que instruam o modelo a ser conciso e a não tentar chamar novas ferramentas a menos que seja estritamente necessário.
• Filtros de Parada: Utilize o parâmetro stopSequences para garantir que o modelo não divague.
• Monitoramento de Custos: Como o Sampling consome tokens do usuário, forneça logs claros no servidor sobre quantas chamadas de amostragem estão sendo realizadas.

Para mais guias sobre o ecossistema e ferramentas de depuração, visite code.claude.com/docs.

Leia mais no site

• Como implementar Human-in-the-loop (HITL) em Agentes Claude via MCP?
• Como implementar RBAC e Filtragem de Ferramentas em Servidores MCP?
• Como implementar Autenticação OAuth em Servidores MCP para o Claude?
• Como filtrar dados sensíveis em Agentes Claude usando MCP?
• Como implementar Human-in-the-Loop em agentes com Claude?

#Mcp #Anthropic Api #Desenvolvimento #Seguranca #Agentes