Soprano Connect MCP

El servidor MCP de Soprano Connect te permite crear agentes de IA que pueden comunicarse, interactuar con clientes y gestionar flujos de trabajo de comunicaciones a través de la plataforma Soprano Connect utilizando el Protocolo de Contexto de Modelo (MCP).

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de Soprano Connect

El servidor MCP de Soprano Connect le permite crear agentes de IA que pueden comunicarse, interactuar con clientes y gestionar flujos de trabajo de comunicaciones a través de la plataforma Soprano Connect utilizando el Protocolo de Contexto de Modelo (MCP).

El servidor MCP de Soprano Connect permite que asistentes de IA, copilotos, agentes autónomos y aplicaciones empresariales interactúen de forma segura con la plataforma global CPaaS de Soprano Connect. Mediante lenguaje natural, los agentes de IA pueden enviar mensajes, gestionar datos de clientes, administrar cuentas y orquestar comunicaciones a través de múltiples canales en un entorno controlado y de nivel empresarial.

Sin integraciones API complejas. Sin middleware personalizado. Simplemente conecte su cliente de IA compatible con MCP y comience a crear flujos de trabajo de comunicaciones inteligentes: conecte cualquier cliente compatible con MCP (Claude, VS Code Copilot, Cursor, etc.) al servidor MCP de Soprano y permita que su agente envíe mensajes y verifique el estado de entrega a través de múltiples canales, todo mediante lenguaje natural.

💡 ¿Por qué Soprano MCP?

Soprano Connect MCP transforma las capacidades de comunicaciones en herramientas nativas de IA que pueden ser consumidas directamente por agentes de IA. Con Soprano MCP, los agentes de IA pueden:

Enviar comunicaciones omnicanal a través de todos los canales compatibles con la plataforma Soprano Connect
Gestionar contactos y listas de contactos de clientes
Consultar historial de mensajes y estado de entrega
Automatizar flujos de trabajo de interacción con clientes
Crear casos de uso de comunicaciones impulsados por IA sin código de integración personalizado
Operar dentro de un marco de seguridad y gobernanza de nivel empresarial

🛠️ Características principales

Enviar comunicaciones a través de cualquier canal compatible con Soprano Connect, como SMS, RCS, WhatsApp, Viber, Email, Voz, Push móvil
Contenido enriquecido por canal: WhatsApp (multimedia, botones/listas interactivas, plantillas, ubicación, reacciones), RCS (tarjetas enriquecidas, carruseles, sugerencias), Voz (texto a voz, audio pregrabado, Objetos de Control de Llamadas), Notificaciones Push
Envío por lotes y transmisiones, además de consultas de estado de mensajes individuales o por lotes
Listado de plantillas de WhatsApp Business (WABA) y carga/eliminación de multimedia
Autenticación conectable ascendente (Soprano): Clave API, OAuth2 (credenciales de cliente), Básica, OAuth2 heredado y un caso especial de cookie de sesión para plantillas WABA: seleccionada por solicitud, credenciales proporcionadas por el llamante y nunca almacenadas en el servidor

📋 Requisitos previos

Una cuenta API de Soprano Design Connect, aprovisionada con una licencia para cada canal que desee utilizar
Python 3.12+ y uv
Agente de IA o aplicación con soporte de cliente MCP

Cada herramienta/canal solo está disponible si su cuenta de Soprano está suscrita y aprovisionada para el servicio correspondiente. Las funciones fuera de su suscripción actual deben habilitarse mediante el proceso de incorporación o gestión de cuentas de Soprano antes de su uso.

Tabla de contenidos

💡 ¿Por qué Soprano MCP?
🔌 Transportes
- HTTP transmisible
- stdio
✉️ Canales de mensajería
🧰 Herramientas disponibles
🤖 Permisos de agente y control de acceso
🔐 Autenticación
🔒 Autenticación de cliente (opcional)
🚀 Instalación y ejecución
🛠️ Solución de problemas
🤝 Contribuciones
📄 Licencia

🔌 Transportes

El servidor MCP de Soprano admite ambos transportes definidos por la especificación MCP: a diferencia de un servicio multiinquilino alojado, usted lo ejecuta usted mismo (localmente o implementado), por lo que hay un único punto final/proceso en lugar de uno por canal.

