Sinch

Interaja com as APIs da Sinch para serviços de comunicação como conversa, e-mail, verificação e voz.

Documentação

Servidor MCP Sinch — Prévia para Desenvolvedores

Este repositório contém o código-fonte do servidor MCP Sinch, que fornece um conjunto de ferramentas para interagir com as APIs Sinch. Este README foca no uso do servidor MCP com o cliente Claude Desktop, mas também pode ser usado com qualquer outro cliente MCP.

Visão Geral das Ferramentas

Aqui está a lista de ferramentas disponíveis no servidor MCP (todos os números de telefone devem ser fornecidos no formato E.164, ex.: +33612345678 para França).

Ferramentas de Conversa

Ferramenta	Descrição	Tags
send-text-message	Envia uma mensagem de texto simples para um destinatário em um canal suportado. Exemplo de prompt: "Envie uma atualização rápida para o número +33612345678 via SMS."	conversa, notificação
send-media-message	Envia uma imagem, vídeo ou documento por meio de uma mensagem de mídia. Exemplo de prompt: "Envie o PDF do folheto do produto para o número +33612345678 via WhatsApp."	conversa, notificação
send-template-message	Envia uma mensagem usando um modelo predefinido (somente omni-template). Exemplo de prompt: "Envie o modelo de lembrete de consulta em espanhol para este usuário no Messenger."	conversa, notificação
send-whatsapp-template-message	Envia uma mensagem usando um modelo predefinido do WhatsApp. Exemplo de prompt: "Envie uma mensagem usando o modelo 'appointment-reminder' no WhatsApp."	conversa, notificação
send-choice-message	Envia uma mensagem que inclui opções interativas (botões ou respostas rápidas). Exemplo de prompt: "Envie uma pesquisa RCS sobre o sabor de sorvete preferido para +33612345678 com as seguintes opções: Baunilha, Morango, Avelã."	conversa, notificação
send-location-message	Envia um pin de localização ou coordenadas para um usuário. Exemplo de prompt: "Envie um pin da localização do Museu Guggenheim em Bilbao para o número +33612345678."	conversa, notificação
list-conversation-apps	Lista todos os aplicativos de Conversa configurados na conta Sinch. Exemplo de prompt: "Quais aplicativos de mensagens eu tenho configurados na minha conta?"	conversa, notificação
create-conversation-app	Cria um novo aplicativo da API de Conversa (nenhum canal é necessário na criação). Exemplo de prompt: "Crie um aplicativo de Conversa chamado Meu Bot de Suporte na região da UE."	conversa, configuração
update-conversation-app	Atualiza o nome de exibição de um aplicativo da API de Conversa. Exemplo de prompt: "Renomeie o aplicativo de Conversa abc123 para Meu Bot de Suporte."	conversa, configuração
delete-conversation-app	Exclui um aplicativo da API de Conversa por ID. Exemplo de prompt: "Exclua o aplicativo de Conversa abc123."	conversa, configuração
set-sms-channel-on-app	Define (cria ou substitui) o canal SMS em um aplicativo de Conversa. Exemplo de prompt: "Defina SMS no aplicativo abc123 usando o plano de serviço XYZ e o token da API …"	conversa, configuração
set-rcs-channel-on-app	Define (cria ou substitui) o canal RCS em um aplicativo de Conversa. Exemplo de prompt: "Defina RCS no aplicativo abc123 com o ID do remetente … e o token de portador …"	conversa, configuração
set-whatsapp-channel-on-app	Define (cria ou substitui) o canal WhatsApp em um aplicativo de Conversa. Exemplo de prompt: "Defina WhatsApp no aplicativo abc123 com o ID do remetente … e o token de portador …"	conversa, configuração
list-messaging-templates	Lista os modelos de mensagens omni-canal (gerenciados pela Sinch) para a região configurada. Modelos específicos do WhatsApp podem ser obtidos com a ferramenta `list-whatsapp-templates`. Exemplo de prompt: "Mostre-me todos os modelos de mensagens na minha conta."	conversa, notificação
list-webhooks	Lista os webhooks configurados para um aplicativo de Conversa. Exemplo de prompt: "Liste todos os webhooks do meu aplicativo de Conversa."	conversa, configuração
get-webhook	Obtém um webhook por ID. Exemplo de prompt: "Mostre-me os detalhes do webhook ID abc123."	conversa, configuração
create-webhook	Cria um webhook que entrega eventos da API de Conversa para uma URL de destino. Exemplo de prompt: "Crie um webhook para mensagens recebidas em https://example.com/callback."	conversa, configuração
update-webhook	Atualiza a URL de destino e/ou os gatilhos de um webhook. Exemplo de prompt: "Atualize o webhook abc123 para também receber eventos MESSAGE_DELIVERY."	conversa, configuração
delete-webhook	Exclui um webhook por ID. Exemplo de prompt: "Exclua o webhook abc123."	conversa, configuração

Ferramentas de E-mail (Mailgun)

