Agentes IA · Servidor MCP

Prompts: fluxos de trabalho num comando

Além das ferramentas e dos resources, o protocolo MCP tem um terceiro conceito: os Prompts. São fluxos de trabalho que o servidor entrega ao teu editor, e que aparecem como comandos rápidos — não tens de escrever o pedido nem de te lembrar da ordem certa dos passos.

A diferença face a escreveres o pedido à mão não é a poupança de teclas. É a instrução de método: o prompt não diz apenas o que fazer, diz por que ordem, o que ler primeiro, o que nunca fazer sem confirmação e como validar o resultado. É isso que separa uma tentativa de integração de uma integração que fica testada.

Como usar

Depende do cliente. No Claude Code e no Claude Desktop os prompts aparecem na lista de comandos do servidor; no Cursor e no Windsurf, no seletor de prompts MCP. Alguns aceitam argumentos opcionais — quando os omites, o assistente deduz o valor a partir do teu projeto.

Os seis prompts

integrar_pagamentos

Integração completa, do princípio ao fim. Argumentos opcionais: framework e webhook_url — omitidos, são deduzidos do projeto.

Instrui o assistente a:

• ler o quickstart e a documentação de webhooks antes de escrever código;
• deduzir a app a partir do domínio, em vez de te perguntar qual é;
• não rodar o webhook_secret se já existir um — perguntar primeiro, porque rodar quebra o código que já o usa;
• partir dos snippets oficiais em vez de compor código do zero;
• validar com trigger_test_payment_webhook e corrigir-se sozinho enquanto a resposta não for 2xx;
• nunca tocar em apps live durante a tarefa.

diagnosticar_webhook

Para quando os pagamentos não chegam à aplicação. Faz o diagnóstico por eliminação, do mais provável para o menos: primeiro a configuração (o evento está subscrito? há segredo?), depois o histórico de entregas, e só então o código. Traz a tabela de interpretação dos códigos HTTP, para o assistente saber que um 401 aponta quase sempre para a assinatura ser calculada sobre o JSON reserializado em vez do corpo bruto, e que um 419 é CSRF por excluir.

checklist_producao

Verificação de prontidão para Live. É deliberadamente uma tarefa de leitura: o assistente inspeciona, lista o que falta preparar, e pergunta antes de agir. Recusa avançar se nunca tiver havido uma entrega bem sucedida do invoice.paid em Test — nesse caso a integração não está validada, e não faz sentido promovê-la.

auditar_seguranca

Revisão da conta de developer: logins recentes, dispositivos de confiança e configuração de todas as apps nos dois ambientes. Assinala apps live sem webhook_secret, eventos subscritos sem webhook definido, e webhooks em http://. Sugere, mas não revoga nem roda nada.

relatorio_receita

Resumo de faturação com comparação com o período anterior e estado das assinaturas. Argumentos opcionais: app_id e period. Se os dados vierem de uma app de Test, o assistente é instruído a avisar-te logo à cabeça que são pagamentos simulados.

testar_offline

Levanta o servidor mock local e percorre o ciclo completo sem tocar na plataforma, terminando com o mock parado.

Porque é que a instrução de método importa

Um pedido escrito à mão — "integra os pagamentos" — deixa por dizer tudo o que interessa. O assistente pode começar pelo código em vez da documentação, criar uma app nova quando já existia uma, rodar um segredo que estava em uso, ou dar a tarefa por terminada sem nunca ter verificado se o handler responde. Nenhuma destas coisas é um erro de raciocínio: é ausência de contexto.

Os prompts fecham essa lacuna de uma vez, e ficam versionados connosco — quando a plataforma muda, o método muda com ela, sem teres de reescrever nada.