Testes de OTP para agentes de IA

Um agente de IA que controla um navegador para se cadastrar em um serviço esbarra na mesma barreira que um humano: "confira seu e-mail para ver o código". Diferente de um humano, ele não tem uma caixa de entrada para checar — a menos que você dê uma a ele. O servidor MCP da OTPBox faz exatamente isso: entrega ao agente ferramentas para criar uma caixa real, aguardar o e-mail e extrair o código ou link, tudo dentro da mesma conversa que está conduzindo o cadastro.

Por que MCP em vez de um script

Os guias de Playwright/Cypress desta série conectam uma sequência fixa de passos que um humano escreveu com antecedência. Um agente é diferente: ele decide em tempo real se precisa de uma caixa, quando verificá-la e o que fazer com o que chega. As ferramentas MCP são feitas exatamente para isso — chamadas únicas e bem delimitadas que o próprio raciocínio do agente invoca conforme necessário, em vez de um script executado do início ao fim. A mesma conta e cota da OTPBox sustentam ambos; o MCP é apenas uma segunda interface sobre as mesmas caixas, mensagens e identidades da API REST.

1. Conecte o servidor

A OTPBox executa um servidor MCP remoto (HTTP com streaming) em https://otpbox.io/mcp, autenticado com a mesma chave bearer da API REST. Adicione-o a um cliente compatível com MCP — Claude, Cursor, ou seu próprio framework de agentes:

{
  "mcpServers": {
    "otpbox": {
      "url": "https://otpbox.io/mcp",
      "headers": { "Authorization": "Bearer <your-key>" }
    }
  }
}

Obtenha uma chave sem precisar de conta — POST /api/v1/keys/free (veja Obter uma chave) — ou gere uma chave de organização a partir do painel caso vários agentes ou projetos precisem compartilhar uma cota comum.

2. As ferramentas com que um agente conta

O servidor expõe 13 ferramentas no total; estas são as que uma tarefa de cadastro e verificação realmente usa. Lista completa e detalhes dos argumentos estão em na documentação.

Ferramenta	Use para…
`create_test_inbox`	Obter um endereço descartável novo antes de iniciar o cadastro.
`wait_for_email`	Bloquear até que algo chegue, em vez do agente ficar consultando por conta própria.
`get_otp`	Ler apenas o código extraído da mensagem mais recente.
`get_verification_link`	Ler o link de confirmação/redefinição/login mágico extraído, em vez de um código.
`get_latest_email`	Ler a mensagem completa quando o agente precisa de mais do que o código (assunto, corpo, remetente).
`create_test_identity`	Obter nome, país e perfil junto com a caixa, para um formulário de cadastro que quer uma pessoa convincente, não só um endereço de e-mail.
`delete_inbox`	Limpar assim que a tarefa termina.

3. Uma tarefa típica de agente

Com uma instrução como "cadastre-se em acme.example.com e confirme que a conta existe", um agente com as ferramentas da OTPBox disponíveis e uma ferramenta de navegador (ou sua própria capacidade HTTP) costuma seguir mais ou menos esta sequência — este é o padrão de chamadas de ferramentas, não código literal, já que o próprio modelo do agente decide a ordem e eventuais novas tentativas:

1. create_test_inbox()
   -> { id: "a1b2c3", address: "bold.quartz844@otpbox.io", expiresAt: ... }

2. (drive the browser) fill the signup form's email field with that address,
   submit

3. wait_for_email({ inboxId: "a1b2c3", timeoutSeconds: 20 })
   -> { timedOut: false, message: { code: "482913", ... } }

   // or, if the agent only wants the code and not the whole message:
   get_otp({ inboxId: "a1b2c3" })
   -> { code: "482913", messageId: "msg_..." }

4. (drive the browser) type "482913" into the OTP field, submit

5. delete_inbox({ inboxId: "a1b2c3" })

Prefira wait_for_email a fazer o agente chamar get_otp em um loop manual de novas tentativas — é uma única chamada que bloqueia do lado do servidor (até 25 segundos) em vez de várias chamadas, cada uma consumindo uma unidade de cota.

4. Testes em massa e orientados a personas

Um agente encarregado de algo como "crie 10 contas de teste com países diferentes e confirme que cada uma verifica" pode usar create_bulk_test_identities (um template mais uma quantidade de 1 a 50) em vez de chamar create_test_inbox em um loop — cada identidade já vem com nome, e-mail e perfil apropriado ao país, apoiados por sua própria caixa real. Templates: us_customer, indian_customer, european_customer, business_customer, student, employee.

Limites que um agente vai encontrar

Cada chamada de ferramenta conta como uma requisição na cota mensal da chave (Grátis: 200/mês; Pro: 5.000/mês compartilhadas por organização — veja preços), assim como uma chamada REST. Um agente que faz polling desnecessário consome a cota da mesma forma que uma suíte de testes tagarela.
As chamadas MCP também têm um limite separado de 60/minuto por chave, então um loop descontrolado de agente não consegue sobrecarregar o servidor mesmo dentro da cota.
As falhas aparecem como erros de ferramenta MCP, não como códigos de status HTTP — um framework de agente bem construído deve tratar um resultado de erro de ferramenta como um sinal para parar e reconsiderar, não simplesmente tentar de novo às cegas.
Uma chave criada com escopos restritos (painel → chave → escopos) rejeitará ferramentas fora desses escopos com um erro de escopo insuficiente — útil para dar a um agente uma chave que só possa criar caixas e ler OTPs, nada mais.

Próximos passos

Pronto para integrar isso ao seu próprio agente? Crie uma conta gratuita

Documentação da API Preços Todos os guias Registro de alterações

← Voltar à OTPBox