Ferramenta	Descrição	Tags
send-email	Envia um e-mail usando um modelo HTML predefinido ou conteúdo HTML/texto bruto. Exemplo de prompt: "Envie um e-mail de boas-vindas para john@example.com usando nosso modelo de integração."	e-mail, notificação
list-email-templates	Lista todos os modelos de e-mail disponíveis para um domínio específico. Exemplo de prompt: "Quais modelos de e-mail eu tenho disponíveis?"	e-mail, notificação
retrieve-email-info	Recupera metadados, conteúdo e status de entrega de uma mensagem de e-mail específica. Exemplo de prompt: "Você pode obter o status de entrega do e-mail com ID ?"	e-mail, notificação
list-email-events	Recupera e agrupa eventos recentes de entrega de e-mail, como rejeições, aberturas ou cliques. Exemplo de prompt: "Mostre-me toda a atividade recente de e-mail da minha conta."	e-mail
analytics-metrics	Recupera métricas de análise de e-mail, como taxas de abertura ou taxas de clique. Exemplo de prompt: "Quais são as taxas de abertura na última semana?"	e-mail

Ferramentas de Verificação

Ferramenta	Descrição	Tags
number-lookup	Consulta um número de telefone para verificar seu status e capacidades. Exemplo de prompt: "Consulte as capacidades do seguinte número de telefone: +33501020304."	verificação
start-sms-verification	Inicia uma verificação por SMS enviando um OTP para o número de telefone de um usuário. Exemplo de prompt: "Inicie a verificação de telefone para o número +33612345678."	verificação
report-sms-verification	Envia uma senha de uso único (OTP) para concluir a verificação por SMS. Exemplo de prompt: "Verifique o número de telefone com este código: 1234."	verificação

Ferramentas de Voz

Ferramenta	Descrição	Tags
tts-callout	Faça uma chamada de voz e leia em voz alta uma mensagem usando Text-to-Speech. Exemplo de prompt: "Ligue para o número +33612345678 e diga: 'Sua consulta é amanhã às 10h.'"	voz, notificação
get-call-information	Obtenha informações sobre uma chamada usando seu ID. Exemplo de prompt: "Obtenha os detalhes da chamada com ID abc123."	voz, notificação
list-calls	Liste e filtre chamadas por serviço, endpoint, intervalo de tempo, tipo, resultado ou motivo. Exemplo de prompt: "Liste as chamadas concluídas de hoje."	voz, notificação
get-session-information	Obtenha uma sessão de voz e todas as suas pernas de chamada usando o ID da sessão. Exemplo de prompt: "Obtenha detalhes da sessão 01BX5ZZKBKACTAV9WEVGEMMVRB."	voz, notificação
create-voice-service	Crie um serviço de Voice. Exemplo de prompt: "Crie um serviço de Voice padrão chamado Suporte ao Cliente."	voz
set-voice-service-webhook	Configure o webhook principal e as URLs de fallback para um serviço de Voice. Exemplo de prompt: "Configure o webhook e o fallback para o serviço 6e124178-c29d-46a5-943c-5c2ae544aade."	voz
remove-voice-service-webhook	Remova o tratamento de webhook de um serviço de Voice. Exemplo de prompt: "Remova o webhook do serviço 6e124178-c29d-46a5-943c-5c2ae544aade."	voz
assign-number-to-voice-service	Atribua um número Sinch ativo a um serviço de Voice. Exemplo de prompt: "Atribua +14155550100 ao serviço de Voice 6e124178-c29d-46a5-943c-5c2ae544aade."	voz
tts-batch-callout	Inicie um lote de chamadas de saída que reproduzem a mesma mensagem de texto para fala. Exemplo de prompt: "Ligue para esses números em lote e leia este lembrete."	voz, notificação
get-voice-batch-summary	Obtenha os totais de execução do lote e, opcionalmente, o estado de cada sessão. Exemplo de prompt: "Obtenha o resumo e os detalhes da sessão para o lote 01BX5ZZKBKACTAV9WEVGEMMVRB."	voz, notificação

Hierarquia de lote, sessão e chamada de voz

Um lote agrupa uma solicitação assíncrona para iniciar chamadas para vários destinos. tts-batch-callout retorna um ID de lote, e cada destino produz sua própria sessão.
Uma sessão representa um fluxo de chamada e contém uma ou mais chamadas. tts-callout retorna um ID de sessão diretamente; use get-session-information para recuperar suas pernas de chamada.
Uma chamada é uma perna individual dentro de uma sessão, identificada por um ID de chamada. Use get-call-information quando precisar do status ou detalhes dessa perna específica.

Para inspecionar um lote de cima para baixo: use get-voice-batch-summary com detalhes de sessão habilitados, passe um ID de sessão retornado para get-session-information e, em seguida, passe qualquer ID de chamada retornado para get-call-information.

Ferramentas de Remetentes RCS

