Sinch MCP Server
About
Sinch provides a global, scalable, secure platform for businesses to communicate with their customers - for messaging, voice, verification and email. These communication capabilities are vital for anyone building customer-connected solutions with AI systems.
Details
- Author
- sinch
- Downloads
- 448
- Categories
- Communication, Productivity
Jump to
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Sinch MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install the Sinch MCP Server
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"sinch mcp server": {
"sinch": {
"command": "node",
"args": [
"/your/path/to/sinch-mcp-server/mcp/dist/index.js"
],
"env": {
"CONVERSATION_PROJECT_ID": "",
"CONVERSATION_KEY_ID": "",
"CONVERSATION_KEY_SECRET": "",
"CONVERSATION_APP_ID": "",
"CONVERSATION_REGION": "",
"DEFAULT_SMS_ORIGINATOR": "",
"GEOCODING_API_KEY": "",
"VERIFICATION_APPLICATION_KEY": "",
"VERIFICATION_APPLICATION_SECRET": "",
"VOICE_APPLICATION_KEY": "",
"VOICE_APPLICATION_SECRET": "",
"CALLING_LINE_IDENTIFICATION": "",
"MAILGUN_API_KEY": "",
"MAILGUN_DOMAIN": "",
"MAILGUN_SENDER_ADDRESS": ""
}
}
}
}
}McpServers
{
"sinch": {
"command": "node",
"args": [
"/your/path/to/sinch-mcp-server/mcp/dist/index.js"
],
"env": {
"CONVERSATION_PROJECT_ID": "",
"CONVERSATION_KEY_ID": "",
"CONVERSATION_KEY_SECRET": "",
"CONVERSATION_APP_ID": "",
"CONVERSATION_REGION": "",
"DEFAULT_SMS_ORIGINATOR": "",
"GEOCODING_API_KEY": "",
"VERIFICATION_APPLICATION_KEY": "",
"VERIFICATION_APPLICATION_SECRET": "",
"VOICE_APPLICATION_KEY": "",
"VOICE_APPLICATION_SECRET": "",
"CALLING_LINE_IDENTIFICATION": "",
"MAILGUN_API_KEY": "",
"MAILGUN_DOMAIN": "",
"MAILGUN_SENDER_ADDRESS": ""
}
}
}This repository contains the source code for the Sinch MCP server, which provides a set of tools to interact with the Sinch APIs. This README focuses on using the MCP server with theClaude Desktopclient, but it can also be used with any other MCP client.
Here is the list of tools available in the MCP server (all the phone numbers must be provided in E.164 format, e.g.,+33612345678for France).
- Node.js 20.x or 22.x (LTS)
- A provisionedSinch Build account
- Claude Desktop (or any other MCP client). This README is focused onClaude Desktop, but the MCP server can be used with any MCP client.
To use the APIs used by the MCP tools, you will need the following credentials:
-
RCS API credentials: RCS must be enabled for your Sinch project. Contactsi-richmessaging@sinch.comto activate it. Once enabled, RCS uses the samePROJECT_ID,KEY_ID, andKEY_SECRETas the Conversation API (see below).
WhatsApp Template API credentials: uses the samePROJECT_ID,KEY_ID, andKEY_SECRETas the Conversation API (see below).
- (Required)PROJECT_ID: Select the project you want to use from yourSinch Build dashboard(Located at the left of the top toolbar)
- (Required)KEY_ID: Select or create a new access key in theAccess keys sectionof the Sinch Build dashboard.
- (Required)KEY_SECRET: This is the secret associated with theAccess Keyyou selected or created in the previous step. Be careful, theAccess Key Secretis only shown once when you create theAccess Key. If you lose it, you will need to create a newAccess Key.
- CONVERSATION_APP_ID: This is the ID of the conversation app you want to use. You can find it in theConversation API / Apps sectionof the Sinch Build dashboard. If you don't set it, you will have to specify it in the prompt.
- CONVERSATION_REGION: This is the region where your conversation app and templates are located. It can beus,eu, orbr. If you don't set it, it defaults tous(except inmulti-tenant mode, where it is required and never defaulted).
- When using the SMS channel, you can also set theDEFAULT_SMS_ORIGINATORenvironment variable to the phone number that will be used as the sender for SMS messages. Depending on your country, this setting may be required.
- You can also set theGEOCODING_API_KEYenvironment variable to your Google Geocoding API key if you want to use the location feature. This is needed to convert an address to a latitude/longitude pair.
Verification API credentials: navigate to theVerification / Apps sectionof the Sinch Build dashboard and create a new app or select an existing one. You will need the following credentials:
- (Required)APPLICATION_KEY
- (Required)APPLICATION_SECRET
Voice API credentials: navigate to theVoice / Apps sectionof the Sinch Build dashboard and create a new app or select an existing one. You will need the following credentials:
- (Required)APPLICATION_KEY
- (Required)APPLICATION_SECRET
- You can also set theCALLING_LINE_IDENTIFICATIONenvironment variable to the phone number that will be displayed to the user when they receive a call.
Mailgun API credentials: navigate to theMailgun / Domains sectionof the Mailgun dashboard and create a new domain or select an existing one. You will need the following credentials:
- (Required)MAILGUN_API_KEY
- MAILGUN_DOMAIN
- MAILGUN_SENDER_ADDRESS
The Sinch MCP server is available as an NPM package to the executed. Here is how to set it up in theClaude Desktopconfiguration file (claude_desktop_config.json). Remember to fill in the environment variables with your own credentials:
{ "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": "" } } } }
Option 1: Start the MCP server with stdio using Claude Desktop
To run the MCP server locally with Claude Desktop, you will need to clone the repository and build the MCP server. This option is useful for local development and testing.
git clone https://github.com/sinch/sinch-mcp-server.git
cd sinch-mcp-server npm install npm run build
Step 3: Setup Claude Desktop configuration
Here is an example of how to configure the MCP server in theClaude Desktopconfiguration file (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": "" } } } }
Step 4: (Optional) Filter the tools available in the MCP server
Too many tools mean bigger context, mean higher tokens usage and more confusion for the LLM to select the right tool to use.
You can filter the tools that are available in the MCP server by using thetagsoptions. For example, if you want to only use the conversation tools, you can add the following options to theargsarray:
"args": [ "/your/path/to/sinch-mcp-server/dist/index.js", "--tags", "conversation" ],
You can combine multiple tags by separating them with commas. For example, if you want to use both conversation and verification tools, you can use the following command:
"args": [ "/your/path/to/sinch-mcp-server/dist/index.js", "--tags", "conversation,verification" ],
Available tags:conversation,rcs,whatsapp,email,verification,voice,numbers,notification,configuration,all.
If you want to use all the tools, you can omit the--tagsoption, or use the tagall:
"args": [ "/your/path/to/sinch-mcp-server/dist/index.js", "--tags", "all" ],
Option 2: Start the MCP server remotely and connect to it using SSE
With this option, you can run the MCP server on a remote machine and connect to it using Server-Sent Events (SSE). This is useful if you want to run the MCP server on a cloud server or a dedicated machine. By default, Claude Desktop will connect to the MCP server using STDIO; we will use thesupergateway libraryto connect to the MCP server using SSE.
cd sinch-mcp-server npm install npm run build
Step 2: Set up the MCP server configuration
Copy the file.template.envand rename it.env. Then replace the placeholders with your own credentials and delete any key you don't need. Environment variables are parsed and typed at server startup viaT3 Env; missing credentials only cause errors when you invoke a tool that requires them. The.envfile should look like this ():
# Conversation / Numbers 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 / Voice tools related environment variables APPLICATION_KEY= APPLICATION_SECRET= ## Needed only if you want to make calls: it is the number that will be displayed to the user when they receive a call CALLING_LINE_IDENTIFICATION= # Mailgun tools related environment variables MAILGUN_DOMAIN= MAILGUN_API_KEY= MAILGUN_SENDER_ADDRESS=
By default, this command will start the MCP with all the tools available. If you want to filter the tools that are available in the MCP server, you can use the--tagsoption. For example, if you want to only use the conversation tools, you can modify the command as follows:
# 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)"
You can combine multiple tags by separating them with commas. For example, if you want to use both conversation and verification tools, you can use the following command:
"start": "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)"
Step 4: Configure the MCP server in Claude Desktop
You can then configure the MCP server in the Claude configuration file as follows:
{ "mcpServers": { "sinch": { "command": "npx", "args": ["-y", "supergateway", "--sse", "http://localhost:8000/sse"] } } }
(Replace thehttp://localhost:8000/ssewith the URL of your MCP server if it is not running locally)
Option 3: Native Streamable HTTP server (recommended for remote)
This option runs anative Streamable HTTPMCP server on/mcp. Choosesingle-tenantormulti-tenantdeployment — they are mutually exclusive.
cd sinch-mcp-server npm install npm run build
Single-tenant (one Sinch account per server)
Use when every client of this MCP instance shares the same Sinch project. Configure credentialson the server; clients only authenticate to the MCP gateway.
MCP_API_KEY=your-secret-mcp-api-key PORT=8000 PROJECT_ID= KEY_ID= KEY_SECRET=
Remote clients sendone headeron every request:
MCP_API_KEY(or comma-separatedMCP_API_KEYSforkey rotation) authorizes access to the MCP server.PROJECT_ID,KEY_ID, andKEY_SECRETare read from the server environment only —X-Sinch-Credentialsis ignoredin this mode (no client override of server credentials).
Multi-tenant (each client brings a Sinch account)
Use when different clients must use different Sinch projects.Do not setMCP_API_KEYon the server. Each client sends its own credentials on every request.
Remote clients sendone headeron every request:
The server doesnotreadPROJECT_ID,KEY_ID, orKEY_SECRETfrom its environment for OAuth-backed tools in this mode. OAuth clients are cached in memory withLRU eviction(default 256 entries, configurable viaOAUTH_TOKEN_CACHE_MAX_ENTRIES).
In multi-tenant mode,CONVERSATION_REGIONisrequired: the server refuses to start without it, and it is never defaulted tous. Each deployment is pinned to a single region, and the region cannot be overridden per request or from the prompt.
X-Sinch-Credentialsformat (multi-tenant only)
- Build a UTF-8 string:projectId:keyId:keySecret(seeAPI credentials).
- Encode withstandard Base64(no line breaks).
- Send oneachHTTP request (including after MCP session initialization).
The access key secret may contain:characters; only thefirst twocolons separate the three fields.
export SINCH_CREDS=$(printf '%s' 'my-project-id:my-key-id:my-key-secret' | base64) curl -X POST "http://localhost:8000/mcp" \ -H "X-Sinch-Credentials: ${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"}}}'
Scope:X-Sinch-Credentialsapplies toConversation,Numbers, andNumber Lookuptools.Voice,Verification, andMailgunstill use server environment variables for now.Local stdio(Option 1) always uses server environment variables.
Agent integrations (e.g. an agent installed in a Gemini Enterprise app) may send anx-agent-idheader carrying the unique installation identifier (the MarketplaceOrderId). Its purpose is to distinguish which installation is calling the MCP server, so it is meant formulti-tenantdeployments only: it will be used to resolve the caller's Sinch credentials in an upcoming release. In single-tenant mode credentials always come from the server environment, so the header serves no purpose there. This custom header is a temporary mechanism until a token-exchange capability is available over M2M authentication.
After the end-user completes the OAuth login and consent flow, agent integrations may send the resulting Auth0 user JWT on each request:
The server base64-decodes the JWT payload and captures the Sinch claims (https://sinch.com/project_id,https://sinch.com/account_id,https://sinch.com/email,https://sinch.com/global_user_id, andsub) in the request context, logging them foraudit purposes only. The token signature isnotverified and the claims are never used to resolve API credentials (thex-agent-idheader serves that purpose). A missing or malformed token is ignored and the request proceeds normally. In the long term, the user JWT will be exchanged for an M2M JWT, replacing the custom headers.
Note: insingle-tenantmode theAuthorizationheader carries the MCP API key instead; an opaque key is not a JWT, so no claims are captured.
UseMCP_API_KEYS(comma-separated) insingle-tenantmode to accept an old and new gateway key during rotation, then remove the retired key.
The server listens onhttp://localhost:8000/mcpby default (override withPORT).
Each MCP client session creates an in-memoryMcpServerinstance (all registered tools) plus aStreamableHTTPServerTransport. To avoid unbounded memory growth, the server capsconcurrent sessionsat256by default (MCP_MAX_SESSIONS). When the limit is reached, newinitializerequests receive503 Service Unavailableuntil a client closes a session (DELETE /mcpwithmcp-session-id) or the transport is torn down.
Step 4: Example MCP client configuration
{ "mcpServers": { "sinch-remote": { "url": "https://your-host.example.com/mcp", "headers": { "Authorization": "Bearer <MCP_API_KEY>" } } } }
{ "mcpServers": { "sinch-remote": { "url": "https://your-host.example.com/mcp", "headers": { "X-Sinch-Credentials": "<base64(projectId:keyId:keySecret)>" } } } }
After theinitializeresponse, include themcp-session-idheader returned by the server on subsequent requests.
See
CONTRIBUTING.mdfor contributor guidelines, including how to add new tools and pin GitHub Actions.Manage your WhatsApp, SMS and Phone Calls using a single MCP connector
Connect to any function, any language, across network boundaries using AgentRPC.
Access your meeting transcripts, summaries, and action items from any AI assistant.
Connect Claude, ChatGPT, and other AI tools to your Granola meeting notes via MCP. Query your notes, search transcripts, and get meeting insights in your favorite AI assistants.
Build with the Kudosity API to send SMS and MMS. Access developer docs, API references and live testing tools to send messages, manage contact lists, configure webhooks and more.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