HTTP transmisible

Admite transporte HTTP transmisible para uso remoto/implementable (por ejemplo, detrás de un ALB, URL de función Lambda o API Gateway). Apunte su cliente MCP al punto final /mcp del servidor, reemplazando <mems-mcp-server-url> con donde lo haya implementado (o http://127.0.0.1:8000 si se ejecuta localmente).

Si el servidor tiene Autenticación de cliente (MCP_CLIENT_AUTH_MODE=oauth2.1) habilitada con el respaldo de Capa 2 activado — la configuración recomendada para implementaciones alojadas — no se necesitan encabezados X-Soprano-* en absoluto:

{
  "servers": {
    "mems-mcp (http)": {
      "type": "http",
      "url": "<mems-mcp-server-url>/"
    }
  }
}

Su cliente MCP lo redirigirá a través de una página de inicio de sesión/consentimiento OAuth, donde ingresará su ID de API y CLAVE DE API de Soprano Connect — esa es la única credencial que necesita proporcionar. El servidor la utiliza tanto para autenticarlo a usted (Capa 1) como, mediante el respaldo de Capa 2, para autenticar sus propias llamadas a Soprano en su nombre, por lo que los encabezados por solicitud se vuelven innecesarios.

De lo contrario (MCP_CLIENT_AUTH_MODE=none, o si desea pasar diferentes credenciales de Soprano por solicitud), proporcione explícitamente las credenciales de Capa 2 mediante los encabezados X-Soprano-*:

{
  "servers": {
    "mems-mcp (http)": {
      "type": "http",
      "url": "<mems-mcp-server-url>",
      "headers": {
        "X-Soprano-Auth-Method": "api_key",
        "X-Soprano-Api-Id": "${input:soprano-api-id}",
        "X-Soprano-Api-Key": "${input:soprano-api-key}"
      }
    }
  }
}

X-Soprano-Domain-Url generalmente puede omitirse: si el nombre de host público del propio servidor sigue la convención de nomenclatura mcp- (por ejemplo, mcp-aus.sopranodesign.com), deriva automáticamente su dominio de Soprano eliminando ese prefijo (https://aus.sopranodesign.com). Establezca el encabezado explícitamente solo si su implementación no sigue esa convención, o para apuntar a un dominio diferente al implicado por el nombre de host.

Los encabezados X-Soprano-* anteriores son para el método api_key: cámbielos por cualquiera de los otros métodos de autenticación compatibles (consulte Autenticación a continuación) utilizando el conjunto de encabezados correspondiente:

// oauth2 (client credentials)
"headers": {
  "X-Soprano-Auth-Method": "oauth2",
  "X-Soprano-Client-Id": "${input:soprano-client-id}",
  "X-Soprano-Client-Secret": "${input:soprano-client-secret}"
}

// basic
"headers": {
  "X-Soprano-Auth-Method": "basic",
  "X-Soprano-Username": "${input:soprano-username}",
  "X-Soprano-Password": "${input:soprano-password}"
}

// legacy_oauth2
"headers": {
  "X-Soprano-Auth-Method": "legacy_oauth2",
  "X-Soprano-Username": "${input:soprano-username}",
  "X-Soprano-Password": "${input:soprano-password}"
}

El transporte heredado sse (agregue el indicador --transport sse del servidor, punto final /sse) también está disponible para clientes MCP que aún no admiten HTTP transmisible.

stdio

Para uso local (por ejemplo, lanzado como subproceso por VS Code, Claude Desktop, etc.), ejecute con --transport stdio. Dado que stdio no tiene encabezados HTTP, las credenciales de Soprano se proporcionan mediante las variables de entorno SOPRANO_*:

{
  "servers": {
    "mems-mcp (stdio)": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "${workspaceFolder}", "mems-mcp", "--transport", "stdio"],
      "env": {
        "SOPRANO_DOMAIN_URL": "https://aus.sopranodesign.com",
        "SOPRANO_AUTH_METHOD": "api_key",
        "SOPRANO_API_ID": "${input:soprano-api-id}",
        "SOPRANO_API_KEY": "${input:soprano-api-key}"
      }
    }
  }
}

