Agentes IA · Servidor MCP
Resources: o que a IA lê antes de escrever
Além das ferramentas, o protocolo MCP tem um segundo conceito: os Resources. São documentos que o servidor serve ao assistente a pedido, e é isso que separa uma integração que funciona de uma integração que alucina.
Uma ferramenta diz à IA o que ela pode fazer. Um resource diz-lhe como a plataforma funciona. Sem o segundo, a IA infere a arquitetura a partir dos nomes das ferramentas — e inventa detalhes que não existem, como o formato de uma assinatura ou o nome de um campo.
Documentação
| URI | Conteúdo |
|---|---|
acapadev://docs/quickstart |
A receita completa, do princípio ao fim, incluindo os passos de auto-validação e a regra de ouro sobre ambientes. É o primeiro que o assistente lê. |
acapadev://docs/payments |
Autenticação M2M por client_credentials, o ciclo fatura → cobrança → confirmação, os métodos REF/GPO/EKZ/RDP/WIP com os prazos reais, os códigos de erro e a sincronização declarativa de planos. |
acapadev://docs/webhooks |
Destino do evento, esquema de assinatura HMAC, exemplo de verificação em PHP, payload completo do invoice.paid, idempotência e a lista de eventos disponíveis. |
acapadev://docs/environments |
Diferenças de comportamento entre Test e Live, como trabalhar em cada um e o que é preciso repetir ao promover. |
Templates de código
A documentação explica o contrato, mas deixa a estrutura do código ao critério do modelo — que a inventa, e por vezes inventa mal. Os erros são sempre os mesmos três: assinar o JSON reserializado em vez do corpo bruto, esquecer a idempotência, e deixar a rota sujeita à proteção CSRF. Ao servir o template real, o assistente passa a preencher variáveis em vez de compor código do zero.
| URI | Conteúdo |
|---|---|
acapadev://snippets/laravel/webhook-handler |
Rota completa com verificação HMAC sobre o corpo bruto, hash_equals, idempotência e exclusão de CSRF. |
acapadev://snippets/laravel/idempotency-migration |
Migração da tabela processed_payments, com o índice único que faz o trabalho todo. |
acapadev://snippets/laravel/m2m-client |
Serviço com token client_credentials em cache e métodos para fatura, cobrança e estado. |
acapadev://snippets/laravel/config |
Bloco para config/services.php e as chaves correspondentes no .env. |
acapadev://snippets/nodejs/webhook-handler |
Rota Express com express.raw() e comparação em tempo constante. |
acapadev://snippets/nodejs/m2m-client |
Cliente sem dependências, com renovação automática do token. |
acapadev://snippets/php/webhook-handler |
Versão sem framework, para projetos em PHP puro. |
acapadev://snippets/frontend/checkout-flow |
O que o frontend faz em cada método, com polling de estado e contagem decrescente. |
Repara no detalhe do handler em Node: a rota usa express.raw() em vez de
express.json(). É uma armadilha clássica — o parser de JSON consome o corpo e
deixa-te sem o texto original, que é precisamente aquilo sobre o que a assinatura é
calculada. O template já vem com a ordem certa dos middlewares.
Porque é que isto importa
Repara na diferença entre o que uma IA sabe com e sem estes documentos. Sem eles, ao ver uma ferramenta
chamada update_payment_config, ela infere que existe uma configuração de pagamentos — mas não
sabe que a assinatura do billing usa um esquema diferente do dos eventos de identidade, que a
assinatura é calculada sobre o corpo bruto e não sobre o JSON reserializado, ou que o mesmo evento pode
chegar duas vezes. São exatamente os detalhes que produzem bugs subtis em produção.
Estes resources são mantidos por nós e versionados com o servidor. Quando a plataforma muda, a IA passa a ler a versão nova sem que tenhas de reescrever o teu prompt.
Como são consultados
Não tens de fazer nada. Os clientes compatíveis expõem os resources ao modelo, e o assistente lê-os quando a tarefa o justifica. Se quiseres forçar a leitura, basta pedir:
"Lê o quickstart do Acapadev antes de começares."
Em clientes que mostram os resources numa lista (como o Claude Desktop), podes também anexá-los manualmente à conversa.
Os resources são servidos localmente pelo processo do MCP, sem chamada de rede à API. Estão disponíveis mesmo antes do teu PAT ser validado, e não consomem quota.