Agentes IA · Servidor MCP
Servidor MCP do Acapadev ID
O Model Context Protocol (MCP) é um standard aberto criado pela Anthropic que permite a
assistentes de IA — Claude Code, Claude Desktop, Cursor, Windsurf, Antigravity — usarem ferramentas externas.
O @devkussema/acapadev-mcp é o servidor oficial do Acapadev ID: liga o assistente que já usas
à tua conta de developer, às tuas apps OAuth e ao ciclo completo de faturação.
O objetivo não é a IA conseguir chamar a nossa API. É a IA conseguir integrar pagamentos do princípio ao fim sem te perguntar nada — descobrir sozinha qual é a tua app, ler a documentação, escrever o código, testá-lo contra o nosso servidor e corrigir-se quando falha.
O que muda na prática
Sem o MCP, pedir a uma IA para integrar pagamentos gera uma conversa de dez perguntas: qual é o App ID, qual o formato do webhook, como se assina o payload, que métodos existem. Com o MCP, escreves uma frase:
"Integra os pagamentos da Acapadev neste projeto."E o assistente executa sozinho a sequência completa:
1 · Descobre o contexto
Analisa o teu projeto com verify_local_environment, tira o domínio do .env e usa find_app_by_url para deduzir o App ID. Nunca te pergunta qual é a app.
2 · Aprende a arquitetura
Lê os Resources embutidos no servidor — autenticação M2M, assinatura HMAC, métodos de pagamento — em vez de adivinhar.
3 · Configura e escreve o código
Define o webhook de faturação, subscreve invoice.paid, sincroniza planos e escreve o handler no teu projeto.
4 · Testa-se a si própria
Dispara um invoice.paid real contra o teu endpoint e lê o código HTTP com que o próprio código dela respondeu. Se falhar, corrige e repete.
Segurança por omissão: começa sempre em Test
O portal Developer tem dois ambientes, Test e Live, e todas as ferramentas
do servidor assumem test quando o ambiente não é indicado. Em Test, o gateway de pagamentos
(Pay4All/AppyPay e E-Kwanza) é simulado: nenhuma cobrança real é gerada, por mais vezes que o assistente
repita o ciclo. Os webhooks, esses, são entregues a sério nos dois ambientes — é isso que torna a
auto-validação possível sem envolver dinheiro.
As ferramentas que geram cobranças ou liquidam faturas através da API Developer estão bloqueadas em Live. Em produção, a tua aplicação usa as suas próprias credenciais M2M. Ver Ambientes.
O que está incluído
| Capacidade | Conteúdo |
|---|---|
| 29 Tools | Perfil e segurança da conta, gestão de apps OAuth, configuração de pagamentos, planos, faturas, cobranças de teste, diagnóstico de webhooks, assinaturas e métricas de receita. |
| 12 Resources | Quatro documentos sobre a arquitetura da plataforma e oito templates de código oficiais, para o assistente preencher variáveis em vez de inventar estrutura. |
| 6 Prompts | Fluxos de trabalho num comando: integrar pagamentos, diagnosticar webhooks, checklist de produção, auditoria de segurança, relatório de receita e teste offline. |
| Descoberta de contexto | find_app_by_url, get_environment_context e verify_local_environment — deduzem a app, o ambiente e o estado do teu projeto. |
| Loop de auto-validação | trigger_test_payment_webhook devolve, de forma síncrona, a resposta HTTP do teu endpoint. |
| Servidor mock local | Emula a plataforma na tua máquina para testes offline, instantâneos e destrutivos. Sem dependências nem custo. |
Requisitos
- Uma conta Acapadev ID verificada, com acesso ao Portal do Desenvolvedor.
- Um Personal Access Token (PAT) gerado nesse portal.
- Node.js 18 ou superior (o servidor corre via
npx, não precisas de instalar nada no teu projeto). - Um cliente compatível com MCP.