Igual que arriba, cambie el bloque env por cualquier otro método de autenticación:

// oauth2 (client credentials)
"env": {
  "SOPRANO_DOMAIN_URL": "https://aus.sopranodesign.com",
  "SOPRANO_AUTH_METHOD": "oauth2",
  "SOPRANO_CLIENT_ID": "${input:soprano-client-id}",
  "SOPRANO_CLIENT_SECRET": "${input:soprano-client-secret}"
}

// basic
"env": {
  "SOPRANO_DOMAIN_URL": "https://aus.sopranodesign.com",
  "SOPRANO_AUTH_METHOD": "basic",
  "SOPRANO_USERNAME": "${input:soprano-username}",
  "SOPRANO_PASSWORD": "${input:soprano-password}"
}

// legacy_oauth2
"env": {
  "SOPRANO_DOMAIN_URL": "https://aus.sopranodesign.com",
  "SOPRANO_AUTH_METHOD": "legacy_oauth2",
  "SOPRANO_USERNAME": "${input:soprano-username}",
  "SOPRANO_PASSWORD": "${input:soprano-password}"
}

✉️ Canales de mensajería

Todos los canales se exponen a través de una herramienta genérica send_message (el parámetro channel selecciona el destino) en lugar de un servidor MCP por canal: esto mantiene la superficie de herramientas (y la huella de tokens) pequeña mientras brinda acceso a cada tipo de contenido enriquecido específico del canal que admite la API de Connect.

Canal	Valor de `channel`	Contenido enriquecido compatible
SMS	`sms`	Solo texto plano
WhatsApp	`whatsapp`	Multimedia (imagen/video/documento/audio), botones/listas interactivas, plantillas preaprobadas, ubicación, reacciones, contexto (respuestas)
RCS	`rcs`	Tarjetas enriquecidas, carruseles, respuestas/acciones sugeridas, multimedia
Email	`email`	Texto plano, CC/CCO
Voz	`voice`	Texto a voz, archivo de audio pregrabado, Objetos de Control de Llamadas
Viber	`viber`	Texto plano (contenido enriquecido no documentado por la guía de API de Connect: use el campo de paso directo `extra`)
Notificación Push móvil	`pushnotification`	Título + cuerpo

Cualquier cosa no cubierta por un parámetro tipado puede enviarse mediante el campo extra de send_message, fusionado textualmente en la carga útil saliente de la API de Connect.

🧰 Herramientas disponibles

Herramienta	Se asigna a
`send_message`	`POST /cgpapi/messages/{channel}`
`get_message_status`	`GET /cgpapi/messages/{channel}/{id}`
`send_batch`	`POST /cgpapi/batch/messages`
`get_batch_status`	`POST /cgpapi/batch/messages/status`
`send_broadcast`	`POST /cgpapi/broadcast/sms`
`list_whatsapp_templates`	`GET /cgpapi/waba/templates`
`upload_whatsapp_media`	`POST /cgpapi/waba/media/{source}`
`delete_whatsapp_media`	`DELETE /cgpapi/waba/media/{id}`

🤖 Permisos de agente y control de acceso

Cada herramienta está anotada con las anotaciones de herramientas estándar de MCP (readOnlyHint, destructiveHint, openWorldHint) para que un cliente pueda aplicar gobernanza antes de invocarla — por ejemplo, send_message/send_batch/send_broadcast/upload_whatsapp_media no son de solo lectura y alcanzan un mundo abierto (entrega real de mensajes/gasto), y delete_whatsapp_media está además marcada como destructiva. Dado que enviar mensajes tiene un costo real y un impacto reputacional, aplique los controles de permisos de su cliente/host MCP (indicaciones de confirmación, listas permitidas, credenciales con alcance) a estas herramientas en lugar de otorgar a un agente acceso sin restricciones — consulte las consideraciones de implementación de la propia especificación MCP para obtener orientación.

🔐 Autenticación

Las credenciales de Soprano se proporcionan por solicitud, nunca se almacenan en el servidor ni se almacenan en caché entre llamadas. La forma de proporcionarlas depende del transporte (encabezados HTTP para streamable-http/sse, variables de entorno para stdio):