Ferramenta	Descrição	Tags
list-rcs-senders	Liste todos os remetentes RCS do projeto, com suporte a paginação. Exemplo de prompt: "Mostre-me todos os meus remetentes RCS."	rcs, configuração
get-rcs-sender	Obtenha um remetente RCS completo por ID, incluindo credenciais, estado, detalhes da marca, números de teste e status do país. Exemplo de prompt: "Obtenha os detalhes do meu remetente RCS abc123."	rcs, configuração
create-rcs-sender	Crie um novo remetente RCS. Detalhes da marca, questionário e países podem ser fornecidos antecipadamente ou adicionados incrementalmente via update-rcs-sender. Exemplo de prompt: "Crie um remetente RCS para a região da UE com uma categoria de cobrança CONVERSATIONAL."	rcs, configuração
update-rcs-sender	Atualize a marca, países, números de teste ou questionário de um remetente RCS. Exemplo de prompt: "Atualize meu remetente RCS abc123 com a URL do logotipo da marca."	rcs, configuração
launch-rcs-sender	Envie um remetente RCS para revisão do Google e das operadoras. Todos os detalhes da marca, países e seções do questionário devem estar completos antes do lançamento. Exemplo de prompt: "Lance meu remetente RCS abc123."	rcs, configuração
add-rcs-test-number	Adicione números de telefone de teste a um remetente RCS (máx. 20 por solicitação, 200 no total por remetente). Exemplo de prompt: "Adicione +14155552671 como número de teste ao meu remetente RCS."	rcs, configuração
delete-rcs-test-number	Exclua um número de teste de um remetente RCS. Exemplo de prompt: "Remova o número de teste +14155552671 do meu remetente RCS."	rcs, configuração
resend-rcs-test-number-invite	Reenvie um convite de número de teste quando o estado for PENDING ou UNVERIFIED. Exemplo de prompt: "Reenvie o convite para o número de teste +14155552671 no remetente abc123."	rcs, configuração
get-rcs-test-number-state	Obtenha o estado de verificação de um único número de teste RCS. Exemplo de prompt: "Qual é o estado do número de teste +14155552671 no remetente abc123?"	rcs, configuração
get-rcs-number-capabilities	Obtenha os recursos RCS suportados pelo dispositivo de um número de teste (ações, layouts de cartão rico, revogação). Exemplo de prompt: "Quais recursos RCS o +14155552671 suporta?"	rcs, configuração

Ferramentas do WhatsApp

Ferramenta	Descrição	Tags
get-whatsapp-account	Obtenha a Conta Comercial do WhatsApp (WABA) do projeto: estado de integração, ID da WABA, detalhes comerciais, estado de banimento, limite diário de mensagens e regiões compatíveis. Exemplo de prompt: "Qual é o status atual da minha Conta Comercial do WhatsApp?"	whatsapp, configuração
list-whatsapp-templates	Liste os modelos de mensagem específicos do canal WhatsApp (gerenciados pela Meta). Modelos omnicanal podem ser obtidos com a ferramenta `list-messaging-templates`. Exemplo de prompt: "Mostre-me meus modelos do WhatsApp."	whatsapp, configuração
create-whatsapp-template	Crie um modelo de mensagem do WhatsApp, como rascunho ou enviado para revisão. Exemplo de prompt: "Crie um modelo UTILITY do WhatsApp chamado order_confirmation em inglês com o texto do corpo 'Seu pedido {{1}} foi enviado.'"	whatsapp, configuração
update-whatsapp-template	Atualize um rascunho de modelo de mensagem do WhatsApp (ou redefina um modelo APPROVED/REJECTED/PAUSED/DISABLED para rascunho) por nome e idioma. Exemplo de prompt: "Atualize o texto do corpo do modelo EN order_confirmation do WhatsApp para 'Seu pedido {{1}} foi enviado hoje.' e envie para revisão."	whatsapp, configuração
delete-single-whatsapp-template-language	Exclua uma única variante de idioma de um modelo de mensagem do WhatsApp por nome e idioma — outros idiomas do mesmo nome de modelo não são afetados. Exemplo de prompt: "Exclua o rascunho do modelo EN order_confirmation do WhatsApp."	whatsapp, configuração
delete-all-whatsapp-template-languages	Exclua todas as variantes de idioma de um modelo de mensagem do WhatsApp por nome em uma única chamada. Exemplo de prompt: "Exclua todas as variantes de idioma do modelo order_confirmation do WhatsApp."	whatsapp, configuração

Ferramentas de Números

Ferramenta	Descrição	Tags
list-available-regions	Lista todas as regiões onde números de telefone estão disponíveis para o projeto. Pode filtrar por tipo de número (`MOBILE`, `LOCAL`, `TOLL_FREE`). Exemplo de prompt: "Quais regiões têm números 0800 disponíveis?"	numbers
list-rented-numbers	Lista todos os números de telefone ativos (alugados) para o projeto. Pode filtrar por região, tipo, padrão e capacidade. Exemplo de prompt: "Mostre-me todos os meus números de telefone ativos nos EUA."	numbers
search-for-available-numbers	Busca números de telefone disponíveis para alugar, com filtros por região, tipo, padrão e capacidades. Exemplo de prompt: "Encontre números locais disponíveis nos EUA que suportem SMS."	numbers
rent-sinch-virtual-numbers	Aluga (ativa) um ou mais números de telefone fornecendo-os no formato E.164. Exemplo de prompt: "Alugue o número de telefone +12025551234."	numbers
release-rented-number	Libera um número de telefone alugado do seu projeto. Exemplo de prompt: "Libere o número de telefone +12025551234."	numbers
get-rented-number-configuration	Obtém um número alugado e sua configuração de serviço atual ou agendada. Exemplo de prompt: "Mostre a configuração e o status de provisionamento para +12025551234."	numbers, configuration

