Servidor MCP

A Zelnum mantém um servidor MCP público em https://mcp.zelnum.com/mcp. Qualquer cliente compatível com MCP — Claude, Cursor, um agente na sua IDE — pode listar produtos, consultar o preço de uma verificação, executá-la e ler o resultado sem escrever código de integração. Uma única URL atende todos os clientes: você se conecta com a sua própria chave de API, e cada cobrança é lançada no seu próprio saldo.

Ponto de acesso

Configuração	Valor
URL	https://mcp.zelnum.com/mcp
Transporte	Streamable HTTP
Credenciais	Authorization: Bearer YOUR_KEY_HERE

A credencial é a mesma chave de API que suas chamadas REST usam. Crie, regenere e revogue a chave em API Center, no console.

Conectar um cliente

Três passos, sem instalar nada.

1. Crie uma chave. Gere uma chave de API em API Center no console — a mesma que suas chamadas REST usam. Veja Authentication.

2. Adicione o servidor. O Cursor e outros clientes que leem o mapa padrão mcpServers podem usar esta entrada como está:

{
  "mcpServers": {
    "zelnum": {
      "url": "https://mcp.zelnum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY_HERE"
      }
    }
  }
}

O Claude recebe esses mesmos dois valores na caixa de diálogo de conector personalizado — a URL e um cabeçalho Authorization com a sua chave.

3. Verifique a conexão. Peça ao agente para dizer quais produtos em tempo real ele consegue verificar. Uma conexão saudável responde chamando list_products, que é somente leitura e gratuito, então a verificação não custa nada. Um 401 significa que a chave está ausente, revogada ou não é aceita pela plataforma.

Ferramentas

Ferramenta	O que faz	Cobrada
list_products	Catálogo de produtos ativos com ID, slug e série. Somente leitura.	Não
get_balance	Saldo da conta com a qual a conexão está autenticada. Somente leitura.	Não
quote_realtime_check	Preço oficial de uma verificação. A única fonte de preço em que um agente deve confiar.	Grátis
check_realtime	Executa uma verificação em tempo real contra até dez produtos.	Sim
create_bulk_task	Envia uma lista embutida para uma tarefa em lote assíncrona.	Sim
get_task_status	Progresso e contadores de cobrança de uma tarefa em lote.	Não
get_task_result	Metadados do resultado e link de download autenticado de uma tarefa concluída.	Não

O que você pode dizer

Acima estão as ferramentas; abaixo, as frases que você digita. Todas são atendidas por uma ferramenta que já existe — nenhuma redação é tratada como caso especial.

Diga isto	O que acontece
Quais produtos posso verificar em tempo real?	Chama list_products e responde com os IDs a usar. Gratuito.
Qual é o meu saldo?	Chama get_balance para a chave com que você se conectou. Gratuito.
Quanto custaria verificar +14155550123 no WhatsApp?	Chama quote_realtime_check e mostra o preço. Gratuito, e nada é cobrado.
Pode seguir por esse preço.	Chama check_realtime para os produtos do orçamento e cobra o valor orçado.
Verifique estes 200 números no WhatsApp e me avise quando terminar.	Chama create_bulk_task e depois consulta get_task_status para informar o progresso.
Aquela tarefa já terminou? Me mande o link de download.	Chama get_task_result e devolve o link autenticado.

Dois hábitos que vale manter:

• Pergunte o preço primeiro. Toda ferramenta cobrada responde com um orçamento antes de cobrar, então perguntar quanto custa é sempre gratuito. Só a confirmação movimenta dinheiro.
• Informe o campo country quando o número não for E.164. +14155550123 já traz o próprio país; 0812345678 não, e a passarela se recusa a adivinhar.

Confirmar uma cobrança

Uma ferramenta cobrada nunca debita na primeira chamada. Chamada sem confirmed, ela devolve um payload de confirmação — os produtos, a quantidade e o custo estimado — junto com um quote_token que assina a entrada exata. Confirme repetindo a mesma chamada com:

1. confirmed definido como true
2. o quote_token daquele payload
3. quoted_total, exatamente o valor que foi mostrado a você
4. o mesmo identificador, os mesmos produtos e o mesmo campo country

Um agente nunca fornece a própria chave de idempotência: o gateway a deriva do orçamento assinado, então um mesmo orçamento aprovado mantém a mesma chave entre novas tentativas, reconexões e reinícios do gateway. Uma cobrança diferente exige um novo orçamento. Se um timeout deixar o resultado desconhecido, repita a chamada idêntica em vez de alterar parâmetros.

Nunca confirme em silêncio

O agente precisa mostrar o custo estimado e obter aprovação explícita antes de ativar o sinalizador de confirmação. O orçamento expira em cinco minutos, e um orçamento cujo preço de referência se moveu é recusado, em vez de cobrado pelo preço novo.

Identificadores

As regras de identificador espelham o contrato REST, então o que o agente valida é o que a API aceita:

• Sem o campo country — o identificador deve ser um número E.164 com prefixo +.
• Com o campo country — um código ISO de duas letras maiúsculas; o identificador passa a ser o número nacional ou um número E.164.
• O país nunca é deduzido de um número nacional ambíguo como 0812345678, que corresponde a vários países. Deixe o country de fora apenas quando o número já for um E.164 completo.
• Tarefas em lote sobre produtos de telefone exigem o campo country explícito.

Trava de dinheiro

Quatro travas ficam entre o agente e o seu saldo:

1. Orçamentos assinados. A plataforma lê os preços atuais e devolve um orçamento criptografado que vincula a conta, a entrada exata, os produtos e o retrato de preços. Entrada alterada, orçamento expirado ou preço que se moveu é recusado antes de qualquer cobrança.
2. Idempotência determinística. A chave de idempotência vem do orçamento assinado, e não do modelo, então nenhuma redação de uma requisição transforma uma aprovação em duas cobranças.
3. Limites por chave. Um teto diário de gasto e um piso de saldo valem por chave de API, e cada reserva é serializada antes da chamada à plataforma, de modo que agentes concorrentes não conseguem furá-los.
4. Falha fechada. Se o saldo não puder ser lido, ou voltar malformado, as chamadas cobradas são recusadas em vez de rodar sem proteção.

Erros e limites

• Uma credencial ausente ou malformada é recusada com HTTP 401 antes de a requisição chegar à plataforma.
• Uma chave que a plataforma não aceita volta como erro de ferramenta, com o status e o corpo da plataforma, então o agente reporta em vez de tentar de novo às cegas.
• Limites de requisição, códigos de erro e download de resultados funcionam exatamente como no REST — o gateway não acrescenta um segundo contrato para aprender.

Próximos passos

• Authentication — crie a chave com a qual você vai se conectar.
• Realtime check — o endpoint por trás de check_realtime.
• Bulk workflow — o caminho assíncrono por trás de create_bulk_task.
• Error codes — os códigos que a plataforma devolve.