Crie prompts reutilizáveis que estruturam como o modelo interage com seu server.
No contexto do MCP, prompts são templates de instrução que o server oferece ao modelo. Eles são diferentes de tools (que executam ações) e resources (que fornecem dados). Prompts estruturam como o modelo deve pensar e responder em cenários específicos, usando o decorator @mcp.prompt() para registrá-los no server.
Um prompt MCP é um template reutilizável que define instruções para o modelo. Enquanto tools executam ações concretas (buscar dados, enviar mensagens) e resources expõem dados estáticos (arquivos, configurações), prompts definem padrões de interação — como o modelo deve analisar código, gerar relatórios ou formatar respostas. O decorator @mcp.prompt() registra uma função Python como um prompt disponível no server, que o client pode listar e invocar.
Pense em prompts como receitas pré-definidas para o modelo. Em vez de o usuário escrever "analise este código focando em bugs, performance e legibilidade" toda vez, o server oferece um prompt "revisar_codigo" pronto. O client escolhe o prompt, o server retorna as instruções formatadas, e o modelo sabe exatamente o que fazer. É reutilização de conhecimento em forma de instruções.
O prompt mais básico é uma função decorada com @mcp.prompt() que retorna uma string. Essa string contém as instruções que serão enviadas ao modelo. Simples, direto e poderoso — basta definir a função e o MCP cuida do resto.
Criar um prompt simples requer apenas o decorator e uma função que retorna string:
O nome da função (revisar_codigo) vira o identificador do prompt. A docstring vira a descrição. A string retornada vira o conteúdo do prompt enviado ao modelo.
Prompts estáticos são úteis, mas o verdadeiro poder aparece quando você adiciona parâmetros dinâmicos. Usando type hints do Python, o MCP detecta automaticamente os parâmetros e os expõe ao client, que pode preenchê-los antes de invocar o prompt.
Parâmetros são definidos como argumentos da função com type hints:
O MCP usa os type hints para informar ao client quais parâmetros são esperados. O client apresenta campos para o usuário preencher (ex: tipo="vendas", periodo="Q1 2025") antes de invocar o prompt.
Use nomes descritivos para os parâmetros — tipo e periodo são melhores que t e p. O client exibe esses nomes para o usuário, então clareza importa. Se um parâmetro é opcional, use Optional[str] = None como type hint.
O client lista os prompts disponíveis e vê "gerar_relatorio" com parâmetros tipo (str) e periodo (str).
O usuário preenche os parâmetros: tipo="vendas", periodo="março 2025".
O server executa a função, substitui os parâmetros na string e retorna o prompt completo para o modelo.
O client MCP pode solicitar a lista de todos os prompts disponíveis no server, incluindo seus nomes, descrições e parâmetros. Isso permite que interfaces de usuário exibam um catálogo de prompts disponíveis, tornando a experiência intuitiva e auto-documentada.
O protocolo MCP define o método prompts/list que retorna todos os prompts registrados no server. Para cada prompt, o client recebe: o nome (derivado do nome da função), a descrição (derivada da docstring da função) e a lista de parâmetros (derivada dos type hints). Isso significa que a documentação do prompt é gerada automaticamente a partir do código Python — não é necessário manter documentação separada.
O que o client recebe ao listar prompts:
Prompts MCP brilham quando você tem padrões de interação que se repetem frequentemente. Em vez de cada usuário escrever suas próprias instruções (muitas vezes de forma inconsistente), o server oferece prompts padronizados e testados que garantem resultados de alta qualidade.
Os melhores prompts MCP encapsulam expertise do domínio em templates reutilizáveis. Um prompt de análise de código pode incluir critérios que um desenvolvedor sênior usaria. Um prompt de relatório pode seguir o formato oficial da empresa. A ideia é transformar conhecimento tácito em instruções explícitas e compartilháveis, permitindo que qualquer usuário obtenha resultados de nível especialista.
Prompt que instrui o modelo a revisar código focando em bugs, segurança, performance e legibilidade — com checklist padronizado da equipe.
Prompt parametrizado que gera relatórios em formato específico com métricas, gráficos sugeridos e recomendações acionáveis.
Prompt que transforma dados brutos em tabelas formatadas, JSON estruturado ou CSV — com regras de validação embutidas.
Prompt que gera emails profissionais seguindo o tom e formato da empresa, com parâmetros para destinatário, assunto e contexto.
Prompt que analisa documentação técnica verificando clareza, completude, exemplos e consistência com padrões do projeto.
Antes de disponibilizar prompts para uso em produção, é essencial testá-los. O MCP Inspector permite listar todos os prompts do server, visualizar parâmetros esperados e invocar prompts manualmente para verificar que as instruções geradas são corretas e completas.
O MCP Inspector é a ferramenta ideal para testar prompts. Na aba "Prompts", ele lista todos os prompts registrados com seus nomes, descrições e parâmetros. Você pode preencher os parâmetros e clicar em "Get Prompt" para ver exatamente o que será enviado ao modelo. Isso permite validar que as instruções estão completas, que os parâmetros são substituídos corretamente e que o formato está adequado — tudo sem precisar conectar ao Claude Desktop.
Teste cada prompt com valores extremos: strings vazias, textos muito longos, caracteres especiais. Verifique que o prompt lida bem com edge cases. Se um parâmetro é opcional, teste com e sem ele. Se o prompt usa f-strings, confirme que a interpolação funciona corretamente para todos os cenários previstos.
Prompts não validam parâmetros automaticamente — se o client enviar uma string vazia para um parâmetro obrigatório, o prompt será gerado com o espaço em branco. Sempre valide os parâmetros dentro da função antes de construir a string de retorno. Use if not tipo: raise ValueError("tipo é obrigatório") para garantir que dados inválidos não passem silenciosamente.
@mcp.prompt() — diferentes de tools e resources.
Próximo Módulo: 3.8 — Tratamento de Erros