CommSync
Una bandeja de entrada para SMS y correo empresarial. Busca y lee mensajes de texto y correos en cada línea telefónica y buzón, gestiona contactos y etiquetas, clasifica hilos y envía SMS y correos desde las líneas que permitas. Servidor remoto alojado con OAuth 2.1.
Servidor MCP alojado
npx add-mcp 'https://server.commsync.ai/api/mcp'Se instala en Claude Code, Codex, Cursor y más
Documentación
Servidor MCP
CommSync habla el Protocolo de Contexto de Modelo. Apunta una aplicación o agente compatible con MCP al endpoint. Así podrá leer hilos, enviar mensajes, gestionar contactos y etiquetas, y más.
Hay dos formas de autenticarse, y ambas llegan a las mismas herramientas:
- OAuth 2.1 es la forma principal. La aplicación te identifica sin secreto compartido. Consulta Conectar aplicaciones de IA.
- Una clave API es la alternativa para scripts y servidores. Envíala como token Bearer. Consulta Claves API.
OAuth es como se conectan Claude, ChatGPT, Codex, Cursor y VS Code.
El usuario autenticado y su rol en la organización delimitan cada operación.
Los agentes pueden obtener /docs/mcp.txt para el mismo catálogo como texto plano con todos los detalles de parámetros: una sola solicitud, sin scraping.
Conectar
El servidor es un único endpoint HTTP sin estado. Para conectar una aplicación de IA, pega la URL del endpoint en la aplicación e inicia sesión. La página Conectar aplicaciones de IA tiene una guía para cada aplicación.
Para llamar al endpoint desde tu propio código con una clave API:
Genera una clave API
En CommSync, abre **Configuración → Claves API** y crea una clave. CommSync la muestra
una sola vez: guárdala de forma segura. Consulta <a href="/docs/api-keys">Claves API</a>.
Llama al endpoint
Envía JSON-RPC por POST a la ruta <code>/api/mcp</code> en tu origen de API de CommSync.
```bash
curl -X POST "$COMMSYNC_API/api/mcp" \
-H "Authorization: Bearer csk_your_api_key" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
Llama a una herramienta
Usa <code>tools/call</code> con el nombre de la herramienta y sus argumentos.
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": { "name": "list_threads", "arguments": { "limit": 20 } }
}
```
| Endpoint | POST /api/mcp (en tu origen de API de CommSync) |
| Transporte | HTTP, sin estado: una solicitud por llamada |
| Autenticación | Token de acceso OAuth 2.1, o Authorization: Bearer csk_… |
Autenticación
OAuth 2.1
CommSync es su propio servidor de autorización. Un cliente solo necesita la URL del endpoint, porque descubre todo lo demás:
- Una solicitud sin token recibe
401y un encabezadoWWW-Authenticate. El encabezado nombra los metadatos del recurso protegido (/.well-known/oauth-protected-resource/api/mcp, RFC 9728). - Ese documento nombra el servidor de autorización. Sus metadatos están en
/.well-known/oauth-authorization-server(RFC 8414). - El cliente se registra, te envía a la pantalla de consentimiento e intercambia el código por tokens.
| Concesión | Código de autorización con PKCE (solo S256) |
| Registro de cliente | Registro dinámico en POST /oauth/register (RFC 7591), o un Documento de Metadatos de ID de Cliente: una URL https como client_id |
| Autenticación de cliente | none (clientes públicos), client_secret_post, client_secret_basic |
| Alcance | mcp (el predeterminado cuando omites scope) |
| Recurso | La URL del endpoint (RFC 8707). CommSync vincula cada token a ella |
| Token de acceso | csat_…, válido durante una hora |
| Token de actualización | csrt_…, válido durante 90 días. Rota en cada uso. Durante 30 segundos después de un uso, el mismo token recibe el mismo par nuevo otra vez, para un cliente que actualice dos veces a la vez. Después, un token usado revoca su familia de tokens |
| Revocación | POST /oauth/revoke (RFC 7009) |
La respuesta de autorización incluye iss (RFC 9207). Una redirección de
bucle local (http://127.0.0.1, http://localhost, http://[::1]) puede usar cualquier puerto.
Un código es de un solo uso. Un segundo intercambio que pase la verificación PKCE revoca los tokens que emitió el primer intercambio. CommSync rechaza un segundo intercambio sin el verificador correcto, y ese intercambio no cambia nada.
Clave API
Envía Authorization: Bearer csk_…. Una clave no caduca y la revocas
en Configuración, en Claves API. Una clave es adecuada para un script o un agente
del lado del servidor.
Modelo de autorización
Cada solicitud resuelve tu credencial (un token OAuth o una clave API) a
(userId, orgId, role, accessibleChannels).
Cada herramienta está detrás de una de cuatro puertas. El servidor rechaza una llamada que
exceda tu acceso antes de que ocurra cualquier cosa.
cualquier miembro cualquier usuario de la organización acceso a canal necesita acceso al canal correspondiente propietario / administrador solo propietario
- cualquier miembro: cualquier usuario con membresía en la organización.
- acceso a canal: debes tener acceso al canal involucrado.
- propietario / administrador: reservado para propietarios y administradores de la organización.
- solo propietario: el único propietario del espacio de trabajo (por ejemplo, facturación).
Los propietarios y administradores tienen acceso a canales implícitamente; los miembros lo obtienen por canal: consulta Roles y permisos.
CommSync también etiqueta las herramientas por efecto: read (sin cambios), write (modifica) o
destructive (elimina datos: úsalo con cuidado).
Claves y aplicaciones con alcance de canal
Una clave API o una aplicación conectada puede ajustarse a líneas específicas en lugar de tu acceso completo a canales. Para una clave, elige Líneas específicas cuando la crees o edites en Configuración, en Claves API. Para una aplicación, elígela en la pantalla de consentimiento. Puedes cambiarlo más tarde en Configuración, en Conectar aplicaciones de IA. Elige las direcciones de correo y números de teléfono a los que puede acceder.
El servidor entonces cruza tu acceso en vivo a canales con la lista de permitidos en cada solicitud. Una clave o aplicación con alcance solo puede leer, enviar y actuar en las líneas elegidas. Los hilos en otros canales le son invisibles, y CommSync rechaza envíos desde otros canales. Los listados de canales solo muestran lo que está dentro del alcance.
- El valor predeterminado es Todos los canales: la clave sigue tu acceso en vivo.
- Esto incluye líneas que conectes más tarde; CommSync migró las claves preexistentes de esta manera.
- Una clave con alcance nunca supera tus privilegios.
- Si pierdes el acceso, o alguien elimina la línea, también desaparece del alcance de la clave.
- Las superficies por usuario (contactos, etiquetas, IA, webhooks, perfil) no pertenecen a un canal, por lo que el alcance no las afecta.
Catálogo de herramientas
Hilos
Lecturas con alcance de organización (filtradas por acceso a canal); las modificaciones escriben solo tu propio estado de vista por usuario.
| Herramienta | Acceso | Tipo | Descripción |
|---|---|---|---|
list_threads | acceso a canal | lectura | Lista los hilos visibles para ti |
get_thread_summary | acceso a canal | lectura | Resumen de un solo hilo en formato de fila de lista |
get_thread_messages | acceso a canal | lectura | Mensajes paginados de un hilo |
mark_thread_read | acceso a canal | escritura | Limpia tu contador de no leídos |
mark_thread_unread | acceso a canal | escritura | Fuerza un hilo como no leído para ti |
archive_thread | acceso a canal | escritura | Archivar (por usuario) |
unarchive_thread | acceso a canal | escritura | Desarchivar (por usuario) |
mark_thread_spam | acceso a canal | escritura | Mover a Spam (por usuario) |
mark_thread_promotions | acceso a canal | escritura | Mover a Promociones (por usuario) |
mark_thread_automated | acceso a canal | escritura | Mover a Mensajes Automatizados: correo no humano (por usuario) |
move_thread_to_inbox | acceso a canal | escritura | Limpiar banderas de categoría (por usuario) |
snooze_thread | acceso a canal | escritura | Posponer hasta una marca de tiempo (por usuario) |
unsnooze_thread | acceso a canal | escritura | Limpiar una posposición (por usuario) |
delete_thread | acceso a canal | destructivo | Ocultar el hilo de tu vista; la organización conserva su copia |
restore_thread | acceso a canal | escritura | Restaurar un hilo eliminado temporalmente |
delete_message | acceso a canal | destructivo | Ocultar un mensaje de ti |
hard_delete_thread | propietario / administrador | destructivo | Eliminar permanentemente el hilo y los mensajes compartidos |
Envíos salientes
CommSync aplica el acceso a canal antes de cualquier envío. Redactar y reenviar también necesitan al menos un canal accesible del tipo correcto.
| Herramienta | Acceso | Tipo | Descripción |
|---|---|---|---|
send_sms | acceso a canal | escritura | Responder en un hilo SMS actual |
send_email | acceso a canal | escritura | Responder en un hilo de correo actual |
compose_sms | acceso a canal | escritura | Iniciar una nueva conversación SMS |
compose_email | acceso a canal | escritura | Iniciar una nueva conversación de correo |
forward_message | acceso a canal | escritura | Reenviar un mensaje a un nuevo destinatario |
resend_failed_message | acceso a canal | escritura | Reintentar un mensaje saliente fallido |
get_send_capacity | acceso a canal | lectura | Tasa de envío sostenible por línea, más cualquier pausa activa por límite de tasa |
Cuerpos de correo
send_email y compose_email toman dos campos de cuerpo: bodyText y
bodyHtml. Proporciona uno de ellos o ambos. Una llamada sin ninguno falla antes de que
CommSync envíe cualquier cosa.
El texto plano solo es suficiente. CommSync construye la parte HTML a partir de bodyText.
Escapa el texto, conserva los saltos de línea y convierte cada enlace http:// o
https:// en un enlace clicable. Cuando proporcionas bodyHtml, CommSync
envía tu HTML sin cambios. Cuando proporcionas solo bodyHtml, CommSync
crea la parte de texto plano a partir de él. La firma de la cuenta y el pie de página
"Enviado desde CommSync", cuando están activados, van después de tu texto en ambas partes.
Los límites de tasa nunca te alcanzan
CommSync acepta cada envío autorizado y asume la entrega desde ese punto
en adelante: esto también cubre los límites de tasa de operadores y servidores de correo. Las herramientas
de envío no devuelven 429 y nunca te piden que reintentes. Cuando un proveedor nos limita,
el mensaje permanece en cola, retrocede y sale por sí solo.
Cada herramienta de envío devuelve un recibo que describe dónde está el mensaje realmente:
{
"accepted": true,
"messageId": "cm9x…",
"threadId": "cm7a…",
"state": "waiting_on_line",
"estimatedSendAt": "2026-07-29T18:41:12.000Z",
"pacing": {
"provider": "<platform name>",
"sustainedPerMinute": 54,
"rateLimited": true,
"reason": "<platform name> rate limit — waiting 45s"
}
}
state es uno de dispatching, waiting_on_line, scheduled, sent o
failed. Nunca llames a una herramienta de envío dos veces para el mismo mensaje: CommSync
ya ha puesto en cola un mensaje waiting_on_line y lo entregará.
Antes de una ejecución masiva, llama a get_send_capacity para la tasa sostenible en cada
línea desde la que puedas enviar. Si la superas, es seguro: los mensajes se ponen
en cola en lugar de fallar; simplemente tardan más en salir.
Gestión de canales
| Herramienta | Acceso | Tipo | Descripción |
|---|---|---|---|
list_email_accounts | acceso a canal | lectura | Lista los canales de cuentas de correo que puedes ver |
add_email_account | cualquier miembro | escritura | Vincular un buzón IMAP/SMTP a la organización |
delete_email_account | propietario / administrador | destructivo | Eliminar una cuenta de correo |
test_email_account | acceso a canal | lectura | Probar las credenciales IMAP/SMTP almacenadas |
list_phone_numbers | acceso a canal | lectura | Lista los canales de números de teléfono que puedes ver |
add_phone_number | cualquier miembro | escritura | Vincular un número de teléfono a la organización |
delete_phone_number | propietario / administrador | destructivo | Eliminar un número de teléfono |
Facturación
| Herramienta | Acceso | Tipo | Descripción |
|---|---|---|---|
get_billing_state | cualquier miembro | lectura | Nivel, estado, asientos, límites, uso |
change_tier | solo propietario | escritura | Cambiar el nivel de suscripción (prorratea) |
set_seats | solo propietario | escritura | Establecer la cantidad de asientos pagados (prorratea) |
seats_preview | solo propietario | lectura | Simulación de un cambio de asientos prorrateado |
Contactos
El grafo de contactos es privado por usuario: nunca se filtra entre usuarios.
| Herramienta | Acceso | Tipo | Descripción |
|---|---|---|---|
list_contacts | cualquier miembro | lectura | Lista tus contactos |
get_contact | cualquier miembro | lectura | Un contacto, con identidades y etiquetas |
create_contact | cualquier miembro | escritura | Crear un nuevo contacto |
update_contact | cualquier miembro | escritura | Actualizar el nombre visible o las notas |
delete_contact | cualquier miembro | destructivo | Eliminar un contacto; las identidades quedan huérfanas |
merge_contacts | cualquier miembro | destructivo | Fusionar contactos completos en un único superviviente; CommSync elimina las fuentes |
merge_identities | cualquier miembro | escritura | Fusionar dos identidades bajo un mismo contacto |
split_identity | cualquier miembro | escritura | Separar una identidad en huérfana |
attach_identity_to_contact | cualquier miembro | escritura | Adjuntar una huérfana a un contacto |
promote_identity_to_contact | cualquier miembro | escritura | Promover una huérfana a un nuevo contacto |
Identidades
| Herramienta | Acceso | Tipo | Descripción |
|---|---|---|---|
get_identity | cualquier miembro | lectura | Una identidad y su contacto |
update_identity_notes | cualquier miembro | escritura | Editar notas por canal |
list_orphaned_identities | cualquier miembro | lectura | Identidades aún no vinculadas a un contacto |
list_all_identities | cualquier miembro | lectura | Todas las identidades que posees |
Etiquetas
| Herramienta | Acceso | Tipo | Descripción |
|---|---|---|---|
list_labels | cualquier miembro | lectura | Listar etiquetas con recuentos de uso |
create_label | cualquier miembro | escritura | Crear una etiqueta (nombre y color hexadecimal) |
update_label | cualquier miembro | escritura | Actualizar el nombre, el color o el prompt de IA |
delete_label | cualquier miembro | destructivo | Eliminar una etiqueta en todas partes |
assign_label | cualquier miembro | escritura | Aplicar una etiqueta a un contacto o identidad |
unassign_label | cualquier miembro | escritura | Quitar una etiqueta |
IA
| Herramienta | Acceso | Tipo | Descripción |
|---|---|---|---|
get_ai_settings | cualquier miembro | lectura | Leer la configuración de IA |
update_ai_settings | cualquier miembro | escritura | Actualizar la configuración de IA |
get_todays_digest | cualquier miembro | lectura | Resumen diario de hoy (o de una fecha) |
list_digests | cualquier miembro | lectura | Resúmenes diarios recientes |
dismiss_digest | cualquier miembro | escritura | Marcar un resumen como descartado |
trigger_digest_run | cualquier miembro | escritura | Ejecutar un resumen ahora |
list_ai_runs | cualquier miembro | lectura | Entradas recientes de actividad de IA |
test_ai_connectivity | cualquier miembro | lectura | Verificar que CommSync tenga IA configurada |
trigger_inbox_backfill | cualquier miembro | escritura | Clasificar remitentes históricos en Promociones o Spam |
Búsqueda, cuenta y webhooks
| Herramienta | Acceso | Tipo | Descripción |
|---|---|---|---|
search | cualquier miembro | lectura | Buscar contactos, identidades, mensajes |
search_threads | cualquier miembro | lectura | Búsqueda completa centrada en hilos: cada conversación que coincida con una consulta, clasificada y paginada, con fragmentos de coincidencia |
get_profile | cualquier miembro | lectura | Tu perfil (id, correo, nombre) |
update_profile | cualquier miembro | escritura | Actualizar tu nombre para mostrar |
list_webhooks | cualquier miembro | lectura | Listar tus endpoints de webhook |
get_webhook | cualquier miembro | lectura | Un único endpoint |
register_webhook | cualquier miembro | escritura | Crear un endpoint (devuelve el secreto una sola vez) |
update_webhook | cualquier miembro | escritura | Modificar url / eventos / modo / estado |
rotate_webhook_secret | cualquier miembro | escritura | Rotar el secreto de firma (el anterior válido 24 h) |
delete_webhook | cualquier miembro | destructivo | Eliminar un endpoint y su historial |
list_webhook_deliveries | cualquier miembro | lectura | Registro de entregas paginado |
resend_webhook_delivery | cualquier miembro | escritura | Reintentar una entrega |
Los Agentes de CommSync son los compañeros de IA que responden a los mensajes de texto y correos entrantes. Los configuras y gestionas a través de la aplicación o de la API de administración REST, no a través de este catálogo de herramientas MCP. Consulta Agents para más detalles.
Deliberadamente no existe ninguna herramienta MCP que permita a un agente
externo crear, reconfigurar o aprobar turnos para un Agente de CommSync.
Usa send_sms o send_email de arriba para que tu propia
integración responda directamente en su lugar.
Recursos
Además de las herramientas, el servidor expone recursos MCP para lecturas directas:
commsync://threads/{threadId}/messages — messages in a thread
commsync://contacts/{personId} — a contact's detail
commsync://digests/{localDate} — the AI digest for a date
Flujos de trabajo comunes
Clasificar la bandeja de entrada
`list_threads` → `get_thread_messages(threadId)` para leer lo más reciente.
Responder
`get_thread_messages(threadId)` para encontrar la identidad por la que llegó un mensaje →
<code>send_sms</code> o <code>send_email</code> con esa `identityId`.
Fusionar un contacto duplicado
`list_orphaned_identities` (o `search`) para encontrar la identidad suelta →
`merge_identities(identityAId, identityBId)` o
`attach_identity_to_contact(personId, identityId)`. Para dos registros de contacto
completos de la misma persona, confirma ambos con `get_contact` y
llama a `merge_contacts(survivorPersonId, sourcePersonIds)` en su lugar.
Reaccionar en tiempo real
No tienes que llamar a `list_threads` una y otra vez. Registra un
<a href="/docs/webhooks">webhook</a> y vuelve a llamar a MCP solo cuando
se dispare un evento.
Conecta una aplicación en Connect AI apps, o crea una clave en API keys. Luego configura webhooks, para que tu agente reaccione a los mensajes y no tenga que preguntar una y otra vez. Referencia completa de parámetros: /docs/mcp.txt.