Conectar um agente pelo MCP
Configure o transporte, autenticação e todas as ferramentas públicas da conta.
O MCP permite consultar números, vencimentos, chamadas e SMS, configurar encaminhamentos e ramais e comprar um número. São as mesmas permissões, restrições de posse e cotas da API pública.
Conexão e autenticação
Servidor: https://mcp.novodid.com/mcp. Transporte: Streamable HTTP. Use Authorization: Bearer com seu token da API. O cliente precisa aceitar cabeçalhos personalizados. Não há fluxo OAuth nesse servidor: se o aplicativo não permite Bearer, use um cliente compatível.
Crie o token em Desenvolvedores → Tokens. Tokens antigos não recebem novas permissões automaticamente. Nunca coloque seu token em prompts compartilhados, arquivos públicos ou URLs.
Exemplo em TypeScript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const client = new Client({ name: 'meu-agente', version: '1.0.0' });
try {
await client.connect(new StreamableHTTPClientTransport(
new URL('https://mcp.novodid.com/mcp'),
{ requestInit: { headers: {
Authorization: `Bearer ${process.env.NOVODID_API_TOKEN}`
} } }
));
const result = await client.callTool({
name: 'search_available_dids',
arguments: { ddd: '11', kind: 'fixed', page: 1, limit: 20 }
});
console.log(result.structuredContent);
} finally {
await client.close();
}Comprar um número
Pesquise com search_available_dids, obtenha uma cotação com quote_did_purchase e apresente valor, ciclo recorrente e condições ao cliente. Somente após a confirmação crie o checkout com create_did_checkout. Use idempotencyKey e repita a mesma chave e os mesmos dados se o resultado for incerto. Cada pedido aceita um número. Acompanhe get_did_order até a confirmação do pagamento e ativação; um QR Code criado ou uma autorização recorrente aprovada não comprovam pagamento.
No Pix, o resultado inclui imagem PNG, copia e cola e QR em texto para terminal; a renderização depende do cliente. No cartão, o cliente conclui o pagamento pelo link retornado. Não pague instruções expiradas nem repita pagamento que o banco já confirmou. Consulte o pedido e procure suporte com seu ID.
Consentimento e dados sensíveis
Confirme o número e destino antes de alterar encaminhamentos. Siga-me exige saldo e cobrança por minuto; remover encaminhamento não cancela assinatura. Credenciais SIP só são entregues quando o token tem os escopos exigidos e o número está na posse atual.
Para send_sms, confirme remetente, destinatário e mensagem. Só é possível responder a uma entrada desse destinatário durante o acesso SMS da posse atual. Histórico de saída e acesso de titular anterior não autorizam nova conversa. Não repita automaticamente um envio após resposta incerta.
Ferramentas e permissões
get_account
Permissão: Sem escopo adicional; account:read libera nome e e-mail
Consulta a conta e as permissões do token.
list_dids
Permissão: dids:read
Lista os números atuais da conta permitidos pelo token. billing:read libera vencimento, ciclo e pagamento; forwarding:read libera o encaminhamento.
get_did
Permissão: dids:read
Consulta um número por didId, status e recursos. Adicione billing:read para vencimento e pagamento e forwarding:read para encaminhamento.
list_forwardings
Permissão: forwarding:read
Lista os encaminhamentos dos números da conta permitidos pelo token.
get_did_forwarding
Permissão: forwarding:read
Consulta o encaminhamento de um número por didId.
set_did_phone_forwarding
Permissão: forwarding:phone
Cria ou altera o siga-me com didId e destinationNumber (55 + DDD + número). Exige saldo e tem cobrança por minuto, sem minutos gratuitos.
set_did_ip_forwarding
Permissão: forwarding:write
Cria ou altera encaminhamento por IP com didId, clientIp público e clientPort entre 1 e 65535.
set_did_sip_forwarding
Permissão: forwarding:write
Configura um ramal existente autorizado com didId e sipAccountId. Não retorna a senha.
create_did_sip_forwarding
Permissão: forwarding:write + sip:create + sip:credentials:read
Cria ou reutiliza o ramal próprio do número, configura o encaminhamento e retorna login, senha e servidor. Informe didId.
delete_did_forwarding
Permissão: forwarding:delete
Remove o encaminhamento por didId. Não cancela nem devolve o número.
get_did_sip_credentials
Permissão: sip:credentials:read
Consulta login, senha e servidor do ramal próprio por didId, com encaminhamento SIP ativo.
list_calls
Permissão: calls:read
Consulta chamadas da posse atual. Filtros: didId ou did, limit de 1 a 200, page de 1 a 10000, startDate e endDate em formato ISO.
list_sms_messages
Permissão: sms:read
Consulta SMS da posse e do período de acesso atuais. Filtros: didId ou did, direction (inbound/outbound) e limit de 1 a 200.
send_sms
Permissão: sms:send
Responde a um SMS de entrada desse destino para o DID durante o acesso SMS da posse atual. from, to e text (até 1600 caracteres); didId é opcional. Saída anterior, outro contato, posse anterior ou falha de consulta não autorizam. Não repita automaticamente após resultado incerto.
search_available_dids
Permissão: catalog:read
Pesquisa números disponíveis por DDD e tipo. Use kind: fixed para fixos ou mobile para móveis, page a partir de 1 e limit entre 1 e 100. A pesquisa não reserva o número.
quote_did_purchase
Permissão: catalog:read
Consulta preço, recorrência e condições para um número. Informe didId, cycle (monthly, semiannually ou yearly) e paymentMethod (pix ou card). A cotação não cria pagamento.
create_did_checkout
Permissão: orders:create
Gera o pagamento após a confirmação do cliente. Informe os dados da cotação, as confirmações exigidas e idempotencyKey. Cada pedido aceita somente um número.
get_did_order
Permissão: orders:read
Consulta um pedido da sua conta pelo orderId retornado na criação, incluindo as instruções de pagamento enquanto válidas.
list_did_orders
Permissão: orders:read
Lista os pedidos da sua conta. Aceita page e limit, com os mesmos limites de paginação da pesquisa.
Solução de problemas
- 401: confira o cabeçalho, expiração e revogação do token.
- 403: confira escopos, restrições da conta, SMS e bloqueios de segurança.
- 404: confira a posse atual do número e o identificador retornado pela própria conta.
- 409: consulte o pedido ou recurso antes de repetir uma alteração.
- 429: respeite Retry-After e os limites compartilhados da conta.
Consulte o guia completo para limites numéricos, payloads e códigos de erro.
Enviar ou responder SMS
Obrigatórios: from=seu DID autorizado com SMS, to=destinatário, text=mensagem (após trim, 1–1600 caracteres). Telefones: 10–15 dígitos, + inicial opcional. didId opcional deve corresponder a from. O envio só responde a um SMS de entrada desse destino para o DID, recebido desde o início do acesso SMS da posse atual. Mensagem enviada antes, outro contato, posse anterior ou falha ao consultar o histórico não autorizam o envio. Não há liberação de conta para iniciar conversa. 201 confirma submissão, não entrega ao aparelho. message contém id, smscMessageId (podem ser null), didId, from, to, textLength e newConversation, que é false. Sem chave de idempotência: após timeout, confira histórico antes de repetir.
Guias do produto
Orientações públicas para usar a plataforma.