Sinch

Interactúa con las APIs de Sinch para servicios de comunicación como conversación, correo electrónico, verificación y voz.

GitHub

Documentación

Servidor MCP de Sinch — Vista previa para desarrolladores

Este repositorio contiene el código fuente del servidor MCP de Sinch, que proporciona un conjunto de herramientas para interactuar con las APIs de Sinch. Este README se centra en el uso del servidor MCP con el cliente Claude Desktop, pero también se puede utilizar con cualquier otro cliente MCP.

Resumen de herramientas

Esta es la lista de herramientas disponibles en el servidor MCP (todos los números de teléfono deben proporcionarse en formato E.164, por ejemplo, +33612345678 para Francia).

Herramientas de conversación

Herramienta	Descripción	Etiquetas
send-text-message	Enviar un mensaje de texto plano a un destinatario en un canal compatible. Ejemplo de prompt: "Envía una actualización rápida al número de teléfono +33612345678 por SMS."	conversación, notificación
send-media-message	Enviar una imagen, video o documento mediante un mensaje multimedia. Ejemplo de prompt: "Envía el PDF del folleto del producto al número de teléfono +33612345678 por WhatsApp."	conversación, notificación
send-template-message	Enviar un mensaje utilizando una plantilla predefinida (solo omni-plantilla). Ejemplo de prompt: "Envía la plantilla de recordatorio de cita en español a este usuario por Messenger."	conversación, notificación
send-whatsapp-template-message	Enviar un mensaje utilizando una plantilla de WhatsApp predefinida. Ejemplo de prompt: "Envía un mensaje usando la plantilla 'appointment-reminder' por WhatsApp."	conversación, notificación
send-choice-message	Enviar un mensaje que incluye opciones interactivas (botones o respuestas rápidas). Ejemplo de prompt: "Envía una encuesta RCS sobre el sabor de helado preferido a +33612345678 con las siguientes opciones: Vainilla, Fresa, Avellana".	conversación, notificación
send-location-message	Enviar un pin de ubicación o coordenadas a un usuario. Ejemplo de prompt: "Envía un pin con la ubicación del Museo Guggenheim en Bilbao al número de teléfono +33612345678."	conversación, notificación
list-conversation-apps	Listar todas las aplicaciones de conversación configuradas en la cuenta de Sinch. Ejemplo de prompt: "¿Qué aplicaciones de mensajería tengo configuradas en mi cuenta?"	conversación, notificación
create-conversation-app	Crear una nueva aplicación de Conversation API (no se requieren canales al crearla). Ejemplo de prompt: "Crea una aplicación de conversación llamada Mi Bot de Soporte en la región de la UE."	conversación, configuración
update-conversation-app	Actualizar el nombre para mostrar de una aplicación de Conversation API. Ejemplo de prompt: "Renombra la aplicación de conversación abc123 a Mi Bot de Soporte."	conversación, configuración
delete-conversation-app	Eliminar una aplicación de Conversation API por ID. Ejemplo de prompt: "Elimina la aplicación de conversación abc123."	conversación, configuración
set-sms-channel-on-app	Configurar (crear o reemplazar) el canal SMS en una aplicación de conversación. Ejemplo de prompt: "Configura SMS en la aplicación abc123 usando el plan de servicio XYZ y el token de API …"	conversación, configuración
set-rcs-channel-on-app	Configurar (crear o reemplazar) el canal RCS en una aplicación de conversación. Ejemplo de prompt: "Configura RCS en la aplicación abc123 con el ID de remitente … y el token de portador …"	conversación, configuración
set-whatsapp-channel-on-app	Configurar (crear o reemplazar) el canal de WhatsApp en una aplicación de conversación. Ejemplo de prompt: "Configura WhatsApp en la aplicación abc123 con el ID de remitente … y el token de portador …"	conversación, configuración
list-messaging-templates	Listar las plantillas de mensajes omnicanal (gestionadas por Sinch) para la región configurada. Las plantillas específicas de WhatsApp se pueden obtener con la herramienta `list-whatsapp-templates`. Ejemplo de prompt: "Muéstrame todas las plantillas de mensajes en mi cuenta."	conversación, notificación
list-webhooks	Listar los webhooks configurados para una aplicación de conversación. Ejemplo de prompt: "Lista todos los webhooks de mi aplicación de conversación."	conversación, configuración
get-webhook	Obtener un webhook por ID. Ejemplo de prompt: "Muéstrame los detalles del webhook con ID abc123."	conversación, configuración
create-webhook	Crear un webhook que entregue eventos de Conversation API a una URL de destino. Ejemplo de prompt: "Crea un webhook para mensajes entrantes en https://example.com/callback."	conversación, configuración
update-webhook	Actualizar la URL de destino y/o los disparadores de un webhook. Ejemplo de prompt: "Actualiza el webhook abc123 para que también reciba eventos MESSAGE_DELIVERY."	conversación, configuración
delete-webhook	Eliminar un webhook por ID. Ejemplo de prompt: "Elimina el webhook abc123."	conversación, configuración

Herramientas de correo electrónico (Mailgun)

Herramienta	Descripción	Etiquetas
send-email	Enviar un correo electrónico utilizando una plantilla HTML predefinida o contenido HTML/texto sin formato. Ejemplo de prompt: "Envía un correo de bienvenida a john@example.com usando nuestra plantilla de incorporación."	correo, notificación
list-email-templates	Listar todas las plantillas de correo electrónico disponibles para un dominio específico. Ejemplo de prompt: "¿Qué plantillas de correo tengo disponibles?"	correo, notificación
retrieve-email-info	Recuperar metadatos, contenido y estado de entrega de un mensaje de correo específico. Ejemplo de prompt: "¿Puedes obtener el estado de entrega del correo con ID ?"	correo, notificación
list-email-events	Recuperar y agrupar eventos recientes de entrega de correo, como rebotes, aperturas o clics. Ejemplo de prompt: "Muéstrame toda la actividad de correo reciente de mi cuenta."	correo
analytics-metrics	Recuperar métricas de análisis de correo, como tasas de apertura o tasas de clics. Ejemplo de prompt: "¿Cuáles son las tasas de apertura durante la última semana?"	correo