Método de autenticación	Variables de entorno stdio	Encabezados HTTP
Clave API	`SOPRANO_AUTH_METHOD=api_key`, `SOPRANO_API_ID`, `SOPRANO_API_KEY`	`X-Soprano-Auth-Method: api_key`, `X-Soprano-Api-Id`, `X-Soprano-Api-Key`
OAuth2 (credenciales de cliente)	`SOPRANO_AUTH_METHOD=oauth2`, `SOPRANO_CLIENT_ID`, `SOPRANO_CLIENT_SECRET`	`X-Soprano-Auth-Method: oauth2`, `X-Soprano-Client-Id`, `X-Soprano-Client-Secret`
Básica	`SOPRANO_AUTH_METHOD=basic`, `SOPRANO_USERNAME`, `SOPRANO_PASSWORD`	`X-Soprano-Auth-Method: basic`, `X-Soprano-Username`, `X-Soprano-Password`
OAuth2 heredado	`SOPRANO_AUTH_METHOD=legacy_oauth2`, `SOPRANO_USERNAME`, `SOPRANO_PASSWORD`	`X-Soprano-Auth-Method: legacy_oauth2`, `X-Soprano-Username`, `X-Soprano-Password`
Cookie de sesión (solo `list_whatsapp_templates`)	`SOPRANO_AUTH_METHOD=session_cookie`, `SOPRANO_SESSION_COOKIE`	`X-Soprano-Auth-Method: session_cookie`, `X-Soprano-Session-Cookie`

Ambos transportes también requieren el dominio de destino: SOPRANO_DOMAIN_URL (stdio) o X-Soprano-Domain-Url (HTTP), por ejemplo, https://aus.sopranodesign.com. Para streamable-http/sse, este encabezado puede omitirse si el nombre de host público del propio servidor sigue la convención de nomenclatura mcp- (por ejemplo, mcp-aus.sopranodesign.com) — el dominio se deriva automáticamente eliminando ese prefijo.

🔒 Autenticación de cliente (opcional)

Todo lo anterior es Capa 2 (este servidor → Soprano). De forma independiente, también puede requerir autenticación en las solicitudes MCP entrantes (Capa 1 — cliente → este servidor), desactivada por defecto:

Variable de entorno	Requerida	Descripción
`MCP_CLIENT_AUTH_MODE`	—	`none` (predeterminado) o `oauth2.1`
`MCP_OAUTH_ISSUER_URL`	si `oauth2.1`	URL(s) del emisor de su Servidor de Autorización: separadas por comas si esta implementación atiende múltiples dominios. Con el AS autohospedado integrado, esto se deriva automáticamente por solicitud del propio encabezado `Host` del llamante y puede dejarse sin configurar.
`MCP_OAUTH_AUDIENCE`	si `oauth2.1`	Reclamación(es) de `aud` de token esperada(s), separadas por comas: misma derivación por solicitud que arriba con el AS autohospedado.
`MCP_OAUTH_RESOURCE_SERVER_URL`	si `oauth2.1`	URL pública del propio servidor: respaldo predeterminado cuando el `Host` de una solicitud no coincide con ningún dominio configurado.
`MCP_OAUTH_JWKS_URI`	opcional	Predeterminado a `{issuer}/.well-known/jwks.json`
`MCP_OAUTH_REQUIRED_SCOPES`	opcional	Alcances requeridos separados por comas

Funciona con cualquier Servidor de Autorización OAuth2/OIDC compatible con estándares (Auth0, Okta, Cognito, ...).

Servidor de Autorización autohospedado integrado

Algunos clientes MCP (confirmado: Zendesk Agent) requieren un flujo completo interactivo de Código de Autorización OAuth 2.0 + consentimiento en lugar de solo verificación de token portador. En lugar de implementar un IdP separado, este servidor puede actuar como su propio Servidor de Autorización, utilizando el ID de API/CLAVE DE API de Connect del llamante como su identidad: las rutas a continuación están siempre montadas y se vuelven útiles una vez que MCP_CLIENT_AUTH_MODE=oauth2.1 apunta MCP_OAUTH_ISSUER_URL a esta misma implementación:

