Servidor MCP
Conectar un cliente de IA a los datos de tu operación
This page has not been translated yet, so you are seeing it in Spanish.
Qué es el servidor MCP de Audara
MCP es el protocolo que hablan los clientes de inteligencia artificial para usar herramientas externas. Audara expone uno, así que puedes conectar ChatGPT, Claude o cualquier cliente compatible y preguntarle por tu operación en lenguaje natural: qué está pasando ahora mismo en soporte, qué clientes llamaron más de tres veces esta semana, cómo va la campaña de cobranzas.
Es tu información expuesta en el estándar que ya hablan esos clientes. No tienes que programar nada: conectas el servidor una vez y el asistente descubre solo qué herramientas tiene disponibles.
Ojo con no confundirlo con su opuesto. Este artículo trata de otros sistemas consultando a Audara. Si lo que quieres es que un bot de Audara use las herramientas de un servidor MCP ajeno, eso es Integraciones MCP.
- URL del conector
- https://api.audara.io/mcp
- Transporte
- Streamable HTTP. Solo se atiende POST.
- Autenticación
- OAuth 2.1 con PKCE, o un token que creas a mano en la plataforma.
- Herramientas
- Dieciocho, todas de lectura. El servidor no modifica tu operación.
El servidor MCP es un módulo licenciado. Si la pestaña MCP no aparece en el perfil de usuario, tu instalación no lo tiene habilitado y hay que pedirlo a soporte.
El token actúa como una persona
Esta es la idea que conviene entender antes que cualquier otra, porque de ella se desprende todo lo demás.
Un token de MCP no es una credencial de sistema con permisos propios: queda vinculado a un usuario real de Audara y actúa en su nombre. Todo lo que ese usuario puede ver, lo ve el asistente; todo lo que no, tampoco. Los permisos de reportes, la visibilidad de CRM y el alcance por departamento son los mismos que ya tenía la persona, sin una segunda lista que mantener.
Tiene tres consecuencias prácticas.
- Si desactivas al usuario, su acceso por MCP muere con la cuenta. Dar de baja a alguien basta para cortarle también el asistente.
- En la bitácora, el responsable de cada consulta es una persona con nombre, no un sistema anónimo.
- Dos tokens de dos personas distintas ven cosas distintas, aunque apunten a la misma instalación y pidan lo mismo.
Conectar tu cliente de IA
Hay dos caminos, y el que te sirve depende de qué permisos necesites.
Con OAuth, que es el de un clic
Agrega https://api.audara.io/mcp como servidor MCP en tu cliente. Si el cliente soporta OAuth, se registra solo y te abre el navegador. A partir de ahí:
- Eliges a cuál instalación de Audara quieres conectarte.
- Inicias sesión en esa instalación, con tu usuario de siempre y el método que ya usas, incluido el doble factor o Google.
- Apruebas el acceso en una pantalla que te dice qué asistente lo está pidiendo y con qué permisos.
- El cliente recibe su token y queda conectado.
Tu contraseña nunca pasa por el conector: el inicio de sesión ocurre en tu propia instalación. Y el token nunca se te muestra, porque va directo del conector al almacenamiento del cliente.
Con un token creado a mano
Un administrador crea el enlace desde la pestaña MCP del perfil del usuario, elige los permisos y copia el token, que se muestra una sola vez. Luego lo pegas en tu cliente como credencial Bearer.
Los dos caminos no ofrecen lo mismo. Por OAuth nunca vas a obtener el permiso de datos personales (pii:read), por diseño: el cliente pide los permisos que el servidor anuncia y ese no se anuncia, para que no se conceda sin que alguien lo decida. Si necesitas ver los números de teléfono completos, el camino es el token creado a mano, donde una persona marca esa casilla a propósito.
Los permisos
Un enlace lleva una lista de permisos que solo puede restringir lo que el usuario ya podía ver, nunca ampliarlo. Si concedes un permiso sobre algo que esa persona no tiene, el asistente sigue sin verlo.
Hay dos clases de permiso, y la diferencia importa porque fallan distinto.
Los dos primeros deciden qué herramientas existen para la conexión.
- interactions:read
- Las herramientas de consulta histórica: interacciones, llamadas, marcadores y campañas. Es la mayoría del catálogo.
- realtime:read
- Las dos herramientas de tiempo real, la de colas y la de agentes.
Los otros dos no quitan herramientas: cambian qué tanto trae cada resultado. Sin ellos las herramientas siguen ahí y responden, pero con parte del contenido reservado.
- pii:read
- Devuelve los datos de contacto completos. Sin este permiso los números y correos llegan enmascarados: alcanzan para reconocer que dos interacciones son de la misma persona, pero no para identificarla ni para contactarla. No viene activado por defecto.
- transcripts:read
- Incluye el texto de lo que se dijo en la conversación. Sin él sigues viendo que la interacción existió y sus métricas, pero no su contenido.
Si una herramienta te responde con teléfonos recortados, no es una falla: es que la conexión no tiene pii:read. Y el enmascarado conserva solo cuatro dígitos, así que dos números distintos pueden verse iguales. No lo uses como identificador.
Las herramientas
Son dieciocho y todas leen. Ninguna crea, modifica ni borra nada de tu operación.
Dos las responde el conector por sí mismo, sin consultar a ninguna instalación.
- list_instances
- Qué instalaciones alcanza esta conexión, con qué usuario actúa en cada una y en qué estado están. Conviene llamarla primero.
- connect_instance
- Entrega un enlace para sumar otra instalación a la conexión. No conecta nada por sí sola.
Las otras dieciséis las responde cada instalación.
| Herramienta | Para qué sirve | Permiso |
|---|---|---|
get_instance_info | Qué instalación es, con qué usuario actúa y qué permisos tiene. | ninguno |
list_queues | Las campañas disponibles, de voz y de chat. | interactions:read |
search_interactions | Buscar conversaciones de chat por canal, sentimiento, estado o fecha. | interactions:read |
get_interaction | El detalle de una conversación. | interactions:read |
aggregate_interactions | Totales de chat agrupados por la dimensión que pidas. | interactions:read |
search_calls | Buscar llamadas entrantes. | interactions:read |
get_call | El detalle de una llamada. | interactions:read |
aggregate_calls | Totales de llamadas entrantes agrupados. | interactions:read |
search_outbound_calls | Buscar llamadas salientes de marcador. | interactions:read |
aggregate_outbound_calls | Totales de llamadas salientes agrupados. | interactions:read |
list_dialers | Los marcadores configurados. | interactions:read |
get_dialer_progress | Cómo va un marcador con su base de contactos. | interactions:read |
list_blaster_campaigns | Las campañas de envío masivo. | interactions:read |
get_blaster_campaign | El detalle y los resultados de una campaña masiva. | interactions:read |
get_realtime_queues | Qué está pasando ahora mismo en las colas. | realtime:read |
get_realtime_agents | En qué estado están los agentes ahora mismo. | realtime:read |
El catálogo lo publica cada instalación, así que una herramienta nueva aparece sola cuando se actualiza la plataforma. No hay nada que actualizar de tu lado.
La tabla de arriba dice para qué sirve cada una. Campo por campo, lo que cada una devuelve está en Qué trae cada herramienta.
Las herramientas de búsqueda aceptan ventanas de hasta 31 días y devuelven 50 resultados por defecto, 200 como máximo. Las de totales llegan hasta 92 días, porque agregan en vez de listar. Si pides más, la herramienta te lo dice y te pide acotar en lugar de devolver un resultado a medias.
A qué informes de Audara equivale
Es la primera pregunta que hace todo el mundo: qué informes va a poder ver el asistente. La respuesta corta es que no ve informes, ve los datos con los que se arman, y por eso puede responder preguntas que ningún informe trae hechas. La respuesta larga es esta tabla, ordenada como el menú de reportes del producto.
| Menú de reportes | Qué alcanza el asistente | Con qué herramientas |
|---|---|---|
| Canales Chat | Completo. Cada conversación con sus tiempos, su campaña, su agente, su canal, su calificación, sus etiquetas y su sentimiento, y los totales ya calculados por campaña, agente, canal, día u hora. Con transcripts:read, además el texto de lo que se dijo. |
search_interactions, get_interaction, aggregate_interactions |
| Voz Entrante | Completo para las llamadas que entraron a una campaña. Espera, conversación, hold, ACW, quién colgó, por cuáles campañas pasó el llamante, las tipificaciones del agente y las respuestas de la encuesta del IVR. | search_calls, get_call, aggregate_calls |
| Marcadores | Completo para las llamadas que un agente atendió y tipificó, más el avance de cada campaña contra su base de contactos, run por run. | search_outbound_calls, aggregate_outbound_calls, list_dialers, get_dialer_progress |
| Blaster, en sus cuatro canales: voz, WhatsApp, SMS y correo | Completo. Estado de la campaña, audiencia, y el resultado escalón por escalón: enviados, entregados, leídos y clics, con el detalle de por qué falló lo que falló. | list_blaster_campaigns, get_blaster_campaign |
| Productividad | Parcial. Las tres herramientas de totales se agrupan por agente, así que cuánto atendió cada quien, en cuánto tiempo y con qué resultado sale completo, en voz, en chat y en saliente. Lo que todavía no tiene herramienta es el historial de pausas, el de login y logout, las alarmas y los estados de agente. | aggregate_calls, aggregate_interactions, aggregate_outbound_calls |
| Control Calidad | Parcial, pero en la parte que interesa. Llega el análisis completo de Speech Analytics: sentimiento, puntaje de calidad, categorías detectadas, porcentaje de silencio y el resumen escrito por la IA, además de las etiquetas y el comentario que alguien le puso a la grabación. El audio no sale nunca, ni su ruta. | get_call, search_calls, search_interactions |
| Tiempo real, lo que muestra el Panel de Supervisor | Completo. Cuántos esperan, cuántos en hold, qué agentes están conectados y en qué estado, cuánto llevan así, qué pausa tienen y si se pasaron de su tiempo, y cuántos chats más aguanta el equipo en este momento. | get_realtime_queues, get_realtime_agents |
| Agentes de IA | Parcial. Una conversación que atendió un bot aparece en el historial de chat y se distingue de una que atendió una persona, pero no hay un informe de bots como tal. | search_interactions, get_interaction |
| Resultados IVR | No hay herramienta de IVR. Las respuestas de la encuesta sí llegan, pero dentro del detalle de la llamada, no como informe aparte. | get_call |
| CDR | No. Una llamada que timbró una extensión sin pasar por una campaña no está en ninguna herramienta. | ninguna |
| Tickets | No. | ninguna |
Dicho al revés, que es como suele preguntarse: lo único que queda por fuera es el CDR de la central, los informes de IVR y los de tickets. De lo demás, el asistente alcanza los datos completos, con dos matices que conviene decir de frente. El audio de una grabación no se entrega. Y del lado de productividad hay mediciones de agente, las de pausas y jornada, que todavía no tienen herramienta propia.
Un informe responde la pregunta para la que fue diseñado. El asistente trabaja con los datos, así que responde también las que nadie previó: cruzar dos dimensiones a la vez, buscar a los contactos que llamaron más de tres veces, o comparar dos campañas en la misma frase. Eso es lo que no aparece en esta tabla y es la mitad del valor.
Qué trae cada herramienta
Esta sección es el detalle campo por campo. No hace falta leerla de corrido: sirve para resolver un "¿esto trae tal dato?" sin tener que probarlo.
Los nombres van en inglés porque así viajan por el protocolo, que es como los ve el asistente. Y hay una regla que vale para todas: un dato que no se conoce llega vacío, nunca en cero. Una conversación sin calificar no puntúa cero, un promedio sobre nadie no es cero, y una campaña que no mide conversiones no reporta cero conversiones. La diferencia entre "no lo sabemos" y "es cero" se respeta en todas partes, justamente para que el asistente no la borre al resumir.
list_instances
La responde el conector. Pregunta a cada instalación que alcanza la conexión y devuelve un resultado por cada una, así que lo que trae por dentro es lo mismo que get_instance_info. Si una instalación no responde, aparece igual, marcada como inalcanzable: la lista de a cuáles llega la conexión es correcta de todos modos.
connect_instance
La responde el conector, y devuelve un enlace, nada más.
| Campo | Qué trae |
|---|---|
authorization_url | El enlace que alguien tiene que abrir para sumar otra instalación. |
expires_in_minutes | 15. |
already_connected | Las instalaciones que la conexión ya alcanza. |
next_step | La instrucción para el asistente, dicha en voz alta para que no reporte la instalación como conectada cuando lo único que hizo fue pedir un enlace. |
get_instance_info
La radiografía de la conexión. No pide ningún permiso, así que sirve para que el asistente averigüe qué puede hacer antes de intentarlo.
| Campo | Qué trae |
|---|---|
instance | El subdominio de la instalación, que es lo que el conector usa para enrutar. |
clientName | El nombre del cliente tal como está en la licencia. |
actingAs | El nombre y el correo del usuario en cuyo nombre actúa el token. |
scopes | Los permisos concedidos a esta conexión en esta instalación. |
connection | Cómo se llama la conexión aquí. En un enlace por OAuth es el nombre del propio cliente de IA. |
list_queues
El catálogo de campañas, para que el asistente deje de adivinar nombres antes de filtrar por ellos.
| Campo | Qué trae |
|---|---|
queues[].kind | chat o voice. El mismo nombre puede existir en las dos como campañas sin ninguna relación, así que este campo es lo único que las distingue. |
queues[].name | El nombre exacto, que es lo que aceptan los filtros de las búsquedas. |
queues[].id | Solo las de voz. Las de chat no tienen número, su nombre es la llave. |
queues[].active | Si sigue en uso. Una campaña retirada se lista igual, porque su historia sigue siendo suya. |
total, chatTotal, voiceTotal | Cuántas hay de cada clase. |
scopedToUser, scopeNote | Si la lista está recortada por los grupos asignados al usuario. Se dice en voz alta, porque una lista corta y un contact center pequeño se ven igual. |
search_interactions
Las conversaciones de chat, una fila por conversación. Un chat transferido se guarda como varios tramos y aquí llega colapsado en uno solo, con el conteo de tramos aparte, para que "cuántas conversaciones hubo" no cuente doble cada transferencia.
Filtros: since y until son obligatorios, ventana máxima de 31 días. Además channel (whatsapp, messenger, instagram, webchat, voicebot), queueName, agentName, sentiment (POSITIVE, NEUTRAL, NEGATIVE), contactCrmId, contactPhone, status (open o ended) y limit.
| Campo | Qué trae |
|---|---|
interactionId | El identificador de la conversación. Es el que se le pasa a get_interaction, y el mismo que muestra el reporte de conversaciones. |
startTime, endTime | Cuándo empezó y cuándo terminó, abarcando todos sus tramos. |
inProgress | Si todavía no ha terminado. Se dice explícito en vez de dejarlo deducir de una fecha vacía. |
channel | Por dónde entró. |
direction | Cómo se originó, tomado siempre del primer tramo y no del último. |
queue, agent | La campaña y el agente que la atendieron. |
contactName | El nombre del contacto. |
contactPhone, contactEmail | Los datos de contacto, completos con pii:read y enmascarados sin él. |
contactCrmId | El registro de CRM al que quedó vinculada, si lo hay. |
durationSeconds | Lo que duró, sumando sus tramos. |
waitSeconds | Lo que esperó en cola. |
rating | La calificación del cliente, de 1 a 5. Vacío si nadie calificó, nunca cero. |
endAction | Cómo terminó. |
tags | Las etiquetas, resueltas a su nombre. Una etiqueta borrada conserva su identificador en vez de desaparecer. |
sentiment | POSITIVE, NEUTRAL o NEGATIVE, del análisis de Speech Analytics. |
analyzed | Si la conversación llegó a analizarse. Sin esto, "no analizada" y "analizada y salió neutra" se leen igual. |
legs | Cuántos tramos tuvo, o sea cuántas veces se transfirió más uno. |
Alrededor de la lista viajan returned, partial con su partialReason, la ventana consultada, piiMasked y una nota de cobertura que dice en una frase qué entra y qué no en esta búsqueda.
get_interaction
Una conversación entera. Recibe el interactionId y devuelve todos sus tramos en orden, con las transferencias visibles, más la transcripción.
Cada tramo trae todos los campos de search_interactions y cinco más:
| Campo | Qué trae |
|---|---|
transferBy | Quién hizo la transferencia. |
chatbot | El bot que la atendió, si pasó por uno. |
group | El grupo de campañas. |
ratingComment | El comentario que dejó el cliente al calificar. |
comment | El comentario del agente. |
La transcripción llega solo con transcripts:read, y cada mensaje trae la hora, quién lo escribió, su rol, si era un agente humano, el tipo (text, notification o note, que son las notas internas que el cliente nunca vio), el texto y si llevaba adjunto. Si la conversación sigue abierta, los mensajes vivos se leen en el momento y el resultado dice que los incluye. Sin el permiso, el bloque llega marcado como retenido, en vez de vacío, para que no se lea como una conversación sin mensajes.
aggregate_interactions
Los totales de chat, ya calculados. Existe para que el asistente nunca cuente por su cuenta: pidiéndole que sume una lista de 200 resultados, la cifra que produce se ve exactamente igual que una buena.
Filtros: since, until y groupBy son obligatorios, ventana máxima de 92 días. Se agrupa por una o dos dimensiones entre contact, queue, agent, channel, handledBy, day y hour; con dos, sale una tabla cruzada. Además minConversations, channel, queueName y agentName.
| Campo por grupo | Qué trae |
|---|---|
conversations | Conversaciones, contando una vez las transferidas. |
legs | El conteo en crudo de tramos, que es lo que muestra el reporte de actividad de chat. Va al lado a propósito, para que quien compare las dos cifras vea las dos en vez de concluir que una está mal. |
answered, abandoned | Atendidas por una persona, y abandonadas antes de que alguien las tomara. Una conversación que solo atendió un bot cuenta como conversación pero no como atendida. |
abandonedPercent | El porcentaje de abandono del grupo. |
avgWaitSeconds, longestWaitSeconds | Espera promedio y la peor espera del grupo. |
avgHandlingSeconds | Duración promedio, solo sobre las que ya terminaron. |
inProgress | Cuántas siguen abiertas, que son las que quedaron fuera del promedio anterior. |
rated, avgRating | Cuántas calificaron y con qué promedio. Con cero calificaciones el promedio llega vacío, no en cero. |
contactName, contactVia, contactRef | Solo al agrupar por contacto. contactVia dice si la llave es un teléfono, un correo o un registro de CRM, y contactRef aparece cuando no hay pii:read, para que dos contactos cuyo enmascarado coincide no se lean como uno. |
Los totales repiten esas cifras sobre toda la ventana y suman distinctContacts, unidentifiedConversations y, cuando preguntaste por contactos repetidos, contactsMatching: la respuesta a "cuántos escribieron más de tres veces" como número, no como una lista que habría que contar. Cierra con un campo definitions que explica en prosa qué cuenta cada cifra, incluido el aviso de que una conversación transferida entre dos campañas cuenta en las dos, así que las cifras por campaña pueden sumar más que el total.
search_calls
Las llamadas entrantes que pasaron por una campaña, una fila por llamada aunque haya rodado por varias campañas.
Filtros: since y until obligatorios, hasta 31 días, más queueName, outcome (answered, abandoned, flowout, unknown) y limit.
| Campo | Qué trae |
|---|---|
callId | El identificador, que es lo que recibe get_call. |
startTime, endTime | Cuándo empezó y cuándo terminó. |
phone | El número del llamante, completo o enmascarado según el permiso. phoneWithheld avisa cuando la llamada llegó sin identificador. |
outcome | Atendida, abandonada, salida de la cola, o desconocida cuando nunca se registró el desenlace. |
queue | Dónde la atendieron, o la última campaña en la que estuvo si nadie la tomó. |
queues | Todas las campañas por las que pasó, en orden. Más de una es una transferencia. |
agent | Quién la atendió. |
talkSeconds | Conversación. |
waitSeconds | Espera. Se toma de dos sitios distintos según cómo terminó la llamada, porque ninguno de los dos existe para el otro caso. |
holdSeconds | Tiempo en espera durante la llamada. |
acwSeconds | El trabajo posterior a la llamada. |
endedBy | Quién colgó. Solo tiene sentido en una llamada atendida. |
flowedOutTo | A dónde se fue la llamada que salió de la cola, para que "se salió" no se lea como "se perdió". |
sentiment, analyzed | El sentimiento del análisis, y si la llamada llegó a analizarse. |
client | El cliente identificado en la llamada. |
Junto a la lista viene outcomeCounts, el desglose por desenlace de todo lo examinado en esa pasada, aparte de las filas devueltas para que no se confunda con un conteo de lo que se listó.
get_call
Una llamada entera. Recibe el callId y trae el recorrido completo del llamante más un bloque por cada tramo con agente.
De la llamada: el desenlace, el número, la hora de inicio, la espera, a dónde salió si salió, y queuePath, que es cada entrada a una campaña con su hora, de modo que un llamante que estuvo rebotando se ve como lo que fue. Si entró a una campaña más de doce veces, se listan las primeras y se dice cuántas fueron, porque eso ya no es enrutamiento sino un bucle.
| Campo por tramo | Qué trae |
|---|---|
queue, agent | Dónde y con quién. |
startTime, endTime | Cuándo. |
talkSeconds, waitSeconds, holdSeconds, acwSeconds | Los cuatro tiempos del tramo. |
endedBy | Quién colgó. |
dispositions | Las tipificaciones del agente, como pares de etiqueta y valor. Las casillas vacías no aparecen. |
survey | Las respuestas de la encuesta del IVR, incluidas CSAT, FCR y NPS y las que hayas definido. |
contactName, contactCrmId, client | A quién se atendió. |
sentiment, analyzed | El sentimiento y si hubo análisis. |
qualityScore | El puntaje de calidad. Vacío cuando no se puntuó, que en la base se guarda igual que un cero real. |
scoredCategories | Las categorías que el análisis detectó. |
silencePercentage | Porcentaje de silencio. |
aiSummary | El resumen que escribió la IA sobre la llamada. |
recordingAvailable | Si existe grabación. Nunca la ruta ni el audio: el nombre del archivo se arma con el número del llamante, así que entregarlo devolvería el teléfono que el enmascarado acaba de retener. |
recordingTags, recordingComment | Las etiquetas y el comentario que alguien le puso a esa grabación. |
Con transcripts:read viene además la transcripción del tramo atendido, turno por turno, cada uno con su hora, si habló el agente o el cliente, y lo que dijo.
aggregate_calls
Los totales de voz entrante. Misma idea que el de chat y las mismas garantías.
Filtros: since, until y groupBy obligatorios, hasta 92 días. Se agrupa por una o dos dimensiones entre contact, queue, agent, day, hour y outcome. Además minCalls y queueName.
Cada grupo trae calls, el desglose en answered, abandoned, flowout y unknown con sus porcentajes, avgWaitSeconds y longestWaitSeconds, y avgTalkSeconds con avgHandlingSeconds, que solo existen para las atendidas y promedian sobre ellas. Agrupando por contacto salen además distinctCallers, unidentifiedCalls y callersMatching, que es la respuesta directa a "cuántos llamaron más de tres veces".
search_outbound_calls
Las llamadas salientes que un agente atendió y tipificó: preview, auto, manual y la parte conectada de las predictivas. Se filtran por el momento en que se cerró la tipificación, no por el de la llamada.
Filtros: since y until obligatorios, hasta 31 días, más dialerName, dialerType, agentName, result, contactPhone, amdResult, dialFailed y limit.
| Campo | Qué trae |
|---|---|
callId | El identificador de la llamada. |
at | Cuándo se cerró la tipificación, que es por donde filtra la ventana. |
callStartedAt | Cuándo empezó la llamada de verdad. |
dialer, dialerType, sweeper | La campaña, su tipo y el run concreto. |
agent, agentNumber | Quién la atendió. |
contactName, contactPhone, contactCrmId | A quién se llamó. |
result | La gestión del agente: Completed, Scheduled, Wrong, DontCallAgain, NoAnswer, Busy, Voicemail, Disrupted o NoManageResult. |
typifications | Las tipificaciones como pares de grupo y valor. |
durationSeconds | Lo que duró todo. |
ringSeconds, conversationSeconds | Timbre y conversación, que parten el total en dos. |
wrapUpSeconds | El trabajo posterior. |
conversion | Solo si la campaña tiene regla de conversión configurada. Si no la tiene, en su lugar llega conversionTracked: false, para que un cero no se lea como "nadie convirtió". |
amdResult | El veredicto del detector de contestador, y solo si la campaña lo usa. Si no, llega amdChecked: false. |
dialFailed | Si la central no pudo ni marcar. |
sentiment, analyzed | El sentimiento y si hubo análisis. |
aggregate_outbound_calls
Los totales de saliente. Se agrupa por dialer, agent, day, hour, result, dialerType o contact, hasta dos dimensiones, con ventana de 92 días.
Cada grupo trae calls, connected con su porcentaje, dialFailed, conversions, avgConversationSeconds, avgWrapUpSeconds y resultCounts, que es el conteo por cada gestión posible. El campo definitions nombra explícitamente cuáles de las campañas del resultado tienen regla de conversión, porque sin eso un cero en las demás se lee al revés de lo que es.
list_dialers
Las campañas de marcación configuradas, ordenadas por actividad reciente. Acepta type y withActiveRunsOnly.
| Campo | Qué trae |
|---|---|
name, type | Nombre y tipo de campaña. |
searchable | Falso en las campañas Power, que llaman con IVR y sin agente, así que no tienen llamadas que buscar. Se listan igual y con la nota puesta, para que su lista vacía no se lea como una campaña que no hizo nada. |
conversionTracked, amdEnabled | Si esta campaña mide conversión y si usa detector de contestador. |
closureMode | Qué considera esta campaña que es terminar con un contacto: un intento (CALL_ALL) o una gestión final (MANAGE_ALL). Cambia qué significa "pendiente", así que viaja con la campaña. |
runCount, activeRuns, finishedRuns, lastFinishedRun | Los runs vivos van completos, con nombre, estado, fechas y contactos cargados. Los terminados se cuentan y se muestra el más reciente, porque una campaña acumula años de ellos. |
get_dialer_progress
Cómo va una campaña contra su base de contactos, run por run. Recibe dialerName y opcionalmente sweeperName. Se cuenta desde la propia base de la campaña y no desde el reporte de llamadas, así que una llamada cuya tipificación nunca se cerró cuenta igual como intento.
| Campo por run | Qué trae |
|---|---|
sweeper, state, startDate, endDate | Qué run es y en qué va. |
plannedContacts, loadedContacts | Cuántos contactos se planearon y cuántos se cargaron. |
attemptedContacts | Contactos marcados al menos una vez. |
settledContacts | Contactos que llegaron a una gestión final. |
byDisposition | El desglose en gestionado, número equivocado y no volver a llamar. Son banderas independientes y un contacto puede llevar más de una, así que se reportan por separado y nunca se suman. |
scheduledCallbacks | Contactos con un callback agendado, que no están ni terminados ni sin tocar. |
remainingContacts, progressPercent | Lo que falta y el avance, medido contra lo que esta campaña considera terminar un contacto. Si nunca se cargó una lista, el porcentaje llega vacío en vez de inventarse. |
list_blaster_campaigns
Las campañas que salen sin agente, en sus cuatro canales: voz (el marcador Power), WhatsApp, SMS y correo. Acepta channel, state, activeOnly, name e includeArchived.
Cada campaña trae su canal, su nombre, su estado y si sigue activa, cuándo empezó y terminó, su categoría, si está archivada, si está programada y para cuándo, y la audiencia para la que se armó. Una campaña dinámica no trae audiencia sino la marca dynamic con su explicación, porque sus destinatarios entran en caliente y un cero ahí sería el diseño, no una lista vacía. Las de voz añaden runCount y activeRuns. Una campaña cuyo estado viene de un reenvío se marca con resent.
get_blaster_campaign
Una campaña masiva con sus resultados. Recibe name, y channel solo si el nombre existe en más de uno.
Trae lo mismo que la lista, más el bloque de resultados, que depende del canal:
| Canal | Qué se cuenta |
|---|---|
total, sent, delivered, read, clicked, failed y pending. | |
| SMS | total, sent, delivered, failed y pending. Con dos de los tres proveedores la entrega no se puede observar, y entonces se dice con una bandera en vez de reportar un cero que se leería mal. |
| Correo | total, sent, delivered, opened, failed y pending. |
| Voz | total, answeredByHuman, answeringMachine y failed. No son gestiones sino veredictos del detector de contestador: en un Blaster no hay agente que tipifique. |
Los escalones son acumulativos, no excluyentes: cada destinatario cuenta en el punto más lejano al que llegó su mensaje, así que sumarlos no da nada. El resultado lo dice en su propio texto para que el asistente no los sume. Vienen también failureReasons, el porqué de los fallos con su conteo y de mayor a menor, y los reenvíos como bloques aparte con sus propios resultados, que no están incluidos en los de la campaña.
En SMS y correo la entrega se consulta al proveedor durante 24 horas y después se deja de mirar. Una campaña más vieja que eso trae las cifras congeladas en lo que se supo entonces, y el resultado lo advierte. Sin ese aviso, un "0 entregados" de una campaña de hace meses se lee como una campaña que no recibió nadie.
get_realtime_queues
Qué está pasando ahora mismo. No recibe nada.
| Campo | Qué trae |
|---|---|
waiting, onHold | Cuántos esperan y cuántos están en espera. El hold solo existe en voz. |
agents | Conectados, disponibles, ocupados y en pausa. Solo en voz: la campaña de chat no guarda ese desglose, y reportarlo en cero inventaría un equipo entero ocioso. |
today | Interacciones, atendidas y abandonadas con sus porcentajes, y en voz además las salidas de cola, la espera promedio, la peor espera y el tiempo de atención promedio. Son acumulados del día local y se reinician a medianoche. |
hasPanelData | Si el panel ha escrito algo de esta campaña. Una campaña sin datos no llega en ceros, porque "0 esperando, 0 atendidas" y una mañana tranquila se ven igual. |
waitingNow, liveDataAvailable | El total esperando en toda la instalación, y si hay datos vivos. Cuando ninguna campaña los tiene, se dice que eso suele ser el servicio del panel caído y no un contact center quieto. |
get_realtime_agents
En qué está cada agente en este momento. No recibe nada. Solo aparecen los que están conectados al panel, así que responde "quién está trabajando ahora" y nunca "cuántos agentes tiene esta instalación".
| Campo | Qué trae |
|---|---|
name, number | Quién es. |
signedInSeconds | Cuánto lleva conectado. |
channels | A qué canales entró de verdad. Un agente conectado al panel no está conectado a todo. |
paused, pausedSeconds, pauseReason | Si está en pausa, hace cuánto y cuál. La pausa se reporta aparte de los canales porque lo saca de todas las campañas a la vez, que es justo la respuesta a "por qué no contesta nadie". |
pauseAllowedMinutes, pauseOverByMinutes | Cuánto permite esa pausa y en cuántos minutos se pasó. Así nadie tiene que adivinar si una pausa va larga. |
voice, chat, outbound | El estado por canal (busy, acw o available) y hace cuántos segundos está así. Un canal al que no entró no aparece. |
chatCapacity | Cuántos chats tiene en mano, cuántos aguanta, y cuántos cupos le quedan libres ahora mismo. Contempla el "no molestar", el cierre de conversación y el canal exclusivo, que bloquea el chat mientras el agente está en una llamada. |
El resumen final trae conectados, en pausa, en llamada, en chat, disponibles por canal, y sobre todo chatSlotsFree: cuántas conversaciones más puede aceptar el equipo en este instante. Es la cifra que decide si hay quién atienda, y no se puede deducir de los estados, porque un agente "ocupado" en chat casi siempre tiene cupo de sobra.
Varias instalaciones en una conexión
Una misma conexión puede alcanzar varias instalaciones de Audara, que es el caso de quien opera más de una. Funciona así.
Cuando la conexión llega a más de una, todas las herramientas ganan un parámetro instance con la lista de valores válidos. Si lo especificas, la pregunta va solo a esa instalación. Si lo omites, va a todas y recibes un resultado por cada una.
Para sumar una segunda instalación, el asistente llama a connect_instance y obtiene un enlace. Ese enlace no conecta nada por sí mismo: alguien tiene que abrirlo, iniciar sesión en la instalación que quiere sumar y aprobar el acceso ahí, igual que la primera vez. El enlace vence a los 15 minutos.
Un asistente puede afirmar que ya conectó la instalación después de llamar a connect_instance, cuando lo único que hizo fue obtener un enlace. No quedó conectada hasta que una persona abre ese enlace y aprueba. Para confirmarlo, pide una llamada a list_instances y mira si aparece.
Los permisos se conceden por instalación, así que la misma herramienta puede estar permitida en una y negada en otra. Cuando eso pasa, la herramienta aparece en el catálogo (porque en algún lado sirve) y es la instalación la que rechaza la llamada que no corresponde.
Límites
El conector protege a la plataforma de un asistente entusiasta, porque las consultas de MCP corren sobre la misma infraestructura que los reportes de tu equipo.
| Límite | Valor por defecto | Qué pasa si lo superas |
|---|---|---|
| Peticiones por minuto | 30 por token | Respuesta 429, con Retry-After. |
| Peticiones simultáneas | 2 por token | Respuesta 429. |
| Instalaciones por llamada | 8 | Se consultan las primeras 8 y el resultado avisa que se truncó. |
| Duración de una herramienta | 60 segundos | Se reporta como instalación inalcanzable. |
Los límites son por token y no por dirección IP, a propósito: las peticiones de un cliente de IA llegan desde las salidas compartidas del proveedor, así que contar por IP mezclaría clientes que no tienen nada que ver entre sí.
Cuando algo no funciona
Los errores del conector llegan como respuestas JSON-RPC. Estos son los que vas a ver en la práctica.
| Qué ves | Qué significa |
|---|---|
401 con el token ausente o mal formado | Falta la cabecera Authorization, o el token no tiene la forma esperada. Los tokens empiezan por aud_mcp_. |
401 con el token no vinculado | Ninguna instalación reconoce ese token: puede ser inválido, revocado, o de un usuario desactivado. El conector no distingue entre esos casos a propósito, para no confirmarle a nadie si un token existe. |
429 | Superaste el ritmo o las llamadas simultáneas. Espera lo que diga Retry-After. |
503 | El servidor MCP no está habilitado. |
405 al abrir el canal de eventos | El servidor no envía notificaciones hacia el cliente, solo responde peticiones. No es una falla. |
instance_unreachable | Esa instalación no respondió a tiempo. Las demás sí pueden haber respondido. |
unknown_instance | Pediste un valor de instance que la conexión no alcanza. Se rechaza en vez de consultar todo, para no responder una pregunta que no hiciste. |
Cuando una llamada toca varias instalaciones y unas responden y otras no, recibes los resultados parciales junto con el detalle de qué falló y dónde. Solo se reporta como error completo cuando ninguna respondió.
Si una herramienta rechaza tu llamada, lee el mensaje antes de reintentar: las herramientas explican qué estuvo mal y cómo corregirlo, por ejemplo que la ventana de fechas excede los 31 días. Repetir la misma llamada va a dar el mismo resultado.
Seguridad
- La instalación es la que manda
- El conector no valida tokens: los reenvía y cada instalación verifica el suyo contra su propio registro. Puede revocar por su cuenta, sin depender de nadie.
- La contraseña nunca sale de tu instalación
- En el camino de OAuth, el inicio de sesión y la pantalla de aprobación ocurren en tu propia instalación. El conector solo maneja el protocolo.
- El token no se guarda en claro
- Cada lado guarda una derivación distinta del token, así que ninguna de las dos sirve en el otro lado.
- Solo lectura
- Ninguna herramienta modifica tu operación. Un token filtrado puede leer, no actuar.
- Se revoca desde el perfil del usuario
- Un enlace se desactiva o se elimina en la pestaña MCP, y deja de funcionar en cuestión de segundos. Desactivar al usuario tiene el mismo efecto.
Crea un enlace por asistente y ponle un nombre que diga cuál es, en lugar de compartir uno entre varios. Así puedes revocar el que se comprometió sin dejar a los demás sin servicio, y en la bitácora se distingue quién preguntó qué. Y concede solo los permisos que ese asistente necesita: pii:read únicamente cuando de verdad tenga que contactar a alguien.