Soprano MCP

O servidor Soprano Connect MCP permite que você crie agentes de IA capazes de se comunicar, engajar clientes e gerenciar fluxos de trabalho de comunicação por meio da plataforma Soprano Connect usando o Model Context Protocol (MCP).

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP Soprano Connect

O Servidor MCP Soprano Connect permite que você crie agentes de IA capazes de se comunicar, engajar clientes e gerenciar fluxos de trabalho de comunicação através da plataforma Soprano Connect usando o Model Context Protocol (MCP).

O Servidor MCP Soprano Connect permite que assistentes de IA, copilotos, agentes autônomos e aplicações empresariais interajam de forma segura com a plataforma global de CPaaS da Soprano Connect. Usando linguagem natural, agentes de IA podem enviar mensagens, gerenciar dados de clientes, administrar contas e orquestrar comunicações em múltiplos canais em um ambiente controlado e de nível empresarial.

Sem integrações complexas de API. Sem middleware personalizado. Basta conectar seu cliente de IA compatível com MCP e começar a construir fluxos de trabalho inteligentes de comunicação — conecte qualquer cliente compatível com MCP (Claude, VS Code Copilot, Cursor, etc.) ao servidor MCP Soprano e deixe seu agente enviar mensagens e verificar status de entrega em múltiplos canais, tudo através de linguagem natural.

💡 Por que Soprano MCP?

O Soprano Connect MCP transforma capacidades de comunicação em ferramentas nativas de IA que podem ser consumidas diretamente por agentes de IA. Com o Soprano MCP, agentes de IA podem:

Enviar comunicações omnichannel em todos os canais suportados pela plataforma Soprano Connect
Gerenciar contatos e listas de contatos de clientes
Consultar histórico de mensagens e status de entrega
Automatizar fluxos de trabalho de engajamento de clientes
Construir casos de uso de comunicação com IA sem código de integração personalizado
Operar dentro de uma estrutura de segurança e governança de nível empresarial

🛠️ Principais Recursos

Envie comunicações através de qualquer canal suportado pela Soprano Connect, como SMS, RCS, WhatsApp, Viber, Email, Voz, Push Móvel
Conteúdo rico por canal — WhatsApp (mídia, botões/listas interativas, templates, localização, reações), RCS (cartões ricos, carrosséis, sugestões, mídia), Voz (texto-para-fala, áudio pré-gravado, Objetos de Controle de Chamada), Notificação Push
Envio em lote e broadcast, além de consultas de status de mensagens individuais/em lote
Listagem de templates do WhatsApp Business (WABA) e upload/exclusão de mídia
Autenticação upstream (Soprano) plugável — API Key, OAuth2 (credenciais de cliente), Basic, OAuth2 Legado e um caso especial de cookie de sessão para templates WABA — selecionada por requisição, credenciais fornecidas pelo chamador e nunca armazenadas no servidor

📋 Pré-requisitos

Uma conta de API Soprano Design Connect, provisionada com uma licença para cada canal que você deseja usar
Python 3.12+ e uv
Agente de IA ou aplicação com suporte a cliente MCP

Cada ferramenta/canal só está disponível se sua conta Soprano estiver assinada e provisionada para o serviço correspondente. Recursos fora da sua assinatura atual devem ser habilitados através do processo de onboarding ou gerenciamento de conta da Soprano antes do uso.

Sumário

💡 Por que Soprano MCP?
🔌 Transportes
- HTTP Streamable
- stdio
✉️ Canais de Mensagens
🧰 Ferramentas Disponíveis
🤖 Permissão de Agente e Controle de Acesso
🔐 Autenticação
🔒 Autenticação de Cliente (opcional)
🚀 Instalação e Execução
🛠️ Solução de Problemas
🤝 Contribuindo
📄 Licença

🔌 Transportes

O servidor MCP Soprano suporta ambos os transportes definidos pela especificação MCP — ao contrário de um serviço multi-tenant hospedado, você o executa você mesmo (localmente ou implantado), então há um único endpoint/processo em vez de um por canal.

HTTP Streamable