Herramientas de verificación

Herramienta	Descripción	Etiquetas
number-lookup	Consultar un número de teléfono para conocer su estado y capacidades. Ejemplo de prompt: "Consulta las capacidades del siguiente número de teléfono: +33501020304."	verificación
start-sms-verification	Iniciar una verificación por SMS enviando un OTP al número de teléfono de un usuario. Ejemplo de prompt: "Inicia la verificación telefónica del número +33612345678."	verificación
report-sms-verification	Enviar una contraseña de un solo uso (OTP) para completar la verificación por SMS. Ejemplo de prompt: "Verifica el número de teléfono con este código: 1234."	verificación

Herramientas de voz

Herramienta	Descripción	Etiquetas
tts-callout	Realiza una llamada de voz y lee un mensaje en voz alta usando texto a voz. Ejemplo de prompt: "Llama al número de teléfono +33612345678 y di: 'Tu cita es mañana a las 10 AM.'"	voz, notificación
get-call-information	Obtén información sobre una llamada usando su ID. Ejemplo de prompt: "Obtén los detalles de la llamada con ID abc123."	voz, notificación
list-calls	Lista y filtra llamadas por servicio, endpoint, rango de tiempo, tipo, resultado o motivo. Ejemplo de prompt: "Lista las llamadas completadas de hoy."	voz, notificación
get-session-information	Obtén una sesión de voz y todas sus patas de llamada usando el ID de sesión. Ejemplo de prompt: "Obtén los detalles de la sesión 01BX5ZZKBKACTAV9WEVGEMMVRB."	voz, notificación
create-voice-service	Crea un servicio de voz. Ejemplo de prompt: "Crea un servicio de voz predeterminado llamado Soporte al Cliente."	voz
set-voice-service-webhook	Configura el webhook principal y las URL de respaldo para un servicio de voz. Ejemplo de prompt: "Configura el webhook y el respaldo para el servicio 6e124178-c29d-46a5-943c-5c2ae544aade."	voz
remove-voice-service-webhook	Elimina el manejo de webhook de un servicio de voz. Ejemplo de prompt: "Elimina el webhook del servicio 6e124178-c29d-46a5-943c-5c2ae544aade."	voz
assign-number-to-voice-service	Asigna un número Sinch activo a un servicio de voz. Ejemplo de prompt: "Asigna +14155550100 al servicio de voz 6e124178-c29d-46a5-943c-5c2ae544aade."	voz
tts-batch-callout	Inicia un lote de llamadas salientes que reproducen el mismo mensaje de texto a voz. Ejemplo de prompt: "Llama a estos números en un lote y lee este recordatorio."	voz, notificación
get-voice-batch-summary	Obtén los totales de ejecución del lote y opcionalmente el estado de cada sesión. Ejemplo de prompt: "Obtén el resumen y los detalles de sesión del lote 01BX5ZZKBKACTAV9WEVGEMMVRB."	voz, notificación

Jerarquía de lotes, sesiones y llamadas de voz

Un lote agrupa una solicitud asíncrona para iniciar llamadas a múltiples destinos. tts-batch-callout devuelve un ID de lote, y cada destino produce su propia sesión.
Una sesión representa un flujo de llamada y contiene una o más llamadas. tts-callout devuelve un ID de sesión directamente; usa get-session-information para recuperar sus patas de llamada.
Una llamada es una pata individual dentro de una sesión, identificada por un ID de llamada. Usa get-call-information cuando necesites el estado o los detalles de esa pata específica.

Para inspeccionar un lote de arriba a abajo: usa get-voice-batch-summary con los detalles de sesión habilitados, pasa un ID de sesión devuelto a get-session-information, y luego pasa cualquier ID de llamada devuelto a get-call-information.

Herramientas de Remitentes RCS

Herramienta	Descripción	Etiquetas
list-rcs-senders	Lista todos los remitentes RCS del proyecto, con soporte de paginación. Ejemplo de prompt: "Muéstrame todos mis remitentes RCS."	rcs, configuración
get-rcs-sender	Obtén un remitente RCS completo por ID, incluyendo credenciales, estado, detalles de marca, números de prueba y estado del país. Ejemplo de prompt: "Obtén los detalles de mi remitente RCS abc123."	rcs, configuración
create-rcs-sender	Crea un nuevo remitente RCS. Los detalles de marca, cuestionario y países se pueden proporcionar por adelantado o agregarse incrementalmente mediante update-rcs-sender. Ejemplo de prompt: "Crea un remitente RCS para la región de la UE con una categoría de facturación CONVERSACIONAL."	rcs, configuración
update-rcs-sender	Actualiza la marca, países, números de prueba o cuestionario de un remitente RCS. Ejemplo de prompt: "Actualiza mi remitente RCS abc123 con la URL del logotipo de la marca."	rcs, configuración
launch-rcs-sender	Envía un remitente RCS para revisión de Google y del operador. Todos los detalles de marca, países y secciones del cuestionario deben estar completos antes de lanzar. Ejemplo de prompt: "Lanza mi remitente RCS abc123."	rcs, configuración
add-rcs-test-number	Agrega números de teléfono de prueba a un remitente RCS (máx. 20 por solicitud, 200 en total por remitente). Ejemplo de prompt: "Agrega +14155552671 como número de prueba a mi remitente RCS."	rcs, configuración
delete-rcs-test-number	Elimina un número de prueba de un remitente RCS. Ejemplo de prompt: "Elimina el número de prueba +14155552671 de mi remitente RCS."	rcs, configuración
resend-rcs-test-number-invite	Reenvía una invitación de número de prueba cuando el estado es PENDIENTE o NO VERIFICADO. Ejemplo de prompt: "Reenvía la invitación para el número de prueba +14155552671 en el remitente abc123."	rcs, configuración
get-rcs-test-number-state	Obtén el estado de verificación de un único número de prueba RCS. Ejemplo de prompt: "¿Cuál es el estado del número de prueba +14155552671 en el remitente abc123?"	rcs, configuración
get-rcs-number-capabilities	Obtén las funciones RCS compatibles con el dispositivo de un número de prueba (acciones, diseños de tarjeta enriquecida, revocación). Ejemplo de prompt: "¿Qué funciones RCS admite +14155552671?"	rcs, configuración