GET/POST /oauth/authorize — formulario de inicio de sesión y consentimiento, que valida el API ID/API KEY contra el dominio de la API Connect derivado del propio encabezado Host de la solicitud (si sigue la convención mcp-), recurriendo a MEMS_CONNECT_API_URL en caso contrario
POST /oauth/token — concesiones authorization_code (+ PKCE), client_credentials y refresh_token
POST /oauth/register — Registro Dinámico de Clientes RFC 7591; siempre registra un cliente público (protegido por PKCE), sin emitir client_secret
GET /.well-known/oauth-authorization-server / GET /.well-known/jwks.json — metadatos de descubrimiento RFC 8414/7517

La mayoría de los clientes MCP descubren automáticamente los alcances requeridos a partir de esos metadatos. Si el tuyo no lo hace, revisa su lista de scopes_supported en {your-deployment-url}/.well-known/oauth-authorization-server y configúralos manualmente en el cliente.

Variable de entorno	Requerida	Descripción
`MEMS_CONNECT_API_URL`	Sí	Dominio de API Connect de respaldo, utilizado cuando el `Host` de una solicitud no deriva uno mediante la convención `mcp-` (p. ej., múltiples dominios detrás de una sola implementación)
`MCP_OAUTH_SIGNING_KEY` (o `MCP_OAUTH_SIGNING_KEY_SECRET_ARN` para un ARN de AWS Secrets Manager)	Recomendada	Clave privada RSA PEM utilizada para firmar los JWT emitidos; se genera una clave efímera (con una advertencia) si no se establece ninguna — solo es adecuada para un único proceso local
`MCP_OAUTH_CLIENTS_TABLE` / `_CODES_TABLE` / `_CONSENTS_TABLE` / `_AUDIT_TABLE` / `_REFRESH_TOKENS_TABLE`	Opcional	Nombres de tablas de DynamoDB que respaldan el almacenamiento de cliente/código/consentimiento/auditoría/token de actualización (por defecto `mems-mcp-oauth-*`) — requiere credenciales de AWS para `boto3`
`MCP_OAUTH_LAYER2_FALLBACK` / `MCP_OAUTH_LAYER2_CREDENTIALS_TABLE`	Opcional	Permite que los clientes que no pueden enviar encabezados `X-Soprano-*` reutilicen la identidad de Connect con la que se autenticaron en la Capa 1 también para llamadas de la Capa 2 (opt-in; almacena en caché la API KEY real en el servidor, con límite de TTL)

🚀 Instalación y Ejecución

git clone https://github.com/soprano-mcp/mcp.git
cd mcp
uv sync

# stdio (local subprocess, e.g. launched by an MCP client config)
uv run mems-mcp --transport stdio

# streamable-http (remote/deployable)
uv run mems-mcp --transport streamable-http
# host/port: MEMS_MCP_HOST (default 127.0.0.1), MEMS_MCP_PORT (default 8000)

🛠️ Solución de Problemas

Problemas de autenticación

Confirma que los encabezados X-Soprano-* (o las variables de entorno SOPRANO_*) coincidan exactamente con uno de los 5 métodos de autenticación admitidos, incluida la URL del dominio.
list_whatsapp_templates es el único caso atípico que requiere autenticación session_cookie — todas las demás herramientas aceptan los otros 4 métodos.

Problemas de entrega de mensajes

Asegúrate de que el destino del destinatario sea válido para el canal (un número de teléfono para SMS/WhatsApp/RCS/Voz/Viber, una dirección de correo electrónico para Email).
Consulta get_message_status (o get_batch_status para SMS) — una respuesta exitosa de send_message solo significa que Soprano aceptó la solicitud (ENROUTE), no que fue entregada.
Algunos canales/cuentas requieren una licencia/aprovisionamiento explícito en el lado de Soprano (p. ej., conexión de cliente Viber) — una autenticación y carga útil limpias pero un error de tipo licencia de la API significa que debes consultar con el soporte de Soprano.

Otros problemas

Los errores de la API Connect se muestran a través del texto de error de la herramienta (el campo errorDescription de Soprano). Para más detalles a nivel HTTP, consulta la documentación de formato de respuesta/error de la guía de la API Connect.

🤝 Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas en el repositorio.

📄 Licencia

MIT