Ferramentas de Configuração

Ferramenta	Descrição	Tags
sinch-mcp-configuration	Lista todas as ferramentas disponíveis no servidor MCP Sinch e seu status. Se uma ferramenta estiver desabilitada, exibirá o motivo. Exemplo de prompt: "Quais ferramentas estão disponíveis no servidor MCP Sinch?"

Primeiros Passos

Pré-requisitos

Node.js 20.x ou 22.x (LTS)
Uma conta Sinch Build provisionada
Claude Desktop (ou qualquer outro cliente MCP). Este README é focado no Claude Desktop, mas o servidor MCP pode ser usado com qualquer cliente MCP.

Credenciais da API

Para usar as APIs utilizadas pelas ferramentas MCP, você precisará das seguintes credenciais:

Credenciais da API RCS: o RCS deve estar habilitado para o seu projeto Sinch. Entre em contato com si-richmessaging@sinch.com para ativá-lo. Uma vez habilitado, o RCS usa os mesmos PROJECT_ID, KEY_ID e KEY_SECRET da API de Conversa (veja abaixo).
Credenciais da API de Modelos do WhatsApp: usa os mesmos PROJECT_ID, KEY_ID e KEY_SECRET da API de Conversa (veja abaixo).
Credenciais das APIs de Conversa / Números / Voice v2:
- (Obrigatório) PROJECT_ID: Selecione o projeto que deseja usar no seu painel Sinch Build (localizado à esquerda da barra de ferramentas superior)
- (Obrigatório) KEY_ID: Selecione ou crie uma nova chave de acesso na seção de chaves de acesso do painel Sinch Build.
- (Obrigatório) KEY_SECRET: Este é o segredo associado ao Access Key que você selecionou ou criou na etapa anterior. Cuidado: o Access Key Secret é mostrado apenas uma vez quando você cria o Access Key. Se você o perder, precisará criar um novo Access Key.
- CONVERSATION_APP_ID: Este é o ID do aplicativo de conversa que você deseja usar. Você pode encontrá-lo na seção API de Conversa / Aplicativos do painel Sinch Build. Se você não o definir, precisará especificá-lo no prompt.
- CONVERSATION_REGION: Esta é a região onde seu aplicativo de conversa e modelos estão localizados. Pode ser us, eu ou br. Se você não o definir, o padrão será us (exceto no modo multi-tenant, onde é obrigatório e nunca tem valor padrão).
- Ao usar o canal SMS, você também pode definir a variável de ambiente DEFAULT_SMS_ORIGINATOR para o número de telefone que será usado como remetente para mensagens SMS. Dependendo do seu país, essa configuração pode ser obrigatória.
- Você também pode definir a variável de ambiente GEOCODING_API_KEY para sua chave da API Google Geocoding se quiser usar o recurso de localização. Isso é necessário para converter um endereço em um par de latitude/longitude.
Credenciais da API de Verificação: navegue até a seção Verificação / Aplicativos do painel Sinch Build e crie um novo aplicativo ou selecione um existente. Você precisará das seguintes credenciais:
- (Obrigatório) APPLICATION_KEY
- (Obrigatório) APPLICATION_SECRET
As ferramentas de serviço de voz, chamada, sessão e lote usam PROJECT_ID, KEY_ID e KEY_SECRET das credenciais do projeto acima.
- Opcionalmente, defina CALLING_LINE_IDENTIFICATION para um número Sinch ativo com capacidade de Voz. Ele é usado como origem padrão para tts-callout e tts-batch-callout; os chamadores também podem fornecer a origem para qualquer uma das ferramentas. Se nenhum for definido, as chamadas são feitas sem identificador de chamada.
Credenciais da API Mailgun: navegue até a seção Mailgun / Domínios do painel Mailgun e crie um novo domínio ou selecione um existente. Você precisará das seguintes credenciais:
- (Obrigatório) MAILGUN_API_KEY
- MAILGUN_DOMAIN
- MAILGUN_SENDER_ADDRESS

Configuração do Servidor MCP

O servidor MCP Sinch está disponível como um pacote NPM para ser executado. Veja como configurá-lo no arquivo de configuração do Claude Desktop (claude_desktop_config.json). Lembre-se de preencher as variáveis de ambiente com suas próprias credenciais:

{
  "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": ""
      }
    }
  }
}

Executando o Servidor MCP Localmente

Opção 1: Iniciar o servidor MCP com stdio usando Claude Desktop

Para executar o servidor MCP localmente com Claude Desktop, você precisará clonar o repositório e compilar o servidor MCP. Esta opção é útil para desenvolvimento e testes locais.

Etapa 1: Clonar o repositório

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

