Agentes IA · Servidor MCP
Referência das Ferramentas
O servidor expõe 29 ferramentas. Não precisas de as decorar nem de as invocar pelo nome —
o assistente escolhe-as a partir do que lhe pedes em linguagem natural. Esta referência existe para
saberes o que é possível e, quando algo corre mal, o que é que foi realmente chamado.
O app_id é sempre o ID numérico da app, não o client_id.
O assistente deduz-no com find_app_by_url.
Contexto e descoberta
| Ferramenta | Parâmetros | Descrição |
|---|
get_environment_context |
— |
Ambiente assumido, URL da API em uso, se o servidor mock local está ativo, e o perfil autenticado. O primeiro passo natural de qualquer tarefa. |
find_app_by_url |
url, environment |
Resolve o app_id a partir de um domínio, comparando com o redirect, homepage, origens permitidas e webhooks de cada app. |
verify_local_environment |
project_path |
Analisa o projeto na tua máquina, sem qualquer chamada à API: deteta a framework, lê o .env, verifica se as credenciais estão presentes e preenchidas, se o .env está no .gitignore, se há cliente HTTP, e se já existe um handler de webhook com verificação de assinatura. Nunca devolve o valor de um segredo. |
get_user_profile |
— |
Dados do perfil autenticado e contexto da aplicação atual. |
O verify_local_environment é o passo natural antes de tudo o resto: evita que o
assistente reescreva um handler que já existe, e apanha problemas — credenciais por
preencher, .env versionado — antes de se perder tempo na plataforma.
Segurança da conta
| Ferramenta | Parâmetros | Descrição |
|---|
list_my_login_history | — | Histórico de logins recentes: data, IP e browser. |
list_trusted_devices | — | Dispositivos marcados como de confiança, que não pedem 2FA. |
revoke_trusted_device | device_id | Revoga remotamente a confiança de um dispositivo. |
Apps OAuth
| Ferramenta | Parâmetros | Descrição |
|---|
list_my_oauth_apps |
environment |
Lista as tuas apps. Omitir o ambiente devolve todas — útil para encontrar o par Test/Live da mesma app. |
get_oauth_app_details |
app_id |
Detalhes de uma app, incluindo client_id e ambiente. |
create_oauth_app |
name, redirect, description, website, environment |
Cria uma app. Devolve o client_secret — é a única altura em que ele é revelado sem invalidar o anterior. |
rotate_oauth_client_secret |
app_id |
Destrutivo. Gera um novo client_secret e invalida o anterior, quebrando qualquer integração M2M em curso. |
update_app_webhooks |
app_id, webhook_url, webhook_events |
Configura o webhook geral de identidade. A lista de eventos substitui a atual. |
rotate_webhook_secret |
app_id |
Destrutivo se já houver um em uso. Gera o segredo de assinatura dos payloads. As verificações do código atual falham até o novo valor ser publicado. |
Eventos aceites por webhook_events:
| Evento | Quando dispara |
|---|
invoice.paid | Uma fatura da app foi liquidada. |
user.logout | Um utilizador terminou sessão no SSO (single sign-out). |
user.updated | O perfil de um utilizador foi alterado. |
user.role_updated | Os papéis de um utilizador na app mudaram. |
partner.created, partner.approved, partner.rejected, partner.role_updated | Ciclo de vida do Portal de Parceiros. |
Configuração de pagamentos
| Ferramenta | Parâmetros | Descrição |
|---|
get_payment_api_config |
app_id |
O contrato completo numa chamada: chaves, se o gateway está simulado, eventos subscritos, métodos de pagamento com prazos, esquema de assinatura e todos os endpoints. É o que evita perguntas ao utilizador. |
update_payment_config |
app_id, billing_webhook_url, subscribe_invoice_paid |
Atualização parcial — campos omitidos ficam como estão. Sem subscribe_invoice_paid: true, o evento nunca é enviado. |
Planos de assinatura
| Ferramenta | Parâmetros | Descrição |
|---|
list_plans | app_id | Catálogo de planos da app, ativos e inativos. |
sync_plans |
app_id, plans[] |
Declarativo. Envia sempre o catálogo completo: os planos que existam mas não venham no payload passam a inactive (nunca são apagados). |
Cada plano em plans[]:
| Campo | Obrigatório | Notas |
|---|
reference_code | Sim | Identificador estável no teu sistema (ex: pro_mensal). É a chave de sincronização — nunca o mudes depois de criado. |
name | Sim | Nome visível do plano. |
price | Sim | Preço na moeda indicada. |
billing_cycle | Sim | monthly, yearly ou one_time. |
currency | Não | AOA (omissão), USD ou EUR. |
description, features, status | Não | status assume active. |
Faturas e cobranças
| Ferramenta | Parâmetros | Descrição |
|---|
create_invoice |
app_id, customer_name, items[], customer_email, customer_nif, currency, app_reference, due_date, metadata |
Cria uma fatura. O total é a soma de quantity × unit_price. Numa app Test fica marcada como sandbox. Devolve o UUID e o pay_url do checkout hospedado. |
get_invoice |
app_id, invoice_id |
Estado atual, última transação e prazo de validade. Consulta o gateway ao vivo, com rate-limit de 15 s por fatura. |
create_test_charge |
app_id, invoice_id, payment_method, phone_number |
Só em Test. Gera uma cobrança simulada, para veres a forma exata dos dados que a tua UI vai mostrar. |
simulate_invoice_payment |
app_id, invoice_id |
Só em Test. Marca a fatura como paga e dispara o invoice.paid real, com payload e assinatura verdadeiros. |
Métodos aceites por payment_method:
| Código | Método | phone_number | Validade |
|---|
REF | Referência Multicaixa (AppyPay/Pay4All) | Não | 3 dias |
GPO | Multicaixa Express | Sim | 60 segundos |
EKZ | E-Kwanza | Sim | 5 minutos |
RDP | RedotPay (criptomoeda/stablecoins) | Não | 1 hora |
WIP | WiPay (hospedado) | Opcional | sem expiração documentada |
Validação e diagnóstico
| Ferramenta | Parâmetros | Descrição |
|---|
trigger_test_payment_webhook |
app_id, total, currency, app_reference |
Envia um invoice.paid de teste e devolve, de forma síncrona, o código HTTP e o corpo com que o teu endpoint respondeu. Não cria faturas — é seguro repetir. |
list_webhook_deliveries |
app_id, event_type, limit |
Histórico de entregas com estado HTTP e corpo da resposta. A ferramenta a usar quando um pagamento não chega à aplicação. |
Gestão pós-venda
| Ferramenta | Parâmetros | Descrição |
|---|
list_subscriptions |
app_id, status, user_id, plan_reference_code, limit |
Assinaturas da app, com plano, cliente e data de expiração. Responde a "quem está subscrito?" sem sair do editor. |
cancel_subscription |
app_id, subscription_id |
Cancela a assinatura de um cliente. Não devolve dinheiro nem altera faturas já pagas — apenas impede a renovação. Fica registado no log de auditoria. |
get_revenue_metrics |
app_id, period, currency |
Total pago no período, número de faturas, valor médio, montante pendente e série diária. Períodos: today, 7d, 30d, 90d, ytd, all. |
As métricas de uma app de Test trazem is_simulated: true. São pagamentos
simulados, não receita — o assistente é instruído a avisar-te disso antes de apresentar
qualquer número.
Servidor mock local
| Ferramenta | Parâmetros | Descrição |
|---|
start_mock_server |
port |
Levanta um servidor local que emula a API e redireciona todas as ferramentas para ele. Ver Servidor mock. |
stop_mock_server |
— |
Para o mock, descarta o estado e devolve as ferramentas ao endpoint real. |
get_mock_server_status |
— |
Se está a correr, em que URL, e quantos registos tem em memória. |
Operações destrutivas
Três ferramentas têm efeitos irreversíveis. O servidor sinaliza-as ao assistente, mas convém saberes quais são:
| Ferramenta | Consequência |
|---|
rotate_oauth_client_secret | Toda a autenticação M2M em curso com o segredo antigo passa a falhar. |
rotate_webhook_secret | Todas as verificações de assinatura no teu código passam a falhar até publicares o novo valor. |
revoke_trusted_device | O dispositivo volta a pedir 2FA no próximo login. |
cancel_subscription | Afeta um cliente real: a assinatura deixa de renovar. Não é reversível pela API. |
