Agentes IA · Servidor MCP

Servidor Mock Local

O start_mock_server levanta, na tua máquina, um servidor que emula a API Developer do Acapadev e redireciona para ele todas as ferramentas do MCP. Serve para o ciclo de teste ser instantâneo e offline: sem latência de rede, sem depender da disponibilidade da plataforma, e com estado descartável para se poderem fazer testes destrutivos à vontade.

Custo e requisitos: nenhum

É uma pergunta legítima antes de adotar algo assim, por isso vale a pena ser explícito. O mock corre em node:http e node:crypto — módulos do próprio Node. Não acrescenta dependências ao pacote, não precisa de configuração de servidor, não abre portas para fora da tua máquina e não tem qualquer custo. É um processo local que existe enquanto o quiseres e desaparece quando o parares.

Utilização

"Testa a minha integração contra o mock local."

Ou, diretamente, o prompt testar_offline. Por baixo:

Ferramenta	Efeito
`start_mock_server`	Arranca o mock (porta 9999 por omissão) e passa a redirecionar todas as ferramentas para ele. Devolve o `app_id` da app de demonstração já criada.
`get_mock_server_status`	Diz se está a correr, em que URL, e quantos registos tem em memória.
`stop_mock_server`	Para o servidor, descarta o estado e devolve as ferramentas ao endpoint real.

O que é emulado

Toda a superfície da API Developer que as ferramentas usam: apps, resolução por domínio, configuração de pagamentos, planos, faturas, cobranças, simulação, entregas de webhook, assinaturas e métricas. Um pedido a um endpoint não emulado devolve 404 com uma mensagem explícita, em vez de falhar de forma silenciosa.

Os prazos de validade das cobranças são os mesmos da plataforma real:

Método	Validade no mock
`REF`	3 dias
`GPO`	60 segundos
`EKZ`	5 minutos
`RDP`	1 hora
`WIP`	sem expiração documentada

Os webhooks são reais

Esta é a decisão que torna o mock útil em vez de decorativo. O mock não finge entregar o webhook: faz um POST HTTP verdadeiro ao teu endpoint, assinado com o mesmo esquema HMAC-SHA256 no cabeçalho X-AcapaDev-Signature.

Consequência prática: se a verificação de assinatura no teu código estiver mal feita — a assinar o JSON reserializado em vez do corpo bruto, por exemplo — falha aqui exatamente como falharia em produção. O mock não te dá uma falsa sensação de segurança.

Como o mock corre em localhost, o teu endpoint de desenvolvimento também pode estar em localhost: não precisas de túnel (ngrok, Expose) para testar o handler. É a principal vantagem prática sobre testar contra a plataforma.

Segurança

Escuta apenas em 127.0.0.1. O mock aceita qualquer token, por isso nunca pode ficar acessível fora da máquina.
Enquanto está ativo, todas as respostas das ferramentas levam um aviso à cabeça. O risco desta funcionalidade não é técnico — é alguém ler um resultado e julgar que configurou a plataforma quando na verdade configurou um processo local que desaparece ao ser parado.
O get_environment_context devolve mock_server_active e força is_production: false, para o assistente nunca confundir os dois.
O mock é parado automaticamente se o processo do MCP receber SIGINT ou SIGTERM, para não ficar um servidor pendurado.

Quando usar o mock e quando usar Test

	Mock local	Ambiente Test
Velocidade	Instantâneo	Latência de rede
Precisa de internet	Não	Sim
Precisa de túnel para o webhook	Não	Sim, se o teu endpoint for local
Estado	Em memória, descartado ao parar	Persistente, visível no portal
Fidelidade	Alta, mas é uma emulação	É a plataforma

Usa o mock para iterar depressa enquanto escreves o handler, e o ambiente Test para a validação final, antes de promoveres. O mock encurta o ciclo de correção; não substitui o teste contra a plataforma.

← Prompts API Developer →