Etapa 2: Compilar o servidor MCP

cd sinch-mcp-server
npm install
npm run build

Etapa 3: Configurar o Claude Desktop

Aqui está um exemplo de como configurar o servidor MCP no arquivo de configuração do 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": ""
      }
    }
  }
}

Etapa 4: (Opcional) Filtrar as ferramentas disponíveis no servidor MCP

Muitas ferramentas significam contexto maior, maior uso de tokens e mais confusão para o LLM selecionar a ferramenta certa a ser usada.
Você pode filtrar as ferramentas disponíveis no servidor MCP usando as opções tags. Por exemplo, se você quiser usar apenas as ferramentas de conversa, pode adicionar as seguintes opções ao array args:

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

Você pode combinar várias tags separando-as por vírgulas. Por exemplo, se quiser usar as ferramentas de conversa e verificação, pode usar o seguinte comando:

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

Tags disponíveis: conversation, rcs, whatsapp, email, verification, voice, numbers, notification, configuration, all.

Se quiser usar todas as ferramentas, pode omitir a opção --tags ou usar a tag all:

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

Opção 2: Iniciar o servidor MCP remotamente e conectar-se a ele usando SSE

Com esta opção, você pode executar o servidor MCP em uma máquina remota e conectar-se a ele usando Server-Sent Events (SSE). Isso é útil se você quiser executar o servidor MCP em um servidor em nuvem ou em uma máquina dedicada. Por padrão, o Claude Desktop se conecta ao servidor MCP usando STDIO; usaremos a biblioteca supergateway para conectar ao servidor MCP usando SSE.

Etapa 1: Compilar o servidor MCP

cd sinch-mcp-server
npm install
npm run build

Etapa 2: Configurar o servidor MCP

Copie o arquivo .template.env e renomeie-o para .env. Em seguida, substitua os espaços reservados pelas suas próprias credenciais e exclua qualquer chave que não precise. As variáveis de ambiente são analisadas e tipadas na inicialização do servidor via T3 Env; credenciais ausentes só causam erros quando você invoca uma ferramenta que as exige. O arquivo .env deve ficar assim ():

# 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=

Etapa 3: Iniciar o servidor MCP

npm run start:stdio

Por padrão, este comando iniciará o MCP com todas as ferramentas disponíveis. Se quiser filtrar as ferramentas disponíveis no servidor MCP, pode usar a opção --tags. Por exemplo, se quiser usar apenas as ferramentas de conversa, pode modificar o comando da seguinte forma:

# 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)"

Você pode combinar várias tags separando-as por vírgulas. Por exemplo, se quiser usar as ferramentas de conversa e verificação, pode usar o seguinte 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)"

Etapa 4: Configurar o servidor MCP no Claude Desktop

Você pode então configurar o servidor MCP no arquivo de configuração do Claude da seguinte forma:

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