Suporta transporte HTTP streamable para uso remoto/implantável (por exemplo, atrás de um ALB, URL de Função Lambda ou API Gateway). Aponte seu cliente MCP para o endpoint /mcp do servidor, substituindo <mems-mcp-server-url> por onde você o implantou (ou http://127.0.0.1:8000 se estiver executando localmente).

Se o servidor tiver Autenticação de Cliente (MCP_CLIENT_AUTH_MODE=oauth2.1) habilitada com o fallback de Camada 2 ativado — a configuração recomendada para implantações hospedadas — nenhum cabeçalho X-Soprano-* é necessário:

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

Seu cliente MCP o redirecionará através de uma página de login/consentimento OAuth, onde você insere seu API ID e API KEY da Soprano Connect — essa é a única credencial que você precisa fornecer. O servidor a usa tanto para autenticar você (Camada 1) quanto, através do fallback de Camada 2, para autenticar suas próprias chamadas à Soprano em seu nome, tornando os cabeçalhos por requisição desnecessários.

Caso contrário (MCP_CLIENT_AUTH_MODE=none, ou se você quiser passar credenciais Soprano diferentes por requisição), forneça credenciais de Camada 2 explicitamente via cabeçalhos 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 geralmente pode ser omitido: se o hostname público do próprio servidor seguir a convenção de nomenclatura mcp- (por exemplo, mcp-aus.sopranodesign.com), ele deriva seu domínio Soprano automaticamente removendo esse prefixo (https://aus.sopranodesign.com). Defina o cabeçalho explicitamente apenas se sua implantação não seguir essa convenção, ou para direcionar um domínio diferente do implicado pelo hostname.

Os cabeçalhos X-Soprano-* acima são para o método api_key — troque-os por qualquer um dos outros métodos de autenticação suportados (veja Autenticação abaixo) usando o conjunto de cabeçalhos correspondente:

// 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}"
}

O transporte legado sse (adicione o flag --transport sse do servidor, endpoint /sse) também está disponível para clientes MCP que ainda não suportam HTTP streamable.

stdio

Para uso local (por exemplo, iniciado como subprocesso pelo VS Code, Claude Desktop, etc.), execute com --transport stdio. Como stdio não tem cabeçalhos HTTP, as credenciais Soprano são fornecidas via variáveis de ambiente 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}"
      }
    }
  }
}

Assim como acima, troque o bloco env por qualquer outro método de autenticação:

// 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}"
}

✉️ Canais de Mensagens

Todos os canais são expostos através de uma ferramenta genérica send_message (o parâmetro channel seleciona o alvo) em vez de um servidor MCP por canal — isso mantém a superfície de ferramentas (e a pegada de tokens) pequena, enquanto ainda dá acesso a cada tipo de conteúdo rico específico de canal que a API Connect suporta.

Canal	Valor de `channel`	Conteúdo rico suportado
SMS	`sms`	Apenas texto simples
WhatsApp	`whatsapp`	Mídia (imagem/vídeo/documento/áudio), botões/listas interativas, templates pré-aprovados, localização, reações, contexto (respostas)
RCS	`rcs`	Cartões ricos, carrosséis, respostas/ações sugeridas, mídia
Email	`email`	Texto simples, CC/CCO
Voz	`voice`	Texto-para-fala, arquivo de áudio pré-gravado, Objetos de Controle de Chamada
Viber	`viber`	Texto simples (conteúdo rico não documentado pelo guia da API Connect — use o campo de passagem `extra`)
Notificação Push Móvel	`pushnotification`	Título + corpo

Qualquer coisa não coberta por um parâmetro tipado pode ser enviada através do campo extra de send_message, mesclado literalmente no payload de saída da API Connect.

🧰 Ferramentas Disponíveis

Ferramenta	Mapeia para
`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}`

🤖 Permissão de Agente e Controle de Acesso