Herramientas de WhatsApp

Herramienta	Descripción	Etiquetas
get-whatsapp-account	Obtén la Cuenta Comercial de WhatsApp (WABA) del proyecto: estado de incorporación, ID de WABA, detalles comerciales, estado de bloqueo, límite diario de mensajes y regiones compatibles. Ejemplo de prompt: "¿Cuál es el estado actual de mi Cuenta Comercial de WhatsApp?"	whatsapp, configuración
list-whatsapp-templates	Lista las plantillas de mensajes específicas del canal de WhatsApp (gestionadas por Meta). Las plantillas omnicanal se pueden obtener con la herramienta `list-messaging-templates`. Ejemplo de prompt: "Muéstrame mis plantillas de WhatsApp."	whatsapp, configuración
create-whatsapp-template	Crea una plantilla de mensaje de WhatsApp, como borrador o enviada para revisión. Ejemplo de prompt: "Crea una plantilla de WhatsApp de tipo UTILIDAD llamada order_confirmation en inglés con el texto del cuerpo 'Tu pedido {{1}} ha sido enviado.'"	whatsapp, configuración
update-whatsapp-template	Actualiza un borrador de plantilla de mensaje de WhatsApp (o restablece una plantilla APROBADA/RECHAZADA/EN PAUSA/DESHABILITADA a borrador) por nombre e idioma. Ejemplo de prompt: "Actualiza el texto del cuerpo de la plantilla de WhatsApp order_confirmation EN a 'Tu pedido {{1}} ha sido enviado hoy.' y envíala para revisión."	whatsapp, configuración
delete-single-whatsapp-template-language	Elimina una variante de idioma individual de una plantilla de mensaje de WhatsApp por nombre e idioma: los otros idiomas del mismo nombre de plantilla no se ven afectados. Ejemplo de prompt: "Elimina el borrador de la plantilla de WhatsApp order_confirmation EN."	whatsapp, configuración
delete-all-whatsapp-template-languages	Elimina todas las variantes de idioma de una plantilla de mensaje de WhatsApp por nombre en una sola llamada. Ejemplo de prompt: "Elimina todas las variantes de idioma de la plantilla de WhatsApp order_confirmation."	whatsapp, configuración

Herramientas de Números

Herramienta	Descripción	Etiquetas
list-available-regions	Lista todas las regiones donde hay números de teléfono disponibles para el proyecto. Puede filtrar por tipo de número (`MOBILE`, `LOCAL`, `TOLL_FREE`). Ejemplo de prompt: "¿Qué regiones tienen números gratuitos disponibles?"	numbers
list-rented-numbers	Lista todos los números de teléfono activos (alquilados) para el proyecto. Puede filtrar por región, tipo, patrón y capacidad. Ejemplo de prompt: "Muéstrame todos mis números de teléfono activos en EE. UU."	numbers
search-for-available-numbers	Busca números de teléfono disponibles para alquilar, con filtros por región, tipo, patrón y capacidades. Ejemplo de prompt: "Encuentra números locales disponibles en EE. UU. que admitan SMS."	numbers
rent-sinch-virtual-numbers	Alquila (activa) uno o más números de teléfono proporcionándolos en formato E.164. Ejemplo de prompt: "Alquila el número de teléfono +12025551234."	numbers
release-rented-number	Libera un número de teléfono alquilado de tu proyecto. Ejemplo de prompt: "Libera el número de teléfono +12025551234."	numbers
get-rented-number-configuration	Obtiene un número alquilado y su configuración de servicio actual o programada. Ejemplo de prompt: "Muestra la configuración y el estado de aprovisionamiento de +12025551234."	numbers, configuration

Herramientas de Configuración

Herramienta	Descripción	Etiquetas
sinch-mcp-configuration	Lista todas las herramientas disponibles en el servidor MCP de Sinch y su estado. Si una herramienta está deshabilitada, mostrará el motivo. Ejemplo de prompt: "¿Qué herramientas están disponibles en el servidor MCP de Sinch?"

Primeros Pasos

Requisitos previos

Node.js 20.x o 22.x (LTS)
Una cuenta de Sinch Build aprovisionada
Claude Desktop (o cualquier otro cliente MCP). Este README se centra en Claude Desktop, pero el servidor MCP se puede usar con cualquier cliente MCP.

Credenciales de API

Para usar las APIs utilizadas por las herramientas MCP, necesitarás las siguientes credenciales:

Credenciales de la API RCS: RCS debe estar habilitado para tu proyecto de Sinch. Contacta con si-richmessaging@sinch.com para activarlo. Una vez habilitado, RCS usa los mismos PROJECT_ID, KEY_ID y KEY_SECRET que la API de Conversation (ver más abajo).
Credenciales de la API de Plantillas de WhatsApp: usa los mismos PROJECT_ID, KEY_ID y KEY_SECRET que la API de Conversation (ver más abajo).
Credenciales de las APIs de Conversation / Numbers / Voice v2:
- (Requerido) PROJECT_ID: Selecciona el proyecto que quieras usar desde tu panel de Sinch Build (ubicado a la izquierda de la barra de herramientas superior).
- (Requerido) KEY_ID: Selecciona o crea una nueva clave de acceso en la sección de claves de acceso del panel de Sinch Build.
- (Requerido) KEY_SECRET: Este es el secreto asociado con el Access Key que seleccionaste o creaste en el paso anterior. Ten cuidado, el Access Key Secret solo se muestra una vez cuando creas el Access Key. Si lo pierdes, necesitarás crear un nuevo Access Key.
- CONVERSATION_APP_ID: Este es el ID de la aplicación de conversación que quieras usar. Puedes encontrarlo en la sección API de Conversation / Apps del panel de Sinch Build. Si no lo configuras, tendrás que especificarlo en el prompt.
- CONVERSATION_REGION: Esta es la región donde se encuentran tu aplicación de conversación y tus plantillas. Puede ser us, eu o br. Si no lo configuras, el valor predeterminado es us (excepto en modo multi-tenant, donde es obligatorio y nunca se usa un valor predeterminado).
- Al usar el canal SMS, también puedes configurar la variable de entorno DEFAULT_SMS_ORIGINATOR con el número de teléfono que se usará como remitente de los mensajes SMS. Dependiendo de tu país, esta configuración puede ser obligatoria.
- También puedes configurar la variable de entorno GEOCODING_API_KEY con tu clave de API de Google Geocoding si quieres usar la función de ubicación. Esto es necesario para convertir una dirección en un par de latitud/longitud.
Credenciales de la API de Verification: navega a la sección Verification / Apps del panel de Sinch Build y crea una nueva aplicación o selecciona una existente. Necesitarás las siguientes credenciales:
- (Requerido) APPLICATION_KEY
- (Requerido) APPLICATION_SECRET
Las herramientas de servicio de voz, llamadas, sesiones y lotes usan PROJECT_ID, KEY_ID y KEY_SECRET de las credenciales del proyecto anteriores.
- Opcionalmente, configura CALLING_LINE_IDENTIFICATION con un número de Sinch activo con capacidad de Voz. Se usa como origen predeterminado para tts-callout y tts-batch-callout; los llamantes también pueden proporcionar el origen a cualquiera de las herramientas. Si no se configura ninguno, las llamadas se realizan sin identificador de llamada.
Credenciales de la API de Mailgun: navega a la sección Mailgun / Domains del panel de Mailgun y crea un nuevo dominio o selecciona uno existente. Necesitarás las siguientes credenciales:
- (Requerido) MAILGUN_API_KEY
- MAILGUN_DOMAIN
- MAILGUN_SENDER_ADDRESS

Configuración del Servidor MCP

El servidor MCP de Sinch está disponible como un paquete NPM para ejecutar. Así es como se configura en el archivo de configuración de Claude Desktop (claude_desktop_config.json). Recuerda completar las variables de entorno con tus propias credenciales:

{
  "mcpServers": {
    "sinch": {
      "command": "npx",
      "args": ["-y", "@sinch/mcp"],
      "env": {
        "PROJECT_ID": "",
        "KEY_ID": "",
        "KEY_SECRET": "",
        "CONVERSATION_APP_ID": "",
        "CONVERSATION_REGION": "",
        "DEFAULT_SMS_ORIGINATOR": "",
        "GEOCODING_API_KEY": "",
        "APPLICATION_KEY": "",
        "APPLICATION_SECRET": "",
        "CALLING_LINE_IDENTIFICATION": "",
        "MAILGUN_API_KEY": "",
        "MAILGUN_DOMAIN": "",
        "MAILGUN_SENDER_ADDRESS": ""
      }
    }
  }
}

Ejecutar el Servidor MCP localmente

Opción 1: Iniciar el servidor MCP con stdio usando Claude Desktop

Para ejecutar el servidor MCP localmente con Claude Desktop, necesitarás clonar el repositorio y compilar el servidor MCP. Esta opción es útil para el desarrollo y las pruebas locales.

Paso 1: Clonar el repositorio

git clone https://github.com/sinch/sinch-mcp-server.git

Paso 2: Compilar el servidor MCP

cd sinch-mcp-server
npm install
npm run build

Paso 3: Configurar Claude Desktop

Aquí tienes un ejemplo de cómo configurar el servidor MCP en el archivo de configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "sinch": {
      "command": "node",
      "args": ["/your/path/to/sinch-mcp-server/dist/index.js"],
      "env": {
        "PROJECT_ID": "",
        "KEY_ID": "",
        "KEY_SECRET": "",
        "CONVERSATION_APP_ID": "",
        "CONVERSATION_REGION": "",
        "DEFAULT_SMS_ORIGINATOR": "",
        "GEOCODING_API_KEY": "",
        "APPLICATION_KEY": "",
        "APPLICATION_SECRET": "",
        "CALLING_LINE_IDENTIFICATION": "",
        "MAILGUN_API_KEY": "",
        "MAILGUN_DOMAIN": "",
        "MAILGUN_SENDER_ADDRESS": ""
      }
    }
  }
}

Paso 4: (Opcional) Filtrar las herramientas disponibles en el servidor MCP