(Substitua o http://localhost:8000/sse pela URL do seu servidor MCP se ele não estiver rodando localmente)

Opção 3: Servidor HTTP Streamable nativo (recomendado para remoto)

Esta opção executa um servidor MCP HTTP Streamable nativo em /mcp. Ele é single-tenant ou multi-tenant (veja abaixo).

Etapa 1: Compilar o servidor MCP

cd sinch-mcp-server
npm install
npm run build

Etapa 2: Escolher o tipo de locação

A locação é determinada por MCP_AUTH_MODE, que é lido primeiro:

multi-tenant (credenciais do cliente) se MCP_AUTH_MODE for client-credentials
multi-tenant (sinchid-agent) se MCP_AUTH_MODE for sinchid-agent
single-tenant se MCP_AUTH_MODE não estiver definido — PROJECT_ID, KEY_ID e KEY_SECRET são então obrigatórios

`MCP_AUTH_MODE`	Locação	`PROJECT_ID`/`KEY_ID`/`KEY_SECRET`	Ferramentas executadas como
definido para um modo conhecido	Multi-tenant	nunca lido	o que o chamador enviar
definido para qualquer outra coisa	—	—	recusa-se a iniciar
não definido	Single-tenant	obrigatório, todos os três	as credenciais de ambiente do servidor

Como o modo é lido antes de qualquer outra coisa, credenciais deixadas no ambiente não podem silenciosamente reverter um servidor multi-tenant para uma única conta compartilhada — lá, elas não são consultadas de forma alguma, para resolução de credenciais ou para telemetria. Um valor não reconhecido é um erro de inicialização, em vez de um fallback para single-tenant, o que descartaria a autenticação de entrada por completo. Com MCP_AUTH_MODE não definido, um trio parcial também recusa iniciar: defina todos os três, ou nenhum e um modo.

Single-tenant (sem `MCP_AUTH_MODE`)

Use quando todos os clientes desta instância MCP compartilham o mesmo projeto Sinch — na prática, desenvolvimento local. As credenciais ficam no servidor, e todos os três são obrigatórios:

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

Nota: /mcp não realiza autenticação de entrada neste modo. MCP_AUTH_MODE não definido é toda a configuração, portanto não há credencial por chamador para validar e qualquer pessoa que consiga alcançar a porta transaciona nessa conta. Vincule-o a localhost e não o exponha. Para um servidor acessível remotamente, use um modo multi-tenant.

CONVERSATION_REGION permanece opcional aqui (padrão us) e ainda pode ser sobrescrito pelo prompt.

Multi-tenant (`MCP_AUTH_MODE=client-credentials`)

Use quando diferentes clientes precisam usar diferentes projetos Sinch. Cada cliente envia suas próprias credenciais em cada requisição:

Cabeçalho	Valor
`Authorization`	`Bearer <Base64-encoded projectId:keyId:keySecret>`

O servidor não lê PROJECT_ID, KEY_ID ou KEY_SECRET do ambiente neste modo — nem para ferramentas com OAuth, nem para atributos de span. Clientes OAuth são armazenados em cache na memória com evicção LRU (padrão de 256 entradas, configurável via OAUTH_TOKEN_CACHE_MAX_ENTRIES).

Nos modos multi-tenant, CONVERSATION_REGION é obrigatório: o servidor se recusa a iniciar sem ele, e nunca é padronizado para us. Cada implantação é fixada a uma única região, e a região não pode ser sobrescrita por requisição ou pelo prompt.

Como a verificação de formato se comporta

A verificação de formato existe apenas nos modos multi-tenant. Requisições são verificadas contra o formato configurado e rejeitadas com 401 mais um desafio WWW-Authenticate: Bearer caso contrário:

client-credentials exige um token que decodifique para projectId:keyId:keySecret. Um JWT SinchID contém separadores ., portanto nunca decodifica para uma tríade de credenciais e é rejeitado aqui. x-agent-id é ignorado: esta implantação nunca o lê.
sinchid-agent exige um JWT de três segmentos e um cabeçalho x-agent-id — as credenciais são resolvidas a partir da instalação do agente que ele nomeia e o ID do projeto Sinch a partir da claim verificada do token, portanto uma requisição sem ele não pode ser concluída. Uma tríade de credenciais Base64 não é um JWT, então é rejeitada aqui. Apenas ter formato de JWT não é suficiente por si só: o token é então verificado criptograficamente (veja Verificação de token SinchID abaixo) antes que a requisição seja permitida.

Uma requisição sem Authorization algum recebe o desafio somente de realm do RFC 6750 (Bearer realm="sinch-mcp") com o motivo no corpo da resposta; uma requisição carregando o tipo errado de token, ou um JWT que falha na verificação, recebe error="invalid_token" mais uma descrição.

Duas implantações da mesma imagem, cada uma com seu próprio MCP_AUTH_MODE, portanto atendem aos dois públicos em hostnames separados sem que nenhuma aceite as credenciais da outra. MCP_AUTH_MODE não tem efeito sobre stdio.

Verificação de token SinchID (somente `sinchid-agent`)

Cada JWT Authorization de requisição sinchid-agent é verificado contra o JWKS configurado antes que a requisição seja permitida: assinatura (RSA, algoritmo fixado em RS256 — nunca obtido do cabeçalho alg do próprio token), emissor, audiência, expiração (um token sem claim exp também é rejeitado) e claims não vazias de projeto, conta, usuário global e escopo. Um token forjado, expirado, com emissor/audiência errados ou incompleto é rejeitado com 401 e nunca chega à criação de sessão ou execução de ferramenta.

A verificação JWT exige três variáveis de ambiente, todas obrigatórias no modo sinchid-agent — o servidor se recusa a iniciar sem elas:

Variável	Valor
`SINCHID_JWT_ISSUER`	Claim `iss` esperada (ex.: `https://id.sinch.com/`)
`SINCHID_JWT_AUDIENCE`	Claim `aud` esperada
`SINCHID_JWT_JWKS_URI`	URL do documento JWKS do emissor (chaves públicas de assinatura)

A autenticação do Secret Manager usa Credenciais Padrão de Aplicativo do Google. Para desenvolvimento local, execute gcloud auth application-default login; o cliente Google então usa ADC de desenvolvedor sem credencial de variável de ambiente por agente ou fallback. Defina GOOGLE_CLOUD_PROJECT quando o ADC não puder inferir o projeto que possui os segredos. GOOGLE_APPLICATION_CREDENTIALS só é necessário localmente quando um arquivo JSON de conta de serviço é fornecido; aponte-o para o caminho absoluto desse arquivo e nunca o envie para o controle de versão. No Kubernetes, o release do agente monta seu sa-key.json gerenciado pela implantação a partir de um Secret.

O documento JWKS completo é mantido na memória. Requisições HTTP JWKS são abortadas após 3 segundos sem atividade de rede. Após 10 minutos, o servidor tenta atualizar o documento, mas não descarta chaves conhecidas primeiro: se essa atualização agendada falhar, tokens usando uma chave em cache ainda podem ser verificados por até uma hora desde a última busca bem-sucedida. Uma atualização bem-sucedida posterior substitui o documento imediatamente e remove chaves que o emissor não publica mais. Um token cujo ID de chave está ausente pode acionar no máximo uma tentativa de atualização por cooldown de 30 segundos, medido a partir de cada tentativa (incluindo falhas), para que uma interrupção ou uma enxurrada de IDs de chave aleatórios não possa sobrecarregar o endpoint JWKS. Uma chave de assinatura recém-publicada é captada na primeira atualização bem-sucedida após o cooldown. Chaves desconhecidas são rejeitadas com 401 após uma busca JWKS bem-sucedida; 503 é reservado para casos em que uma tentativa de busca não pôde ser concluída ou o último documento bem-sucedido é antigo demais para fallback obsoleto.

As credenciais sinchid-agent são carregadas no momento da requisição a partir da versão mais recente do Google Secret Manager nomeada sinch-agent-m2m_<orderId>_<projectId>. Seu payload é o mesmo blob Base64 projectId:keyId:keySecret usado por client-credentials. orderId vem do cabeçalho x-agent-id, e projectId é derivado da claim https://sinch.com/project_id do token verificado. Ambos os identificadores devem ser UUIDs canônicos e são convertidos para minúsculas ao construir o ID do segredo. O projeto da credencial decodificada deve corresponder ao projeto verificado. Um segredo ausente, inacessível, vazio, malformado, incompatível ou com nome inválido falha de forma fechada com uma resposta de prompt. Este modo nunca recorre a PROJECT_ID, KEY_ID ou KEY_SECRET; essas variáveis permanecem exclusivas do modo single-tenant autônomo.

Formato de credenciais `Authorization` (somente HTTP)

Construa uma string UTF-8: projectId:keyId:keySecret (veja Credenciais de API).
Codifique com Base64 padrão (sem quebras de linha, alfabeto padrão +// — não base64url).
Envie como Authorization: Bearer <base64> em cada requisição HTTP (incluindo após a inicialização da sessão MCP).

O segredo da chave de acesso pode conter caracteres :; apenas os primeiros dois dois-pontos separam os três campos.

Uma requisição cujo cabeçalho Authorization está ausente, usa um esquema diferente de Bearer, ou cujo token não é uma tríade projectId:keyId:keySecret codificada em Base64 não é rejeitada na camada HTTP: ferramentas com OAuth retornam uma resposta de prompt declarando Missing or invalid Authorization header (expected "Bearer <Base64 of projectId:keyId:keySecret>").

Exemplo (multi-tenant):

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

Escopo: as credenciais Authorization se aplicam às ferramentas Conversation, Numbers e Number Lookup. Voice, Verification e Mailgun ainda usam variáveis de ambiente do servidor por enquanto. Stdio local (Opção 1) sempre usa variáveis de ambiente do servidor.

Cabeçalho `x-agent-id` (somente `sinchid-agent`)

Integrações de agente (ex.: um agente instalado em um aplicativo Gemini Enterprise) enviam um cabeçalho x-agent-id carregando o identificador único de instalação (o OrderId do Marketplace). O ID do projeto Sinch é derivado da claim https://sinch.com/project_id verificada no JWT Authorization. Juntos, eles nomeiam qual segredo do Google Secret Manager (sinch-agent-m2m_<orderId>_<projectId>) o servidor resolve as credenciais Sinch do chamador. O cabeçalho x-agent-id é obrigatório em implantações executando com MCP_AUTH_MODE=sinchid-agent; uma requisição sem ele é rejeitada com 401 antes de chegar a uma ferramenta. Em outros lugares, ele simplesmente não é lido — os outros modos o ignoram, e via stdio as credenciais sempre vêm do ambiente. Este cabeçalho personalizado é um mecanismo temporário até que uma capacidade de troca de token esteja disponível via autenticação M2M.

Cabeçalho	Valor
`x-agent-id`	Identificador de instalação do agente (ex.: GE `OrderId`)

JWT de usuário `Authorization` (implantações de agente)

Após o usuário final concluir o fluxo de login e consentimento OAuth, integrações de agente podem enviar o JWT de usuário Auth0 resultante em cada requisição:

Cabeçalho	Valor
`Authorization`	`Bearer <user JWT>`

Uma vez que o token tenha passado na verificação (veja Verificação de token SinchID acima), o servidor captura as claims Sinch (https://sinch.com/project_id, https://sinch.com/account_id, https://sinch.com/global_user_id) e a claim padrão scope no contexto da requisição, registrando-as para fins de auditoria. A claim https://sinch.com/project_id verificada é pareada com x-agent-id para resolver credenciais de API M2M do Secret Manager (sinch-agent-m2m_<orderId>_<projectId>). Single-tenant não lê Authorization; nos modos multi-tenant, o token deve corresponder ao formato da implantação e passar na verificação, ou a requisição é rejeitada com 401. No longo prazo, o JWT de usuário será trocado por um JWT M2M, substituindo os cabeçalhos personalizados.

O que o token Authorization é depende da implantação:

Implantação	Token Bearer	Credenciais Sinch vêm de
Single-tenant	não lido e não obrigatório	`PROJECT_ID`/`KEY_ID`/`KEY_SECRET` do servidor
Multi-tenant, `client-credentials`	Base64 `projectId:keyId:keySecret`	o próprio token
Multi-tenant, `sinchid-agent`	Token de acesso SinchID (JWT de três segmentos)	a instalação do agente (Google Secret Manager)

Os dois formatos multi-tenant são disjuntos: um JWT contém separadores ., que não estão no alfabeto Base64, então uma tríade de credenciais nunca é lida como token e um JWT nunca resolve para credenciais. Cada implantação multi-tenant aceita apenas seu próprio formato e responde 401 ao outro — veja MCP_AUTH_MODE.

Como uma requisição carrega um único cabeçalho Authorization, as claims de auditoria descritas acima são capturadas apenas onde o token é um JWT — ou seja, em uma implantação sinchid-agent. Um chamador client-credentials fornece credenciais em vez de um token de usuário, então nenhuma claim é registrada para ele.

Etapa 3: Iniciar o servidor HTTP

npm run start:http:server

O servidor escuta em http://localhost:8000/mcp por padrão (sobrescreva com PORT).

Armazenamento de sessão (Redis)

A identidade da sessão é armazenada no Redis, não na memória do processo, para que qualquer pod atrás de um balanceador de carga possa validar qualquer sessão — sem necessidade de sessões fixas. Cada requisição constrói seu próprio McpServer e StreamableHTTPServerTransport de curta duração, fechados quando a resposta termina; nada é mantido na memória entre requisições. O Redis é obrigatório — o servidor sai imediatamente na inicialização a menos que tanto REDIS_HOST quanto REDIS_PORT estejam definidos (REDIS_PASSWORD é opcional; TLS é ativado automaticamente quando definido, ex.: para AWS ElastiCache). Se o Redis estiver inacessível após uma breve tentativa, o servidor retorna 503 Service Unavailable com código de erro JSON-RPC -32003, distinto de -32001 Session not found. Como não há transporte persistente por sessão, o servidor não suporta o stream GET/SSE independente — GET /mcp retorna 405. Notificações iniciadas pelo servidor enviadas durante um POST (ex.: progresso de ferramenta) funcionam normalmente; uma notificação enviada independentemente de qualquer requisição não teria para onde ir, já que os transportes são por requisição.

Etapa 4: Exemplo de configuração de cliente MCP

Cada modo envia o mesmo formato de cabeçalho — o que difere é de quem são as credenciais que o token carrega. Clientes de locatário único codificam a tríade do servidor; clientes de múltiplos locatários codificam as suas próprias.

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

Após a resposta initialize, inclua o cabeçalho mcp-session-id retornado pelo servidor nas requisições subsequentes.

Contribuindo

Consulte CONTRIBUTING.md para as diretrizes de contribuição, incluindo como adicionar novas ferramentas e fixar GitHub Actions.

Sinch

Documentação

Servidor MCP Sinch — Prévia para Desenvolvedores

Visão Geral das Ferramentas

Ferramentas de Conversa

Ferramentas de E-mail (Mailgun)

Ferramentas de Verificação

Ferramentas de Voz

Hierarquia de lote, sessão e chamada de voz

Ferramentas de Remetentes RCS

Ferramentas do WhatsApp

Ferramentas de Números

Ferramentas de Configuração

Primeiros Passos

Pré-requisitos

Credenciais da API

Configuração do Servidor MCP

Executando o Servidor MCP Localmente

Opção 1: Iniciar o servidor MCP com stdio usando Claude Desktop

Etapa 1: Clonar o repositório

Etapa 2: Compilar o servidor MCP

Etapa 3: Configurar o Claude Desktop

Etapa 4: (Opcional) Filtrar as ferramentas disponíveis no servidor MCP

Opção 2: Iniciar o servidor MCP remotamente e conectar-se a ele usando SSE

Etapa 1: Compilar o servidor MCP

Etapa 2: Configurar o servidor MCP

Etapa 3: Iniciar o servidor MCP

Etapa 4: Configurar o servidor MCP no Claude Desktop

Opção 3: Servidor HTTP Streamable nativo (recomendado para remoto)

Etapa 1: Compilar o servidor MCP

Etapa 2: Escolher o tipo de locação

Single-tenant (sem MCP_AUTH_MODE)

Multi-tenant (MCP_AUTH_MODE=client-credentials)

Como a verificação de formato se comporta

Verificação de token SinchID (somente sinchid-agent)

Formato de credenciais Authorization (somente HTTP)

Cabeçalho x-agent-id (somente sinchid-agent)

JWT de usuário Authorization (implantações de agente)

Etapa 3: Iniciar o servidor HTTP

Armazenamento de sessão (Redis)

Etapa 4: Exemplo de configuração de cliente MCP

Contribuindo

Single-tenant (sem `MCP_AUTH_MODE`)

Multi-tenant (`MCP_AUTH_MODE=client-credentials`)

Verificação de token SinchID (somente `sinchid-agent`)

Formato de credenciais `Authorization` (somente HTTP)

Cabeçalho `x-agent-id` (somente `sinchid-agent`)

JWT de usuário `Authorization` (implantações de agente)