Cada ferramenta é anotada com as anotações de ferramenta padrão do MCP (readOnlyHint, destructiveHint, openWorldHint) para que um cliente possa aplicar governança antes de invocá-la — por exemplo, send_message/send_batch/send_broadcast/upload_whatsapp_media são não-somente-leitura e alcançam um mundo aberto (entrega real de mensagens/gastos), e delete_whatsapp_media é adicionalmente sinalizada como destrutiva. Como o envio de mensagens tem custo e impacto reputacional no mundo real, aplique os controles de permissão do seu cliente/host MCP (prompts de confirmação, listas de permissão, credenciais com escopo) a essas ferramentas em vez de conceder acesso irrestrito a um agente — veja as considerações de implementação da própria especificação MCP para orientação.

🔐 Autenticação

As credenciais Soprano são fornecidas por requisição, nunca armazenadas no servidor ou em cache entre chamadas. Como você as fornece depende do transporte (cabeçalhos HTTP para streamable-http/sse, variáveis de ambiente para stdio):

Método de autenticação	Variáveis de ambiente stdio	Cabeçalhos HTTP
API Key	`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 (credenciais 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`
Basic	`SOPRANO_AUTH_METHOD=basic`, `SOPRANO_USERNAME`, `SOPRANO_PASSWORD`	`X-Soprano-Auth-Method: basic`, `X-Soprano-Username`, `X-Soprano-Password`
OAuth2 Legado	`SOPRANO_AUTH_METHOD=legacy_oauth2`, `SOPRANO_USERNAME`, `SOPRANO_PASSWORD`	`X-Soprano-Auth-Method: legacy_oauth2`, `X-Soprano-Username`, `X-Soprano-Password`
Cookie de sessão (apenas `list_whatsapp_templates`)	`SOPRANO_AUTH_METHOD=session_cookie`, `SOPRANO_SESSION_COOKIE`	`X-Soprano-Auth-Method: session_cookie`, `X-Soprano-Session-Cookie`

Ambos os transportes também exigem o domínio alvo — SOPRANO_DOMAIN_URL (stdio) ou X-Soprano-Domain-Url (HTTP), por exemplo, https://aus.sopranodesign.com. Para streamable-http/sse, este cabeçalho pode ser omitido se o hostname público do próprio servidor seguir a convenção de nomenclatura mcp- (por exemplo, mcp-aus.sopranodesign.com) — o domínio é então derivado automaticamente removendo esse prefixo.

🔒 Autenticação de Cliente (opcional)

Tudo acima é Camada 2 (este servidor → Soprano). Independentemente, você também pode exigir autenticação em requisições MCP recebidas (Camada 1 — cliente → este servidor), desativada por padrão:

Variável de ambiente	Obrigatória	Descrição
`MCP_CLIENT_AUTH_MODE`	—	`none` (padrão) ou `oauth2.1`
`MCP_OAUTH_ISSUER_URL`	se `oauth2.1`	URL(s) do emissor do seu Servidor de Autorização — separadas por vírgula se esta implantação atende múltiplos domínios. Com o AS auto-hospedado integrado, isso é derivado automaticamente por requisição do cabeçalho `Host` do próprio chamador e pode ser deixado não definido.
`MCP_OAUTH_AUDIENCE`	se `oauth2.1`	Claim(s) de token `aud` esperado(s), separados por vírgula — mesma derivação por requisição acima com o AS auto-hospedado.
`MCP_OAUTH_RESOURCE_SERVER_URL`	se `oauth2.1`	URL pública do próprio servidor — padrão de fallback quando o `Host` de uma requisição não corresponde a nenhum domínio configurado.
`MCP_OAUTH_JWKS_URI`	opcional	Padrão para `{issuer}/.well-known/jwks.json`
`MCP_OAUTH_REQUIRED_SCOPES`	opcional	Escopos obrigatórios separados por vírgula

Funciona com qualquer Servidor de Autorização OAuth2/OIDC compatível com padrões (Auth0, Okta, Cognito, ...).

Servidor de Autorização auto-hospedado integrado

Alguns clientes MCP (confirmado: Zendesk Agent) exigem um fluxo completo e interativo de Código de Autorização OAuth 2.0 + consentimento em vez de apenas verificação de token bearer. Em vez de montar um IdP separado, este servidor pode atuar como seu próprio Servidor de Autorização, usando o API ID/API KEY Connect do chamador como sua identidade — as rotas abaixo estão sempre montadas e se tornam úteis uma vez que MCP_CLIENT_AUTH_MODE=oauth2.1 aponta MCP_OAUTH_ISSUER_URL para esta mesma implantação:

GET/POST /oauth/authorize — formulário de login+consentimento, validando o API ID/API KEY contra o domínio da Connect API derivado do cabeçalho Host da própria requisição (se seguir a convenção mcp-), com fallback para MEMS_CONNECT_API_URL caso contrário
POST /oauth/token — concessões authorization_code (+ PKCE), client_credentials e refresh_token
POST /oauth/register — Registro Dinâmico de Cliente RFC 7591; sempre registra um cliente público (protegido por PKCE), sem emissão de client_secret
GET /.well-known/oauth-authorization-server / GET /.well-known/jwks.json — metadados de descoberta RFC 8414/7517

A maioria dos clientes MCP descobre os escopos necessários automaticamente a partir desses metadados. Se o seu não fizer isso, verifique a lista de scopes_supported em {your-deployment-url}/.well-known/oauth-authorization-server e configure-os manualmente no cliente.

Variável de ambiente	Obrigatória	Descrição
`MEMS_CONNECT_API_URL`	Sim	Domínio da Connect API de fallback, usado quando o `Host` de uma requisição não deriva um via convenção `mcp-` (ex.: múltiplos domínios atrás de uma única implantação)
`MCP_OAUTH_SIGNING_KEY` (ou `MCP_OAUTH_SIGNING_KEY_SECRET_ARN` para um ARN do AWS Secrets Manager)	Recomendada	Chave privada PEM RSA usada para assinar JWTs emitidos; uma chave efêmera é gerada (com um aviso) se nenhuma for definida — adequada apenas para um único processo local
`MCP_OAUTH_CLIENTS_TABLE` / `_CODES_TABLE` / `_CONSENTS_TABLE` / `_AUDIT_TABLE` / `_REFRESH_TOKENS_TABLE`	opcional	Nomes de tabelas DynamoDB que armazenam dados de cliente/código/consentimento/auditoria/refresh-token (padrão para `mems-mcp-oauth-*`) — requer credenciais AWS para `boto3`
`MCP_OAUTH_LAYER2_FALLBACK` / `MCP_OAUTH_LAYER2_CREDENTIALS_TABLE`	opcional	Permite que clientes que não conseguem enviar cabeçalhos `X-Soprano-*` reutilizem a identidade Connect autenticada na Camada 1 também para chamadas da Camada 2 (opt-in; armazena em cache a API KEY real no servidor, com limite de TTL)

🚀 Instalação e Execução

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)

🛠️ Solução de Problemas

Problemas de autenticação

Confirme se os cabeçalhos X-Soprano-* (ou as variáveis de ambiente SOPRANO_*) correspondem exatamente a um dos 5 métodos de autenticação suportados, incluindo a URL do domínio.
list_whatsapp_templates é a única exceção que exige autenticação session_cookie — todas as outras ferramentas aceitam os outros 4 métodos.

Problemas de entrega de mensagens

Certifique-se de que o destino do destinatário é válido para o canal (um número de telefone para SMS/WhatsApp/RCS/Voice/Viber, um endereço de e-mail para Email).
Verifique get_message_status (ou get_batch_status para SMS) — uma resposta send_message bem-sucedida apenas significa que a Soprano aceitou a requisição (ENROUTE), não que ela foi entregue.
Alguns canais/contas exigem uma licença/provisionamento explícito no lado da Soprano (ex.: conexão de cliente Viber) — uma autenticação/payload limpa, mas um erro de licenciamento vindo da API, significa verificar com o suporte da Soprano.

Outros problemas

Erros da Connect API são exibidos via o texto de erro da ferramenta (campo errorDescription da Soprano). Para detalhes mais profundos no nível HTTP, consulte a documentação de formato de resposta/erro do guia da Connect API.

🤝 Contribuições

Issues e pull requests são bem-vindos no repositório.

📄 Licença

MIT