Demasiadas herramientas significan un contexto más grande, un mayor uso de tokens y más confusión para que el LLM seleccione la herramienta correcta.
Puedes filtrar las herramientas disponibles en el servidor MCP usando las opciones de tags. Por ejemplo, si solo quieres usar las herramientas de conversación, puedes agregar las siguientes opciones al array de args:

      "args": [
        "/your/path/to/sinch-mcp-server/dist/index.js",
        "--tags",
        "conversation"
      ],

Puedes combinar múltiples etiquetas separándolas con comas. Por ejemplo, si quieres usar tanto las herramientas de conversación como las de verificación, puedes usar el siguiente comando:

      "args": [
        "/your/path/to/sinch-mcp-server/dist/index.js",
        "--tags",
        "conversation,verification"
      ],

Etiquetas disponibles: conversation, rcs, whatsapp, email, verification, voice, numbers, notification, configuration, all.

Si quieres usar todas las herramientas, puedes omitir la opción --tags, o usar la etiqueta all:

      "args": [
        "/your/path/to/sinch-mcp-server/dist/index.js",
        "--tags",
        "all"
      ],

Opción 2: Iniciar el servidor MCP de forma remota y conectarse a él usando SSE

Con esta opción, puedes ejecutar el servidor MCP en una máquina remota y conectarte a él usando Server-Sent Events (SSE). Esto es útil si quieres ejecutar el servidor MCP en un servidor en la nube o en una máquina dedicada. De forma predeterminada, Claude Desktop se conectará al servidor MCP usando STDIO; usaremos la biblioteca supergateway para conectarnos al servidor MCP usando SSE.

Paso 1: Compilar el servidor MCP

cd sinch-mcp-server
npm install
npm run build

Paso 2: Configurar el servidor MCP

Copia el archivo .template.env y renómbralo como .env. Luego reemplaza los marcadores de posición con tus propias credenciales y elimina cualquier clave que no necesites. Las variables de entorno se analizan y se les asigna un tipo al inicio del servidor mediante T3 Env; las credenciales faltantes solo causan errores cuando invocas una herramienta que las requiere. El archivo .env debería verse así ():

# Conversation / Numbers / Voice v2 API tools related environment variables
PROJECT_ID=
KEY_ID=
KEY_SECRET=
## Optional but recommended: the App ID holding your channels integration configuration. If not set it must be present in the prompt
CONVERSATION_APP_ID=
## Optional, defaults to "us". Other possible values are "eu" and "br"
CONVERSATION_REGION=
## Needed only if you want to send SMS messages: it is the number that will be used as the sender for SMS messages
DEFAULT_SMS_ORIGINATOR=
## Needed only if you want to send location messages: it converts an address to a latitude/longitude pair
GEOCODING_API_KEY=

# Verification tools related environment variables
APPLICATION_KEY=
APPLICATION_SECRET=

# Voice tools related environment variables
## Optional default active Sinch Voice number used by tts-callout and tts-batch-callout
CALLING_LINE_IDENTIFICATION=

# Mailgun tools related environment variables
MAILGUN_DOMAIN=
MAILGUN_API_KEY=
MAILGUN_SENDER_ADDRESS=

Paso 3: Iniciar el servidor MCP

npm run start:stdio

De forma predeterminada, este comando iniciará el MCP con todas las herramientas disponibles. Si quieres filtrar las herramientas disponibles en el servidor MCP, puedes usar la opción --tags. Por ejemplo, si solo quieres usar las herramientas de conversación, puedes modificar el comando de la siguiente manera:

# Original command
"start:sse": "tsc --project tsconfig.build.json && (npx -y supergateway --stdio \"node dist/index.js\" --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message)"

# Modified command to only use conversation tools
"start:sse": "tsc --project tsconfig.build.json && (npx -y supergateway --stdio \"node dist/index.js --tag conversation\" --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message)"

Puedes combinar múltiples etiquetas separándolas con comas. Por ejemplo, si quieres usar tanto las herramientas de conversación como las de verificación, puedes usar el siguiente comando:

"start:sse": "tsc --project tsconfig.build.json && (npx -y supergateway --stdio \"node dist/index.js --tag conversation,verification\" --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message)"

Paso 4: Configurar el servidor MCP en Claude Desktop

Luego puedes configurar el servidor MCP en el archivo de configuración de Claude de la siguiente manera:

{
  "mcpServers": {
    "sinch": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse", "http://localhost:8000/sse"]
    }
  }
}

