Conectar un agente con MCP
Guías del producto, API pública, webhooks y MCP.
MCP permite consultar números, pagos, llamadas y SMS, configurar desvíos y extensiones y comprar un número. Se aplican los permisos, la titularidad y los límites de la API.
Conexión y autenticación
Servidor: https://mcp.novodid.com/mcp. Transporte: Streamable HTTP. Envíe Authorization: Bearer con su token. El cliente debe admitir encabezados personalizados. Este servidor no ofrece OAuth; use un cliente compatible con Bearer.
Cree el token en Desenvolvedores → Tokens. Los tokens anteriores no reciben permisos nuevos automáticamente. Nunca incluya tokens en prompts compartidos, archivos públicos ni URLs.
Ejemplo en 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 un número
Use search_available_dids y quote_did_purchase. Presente precio, ciclo recurrente y condiciones. Solo después del consentimiento cree el pago con create_did_checkout e idempotencyKey. Cada pedido admite un número. Ante un resultado incierto, repita exactamente la misma clave y los mismos datos. Consulte get_did_order hasta confirmar pago y activación.
Crear un QR o aceptar una autorización recurrente no demuestra pago. Pix incluye PNG, código para copiar y QR de terminal; la visualización depende del cliente. Con tarjeta, use el enlace de checkout devuelto. No pague instrucciones vencidas ni repita un pago confirmado por el banco; contacte a soporte con el ID del pedido.
Consentimiento y datos sensibles
Confirme el número y destino antes de cambiar un desvío. El desvío telefónico requiere saldo y cobro por minuto. Eliminarlo no cancela la suscripción. Las credenciales SIP requieren los permisos correspondientes y titularidad actual.
Para send_sms, confirme remitente, destinatario y texto. Solo se permiten respuestas a SMS entrantes de ese destinatario durante el acceso SMS de la titularidad actual. El historial saliente o de otro titular no autoriza una conversación. No repita automáticamente un envío incierto.
Herramientas y permisos
get_account
Permiso: Sin permiso adicional; account:read habilita nombre y correo
Consulta la cuenta y los permisos efectivos. account:read habilita además nombre y correo.
list_dids
Permiso: dids:read
Lista números actuales autorizados. billing:read habilita pagos y ciclo; forwarding:read, desvíos.
get_did
Permiso: dids:read
Consulta didId, estado y funciones. Agregue billing:read para pagos y forwarding:read para destinos.
list_forwardings
Permiso: forwarding:read
Lista desvíos de números propios autorizados por el token.
get_did_forwarding
Permiso: forwarding:read
Consulta el desvío de un didId.
set_did_phone_forwarding
Permiso: forwarding:phone
Configura desvío telefónico con didId y destinationNumber (55 + DDD + número). Requiere saldo y cobro por minuto, sin minutos gratuitos.
set_did_ip_forwarding
Permiso: forwarding:write
Configura desvío a IP pública con didId, clientIp público y clientPort entre 1 y 65535.
set_did_sip_forwarding
Permiso: forwarding:write
Selecciona una extensión existente autorizada con didId y sipAccountId. No devuelve contraseña.
create_did_sip_forwarding
Permiso: forwarding:write + sip:create + sip:credentials:read
Crea o reutiliza la extensión exclusiva, configura el desvío y devuelve usuario, contraseña y servidor. Requiere didId.
delete_did_forwarding
Permiso: forwarding:delete
Elimina el desvío por didId. No cancela la suscripción ni libera el número.
get_did_sip_credentials
Permiso: sip:credentials:read
Consulta usuario, contraseña y servidor de la extensión exclusiva por didId, con desvío SIP habilitado.
list_calls
Permiso: calls:read
Consulta llamadas de la titularidad actual. Filtros: didId o did, limit 1–200, page 1–10000 y startDate/endDate ISO.
list_sms_messages
Permiso: sms:read
Consulta SMS de la titularidad y acceso actuales. Filtros: didId o did, direction (inbound/outbound), limit 1–200.
send_sms
Permiso: sms:send
Responde a un SMS entrante de ese destinatario durante el acceso SMS actual. from, to, text (hasta 1600 caracteres), didId opcional. Un envío anterior, otro contacto o una titularidad anterior no autorizan. No repita automáticamente resultados inciertos.
search_available_dids
Permiso: catalog:read
Busca por ddd y kind (fixed/mobile), page desde 1 y limit 1–100. La búsqueda no reserva.
quote_did_purchase
Permiso: catalog:read
Cotiza un didId con cycle (monthly/semiannually/yearly) y paymentMethod (pix/card). No crea un pago.
create_did_checkout
Permiso: orders:create
Crea el pago después del consentimiento con los datos cotizados, confirmaciones requeridas e idempotencyKey. Un número por pedido.
get_did_order
Permiso: orders:read
Consulta un pedido propio por orderId, incluidas instrucciones de pago mientras estén vigentes.
list_did_orders
Permiso: orders:read
Lista pedidos de la cuenta con page y limit, con los límites del catálogo.
Solución de problemas
- 401: compruebe encabezado, vencimiento y revocación.
- 403: revise permisos, restricciones, SMS y análisis de seguridad.
- 404: compruebe titularidad actual e identificadores de su cuenta.
- 409: consulte el pedido o recurso antes de repetir cambios.
- 429: respete Retry-After y los límites compartidos.
La guía de API detalla límites numéricos, payloads y códigos de error.