(Reemplaza el http://localhost:8000/sse con la URL de tu servidor MCP si no se está ejecutando localmente)

Opción 3: Servidor HTTP Streamable nativo (recomendado para remoto)

Esta opción ejecuta un servidor MCP HTTP Streamable nativo en /mcp. Es single-tenant o multi-tenant (ver más abajo).

Paso 1: Compilar el servidor MCP

cd sinch-mcp-server
npm install
npm run build

Paso 2: Elegir un modo de tenencia

La tenencia se determina mediante MCP_AUTH_MODE, que se lee primero:

multi-tenant (credenciales de cliente) si MCP_AUTH_MODE es client-credentials
multi-tenant (sinchid-agent) si MCP_AUTH_MODE es sinchid-agent
single-tenant si MCP_AUTH_MODE no está configurado — entonces se requieren PROJECT_ID, KEY_ID y KEY_SECRET

`MCP_AUTH_MODE`	Tenencia	`PROJECT_ID`/`KEY_ID`/`KEY_SECRET`	Las herramientas se ejecutan como
configurado en un modo conocido	Multi-tenant	nunca se leen	lo que envíe el llamante
configurado en cualquier otro valor	—	—	se niega a iniciar
sin configurar	Single-tenant	requeridas, las tres	las credenciales de entorno del servidor

Debido a que el modo se lee antes que cualquier otra cosa, las credenciales dejadas en el entorno no pueden cambiar silenciosamente un servidor multi-tenant de vuelta a una cuenta compartida; allí no se consultan en absoluto, ni para la resolución de credenciales ni para la telemetría. Un valor no reconocido es un error de inicio en lugar de una caída al modo single-tenant, lo que eliminaría la autenticación entrante por completo. Con MCP_AUTH_MODE sin configurar, un triple parcial también se niega a iniciar: configura las tres, o ninguna y un modo.

Single-tenant (sin `MCP_AUTH_MODE`)

Úsalo cuando todos los clientes de esta instancia MCP compartan el mismo proyecto de Sinch — en la práctica, desarrollo local. Las credenciales viven en el servidor, y las tres son requeridas:

PORT=8000
PROJECT_ID=
KEY_ID=
KEY_SECRET=
# MCP_AUTH_MODE deliberately unset

Nota: /mcp no realiza autenticación entrante en este modo. Que MCP_AUTH_MODE no esté definida es toda la configuración, por lo que no hay credenciales por llamante que validar y cualquiera que pueda alcanzar el puerto opera en esa cuenta. Vincúlalo a localhost y no lo expongas. Para un servidor accesible de forma remota, usa un modo multiinquilino.

CONVERSATION_REGION sigue siendo opcional aquí (con valor predeterminado us) y aún se puede sobrescribir desde el prompt.

Multiinquilino (`MCP_AUTH_MODE=client-credentials`)

Úsalo cuando distintos clientes deban usar diferentes proyectos de Sinch. Cada cliente envía sus propias credenciales en cada solicitud:

Cabecera	Valor
`Authorization`	`Bearer <Base64-encoded projectId:keyId:keySecret>`

El servidor no lee PROJECT_ID, KEY_ID ni KEY_SECRET de su entorno en este modo — ni para herramientas respaldadas por OAuth, ni para atributos de span. Los clientes OAuth se almacenan en caché en memoria con expulsión LRU (256 entradas por defecto, configurable mediante OAUTH_TOKEN_CACHE_MAX_ENTRIES).

En los modos multiinquilino, CONVERSATION_REGION es obligatorio: el servidor se niega a iniciar sin él y nunca se establece por defecto a us. Cada despliegue está fijado a una única región, y la región no se puede sobrescribir por solicitud ni desde el prompt.

Cómo se comporta la comprobación de forma

La comprobación de forma existe solo en los modos multiinquilino. Las solicitudes se verifican contra la forma configurada y se rechazan con 401 más un desafío WWW-Authenticate: Bearer en caso contrario:

client-credentials requiere un token que se decodifique a projectId:keyId:keySecret. Un JWT de SinchID contiene separadores ., por lo que nunca se decodifica a un trío de credenciales y se rechaza aquí. x-agent-id se ignora: este despliegue nunca lo lee.
sinchid-agent requiere un JWT de tres segmentos y una cabecera x-agent-id — las credenciales se resuelven desde la instalación de agente que nombra y el id de proyecto de Sinch desde la reclamación verificada del token, por lo que una solicitud sin ella no puede completarse. Un trío de credenciales en Base64 no es un JWT, por lo que se rechaza aquí. Que tenga forma de JWT no basta por sí solo: el token se verifica criptográficamente (ver verificación de token SinchID más abajo) antes de permitir el paso de la solicitud.

Una solicitud sin Authorization en absoluto recibe el desafío solo de ámbito del RFC 6750 (Bearer realm="sinch-mcp") con el motivo en el cuerpo de la respuesta; una solicitud que lleva el tipo equivocado de token, o un JWT que falla la verificación, recibe error="invalid_token" más una descripción.

Dos despliegues de la misma imagen, cada uno con su propio MCP_AUTH_MODE, sirven por tanto a las dos audiencias en nombres de host separados sin que ninguno acepte las credenciales del otro. MCP_AUTH_MODE no tiene efecto sobre stdio.

Verificación de token SinchID (solo `sinchid-agent`)

Cada JWT Authorization de una solicitud sinchid-agent se verifica contra el JWKS configurado antes de permitir el paso de la solicitud: firma (RSA, algoritmo fijado a RS256 — nunca tomado de la cabecera alg del propio token), emisor, audiencia, caducidad (un token sin reclamación exp también se rechaza) y reclamaciones no vacías de proyecto, cuenta, usuario global y ámbito. Un token falsificado, caducado, con emisor/audiencia incorrectos o incompleto se rechaza con 401 y nunca llega a la creación de sesión ni a la ejecución de herramientas.

La verificación JWT requiere tres variables de entorno, todas obligatorias en modo sinchid-agent — el servidor se niega a iniciar sin ellas:

Variable	Valor
`SINCHID_JWT_ISSUER`	Reclamación `iss` esperada (p. ej. `https://id.sinch.com/`)
`SINCHID_JWT_AUDIENCE`	Reclamación `aud` esperada
`SINCHID_JWT_JWKS_URI`	URL del documento JWKS del emisor (claves de firma públicas)

La autenticación de Secret Manager usa Credenciales predeterminadas de la aplicación de Google. Para desarrollo local, ejecuta gcloud auth application-default login; el cliente de Google usa entonces ADC de desarrollador sin una credencial de variable de entorno por agente ni respaldo. Establece GOOGLE_CLOUD_PROJECT cuando ADC no pueda inferir el proyecto propietario de los secretos. GOOGLE_APPLICATION_CREDENTIALS solo se necesita localmente cuando se suministra un archivo JSON de cuenta de servicio; apúntalo a la ruta absoluta de ese archivo y nunca lo confirmes en el repositorio. En Kubernetes, el lanzamiento del agente monta su sa-key.json gestionado por el despliegue desde un Secret.

El documento JWKS completo se conserva en memoria. Las solicitudes HTTP de JWKS se abortan tras 3 segundos sin actividad de red. Tras 10 minutos, el servidor intenta actualizar el documento, pero no descarta primero las claves conocidas: si esa actualización programada falla, los tokens que usan una clave en caché aún pueden verificarse hasta una hora desde la última obtención exitosa. Una actualización exitosa posterior reemplaza el documento inmediatamente y elimina las claves que el emisor ya no publica. Un token cuyo id de clave esté ausente puede provocar como máximo un intento de actualización por período de enfriamiento de 30 segundos, medido desde cada intento (incluidos los fallidos), de modo que una interrupción o una avalancha de ids de clave aleatorios no pueda saturar el endpoint JWKS. Una clave de firma recién publicada se recoge en la primera actualización exitosa tras el período de enfriamiento. Las claves desconocidas se rechazan con 401 tras una búsqueda JWKS exitosa; 503 se reserva para casos en los que un intento de búsqueda no pudo completarse o el último documento exitoso es demasiado antiguo para el respaldo obsoleto.

Las credenciales sinchid-agent se cargan en el momento de la solicitud desde la última versión de Google Secret Manager llamada sinch-agent-m2m_<orderId>_<projectId>. Su carga útil es el mismo blob projectId:keyId:keySecret en Base64 usado por client-credentials. orderId proviene de la cabecera x-agent-id, y projectId se deriva de la reclamación https://sinch.com/project_id del token verificado. Ambos identificadores deben ser UUID canónicos y se convierten a minúsculas al construir el id de secreto. El proyecto de la credencial decodificada debe coincidir con el proyecto verificado. Un secreto ausente, inaccesible, vacío, malformado, no coincidente o con nombre inválido falla de forma segura con una respuesta de prompt. Este modo nunca recurre a PROJECT_ID, KEY_ID ni KEY_SECRET; esas variables siguen siendo exclusivas del modo independiente de un solo inquilino.

Formato de credenciales `Authorization` (solo HTTP)

Construye una cadena UTF-8: projectId:keyId:keySecret (ver credenciales de API).
Codifica con Base64 estándar (sin saltos de línea, alfabeto estándar +// — no base64url).
Envía como Authorization: Bearer <base64> en cada solicitud HTTP (incluido después de la inicialización de sesión MCP).

El secreto de la clave de acceso puede contener caracteres :; solo los primeros dos dos puntos separan los tres campos.

Una solicitud cuya cabecera Authorization falte, use un esquema distinto de Bearer, o cuyo token no sea un trío projectId:keyId:keySecret codificado en Base64 no se rechaza en la capa HTTP: las herramientas respaldadas por OAuth devuelven una respuesta de prompt que indica Missing or invalid Authorization header (expected "Bearer <Base64 of projectId:keyId:keySecret>").

Ejemplo (multiinquilino):

export SINCH_CREDS=$(printf '%s' 'my-project-id:my-key-id:my-key-secret' | base64)

curl -X POST "http://localhost:8000/mcp" \
  -H "Authorization: Bearer ${SINCH_CREDS}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"example","version":"1.0.0"}}}'

Alcance: las credenciales Authorization se aplican a las herramientas de Conversation, Numbers y Number Lookup. Voice, Verification y Mailgun siguen usando variables de entorno del servidor por ahora. Stdio local (Opción 1) siempre usa variables de entorno del servidor.

Cabecera `x-agent-id` (solo `sinchid-agent`)

Las integraciones de agente (p. ej. un agente instalado en una aplicación de Gemini Enterprise) envían una cabecera x-agent-id que lleva el identificador único de instalación (el OrderId de Marketplace). El id de proyecto de Sinch se deriva de la reclamación https://sinch.com/project_id verificada en el JWT Authorization. Juntos nombran qué secreto de Google Secret Manager (sinch-agent-m2m_<orderId>_<projectId>) usa el servidor para resolver las credenciales de Sinch del llamante. La cabecera x-agent-id es obligatoria en despliegues que se ejecutan con MCP_AUTH_MODE=sinchid-agent; una solicitud sin ella se rechaza con 401 antes de llegar a una herramienta. En otros lugares simplemente no se lee — los otros modos la ignoran, y sobre stdio las credenciales siempre provienen del entorno. Esta cabecera personalizada es un mecanismo temporal hasta que haya una capacidad de intercambio de tokens disponible sobre autenticación M2M.

Cabecera	Valor
`x-agent-id`	Identificador de instalación de agente (p. ej. GE `OrderId`)

JWT de usuario `Authorization` (despliegues de agente)

Tras completar el flujo de inicio de sesión y consentimiento OAuth del usuario final, las integraciones de agente pueden enviar el JWT de usuario de Auth0 resultante en cada solicitud:

Cabecera	Valor
`Authorization`	`Bearer <user JWT>`

Una vez que el token ha pasado la verificación (ver verificación de token SinchID más arriba), el servidor captura las reclamaciones de Sinch (https://sinch.com/project_id, https://sinch.com/account_id, https://sinch.com/global_user_id) y la reclamación estándar scope en el contexto de la solicitud, registrándolas con fines de auditoría. La reclamación https://sinch.com/project_id verificada se empareja con x-agent-id para resolver credenciales de API M2M desde Secret Manager (sinch-agent-m2m_<orderId>_<projectId>). El modo de un solo inquilino no lee Authorization; en los modos multiinquilino el token debe coincidir con la forma del despliegue y pasar la verificación, o la solicitud se rechaza con 401. A largo plazo, el JWT de usuario se intercambiará por un JWT M2M, reemplazando las cabeceras personalizadas.

Lo que es el token Authorization depende del despliegue:

Despliegue	Token Bearer	Las credenciales de Sinch provienen de
Un solo inquilino	no se lee, y no es obligatorio	los `PROJECT_ID`/`KEY_ID`/`KEY_SECRET` del servidor
Multiinquilino, `client-credentials`	`projectId:keyId:keySecret` en Base64	el propio token
Multiinquilino, `sinchid-agent`	Token de acceso SinchID (JWT de tres segmentos)	la instalación de agente (Google Secret Manager)

Las dos formas multiinquilino son disjuntas: un JWT contiene separadores ., que no están en el alfabeto Base64, por lo que un trío de credenciales nunca se lee como token y un JWT nunca se resuelve a credenciales. Cada despliegue multiinquilino acepta solo su propia forma y responde 401 a la otra — ver MCP_AUTH_MODE.

Debido a que una solicitud lleva una única cabecera Authorization, las reclamaciones de auditoría descritas arriba se capturan solo donde el token es un JWT — es decir, en un despliegue sinchid-agent. Un llamante client-credentials suministra credenciales en lugar de un token de usuario, por lo que no se registran reclamaciones para él.

Paso 3: Inicia el servidor HTTP

npm run start:http:server

El servidor escucha en http://localhost:8000/mcp por defecto (sobrescríbelo con PORT).

Almacenamiento de sesión (Redis)

La identidad de sesión se almacena en Redis, no en memoria de proceso, de modo que cualquier pod detrás de un balanceador de carga puede validar cualquier sesión — no se requieren sesiones fijas. Cada solicitud construye su propio McpServer y StreamableHTTPServerTransport de corta duración, cerrados una vez que la respuesta termina; nada se mantiene en memoria entre solicitudes. Redis es obligatorio — el servidor sale inmediatamente al inicio a menos que tanto REDIS_HOST como REDIS_PORT estén definidas (REDIS_PASSWORD es opcional; TLS se activa automáticamente una vez que se define, p. ej. para AWS ElastiCache). Si Redis es inalcanzable tras un breve reintento, el servidor devuelve 503 Servicio no disponible con el código de error JSON-RPC -32003, distinto de -32001 Session not found. Debido a que no existe un transporte persistente por sesión, el servidor no admite el flujo GET/SSE independiente — GET /mcp devuelve 405. Las notificaciones iniciadas por el servidor durante un POST (por ejemplo, el progreso de herramientas) funcionan como es habitual; una notificación enviada independientemente de cualquier solicitud no tendría a dónde ir una vez que los transportes son por solicitud.

Paso 4: Ejemplo de configuración de cliente MCP

Cada modo envía la misma forma de cabecera — lo que difiere es de quién son las credenciales que porta el token. Los clientes de un solo inquilino codifican el triple del servidor; los clientes multiinquilino codifican el suyo propio.

{
  "mcpServers": {
    "sinch-remote": {
      "url": "https://your-host.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <base64(projectId:keyId:keySecret)>"
      }
    }
  }
}

Después de la respuesta initialize, incluya la cabecera mcp-session-id devuelta por el servidor en solicitudes posteriores.

Contribuciones

Consulte CONTRIBUTING.md para conocer las pautas para colaboradores, incluido cómo añadir nuevas herramientas y fijar GitHub Actions.

Sinch

Documentación

Servidor MCP de Sinch — Vista previa para desarrolladores

Resumen de herramientas

Herramientas de conversación

Herramientas de correo electrónico (Mailgun)

Herramientas de verificación

Herramientas de voz

Jerarquía de lotes, sesiones y llamadas de voz

Herramientas de Remitentes RCS

Herramientas de WhatsApp

Herramientas de Números

Herramientas de Configuración

Primeros Pasos

Requisitos previos

Credenciales de API

Configuración del Servidor MCP

Ejecutar el Servidor MCP localmente

Opción 1: Iniciar el servidor MCP con stdio usando Claude Desktop

Paso 1: Clonar el repositorio

Paso 2: Compilar el servidor MCP

Paso 3: Configurar Claude Desktop

Paso 4: (Opcional) Filtrar las herramientas disponibles en el servidor MCP

Opción 2: Iniciar el servidor MCP de forma remota y conectarse a él usando SSE

Paso 1: Compilar el servidor MCP

Paso 2: Configurar el servidor MCP

Paso 3: Iniciar el servidor MCP

Paso 4: Configurar el servidor MCP en Claude Desktop

Opción 3: Servidor HTTP Streamable nativo (recomendado para remoto)

Paso 1: Compilar el servidor MCP

Paso 2: Elegir un modo de tenencia

Single-tenant (sin MCP_AUTH_MODE)

Multiinquilino (MCP_AUTH_MODE=client-credentials)

Cómo se comporta la comprobación de forma

Verificación de token SinchID (solo sinchid-agent)

Formato de credenciales Authorization (solo HTTP)

Cabecera x-agent-id (solo sinchid-agent)

JWT de usuario Authorization (despliegues de agente)

Paso 3: Inicia el servidor HTTP

Almacenamiento de sesión (Redis)

Paso 4: Ejemplo de configuración de cliente MCP

Contribuciones

Single-tenant (sin `MCP_AUTH_MODE`)

Multiinquilino (`MCP_AUTH_MODE=client-credentials`)

Verificación de token SinchID (solo `sinchid-agent`)

Formato de credenciales `Authorization` (solo HTTP)

Cabecera `x-agent-id` (solo `sinchid-agent`)

JWT de usuario `Authorization` (despliegues de agente)