Sinch MCP Server — Developer Preview

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 the Claude Desktop client, but it can also be used with any other MCP client.

Tools Overview

Here is the list of tools available in the MCP server (all the phone numbers must be provided in E.164 format, e.g., `+33612345678` for France).

Conversation Tools

Email tools (Mailgun)

Verification Tools

Voice Tools

RCS Sender Tools

WhatsApp Tools

Numbers Tools

Configuration Tools

Getting Started

Prerequisites

• Node.js 20.x or 22.x (LTS)
• A provisioned Sinch Build account
• Claude Desktop (or any other MCP client). This README is focused on Claude Desktop, but the MCP server can be used with any MCP client.

API credentials

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. Contact si-richmessaging@sinch.com to activate it. Once enabled, RCS uses the same `PROJECT_ID`, `KEY_ID`, and `KEY_SECRET` as the Conversation API (see below).

• WhatsApp Template API credentials: uses the same `PROJECT_ID`, `KEY_ID`, and `KEY_SECRET` as the Conversation API (see below).

• Conversation / Numbers API credentials:
  • (Required) `PROJECT_ID`: Select the project you want to use from your Sinch Build dashboard (Located at the left of the top toolbar)

• Verification API credentials: navigate to the Verification / Apps section of 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 the Voice / Apps section of 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 the `CALLING_LINE_IDENTIFICATION` environment variable to the phone number that will be displayed to the user when they receive a call.
• Mailgun API credentials: navigate to the Mailgun / Domains section of 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`

MCP Server Configuration

The Sinch MCP server is available as an NPM package to the executed. Here is how to set it up in the Claude Desktop configuration 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": ""
      }
    }
  }
}

Running the MCP Server locally

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.

Step 1: Clone the repository

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

Step 2: Build the MCP server

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 the Claude Desktop configuration 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 the `tags` options. For example, if you want to only use the conversation tools, you can add the following options to the `args` array:

"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 `--tags` option, or use the tag `all`:

"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 the supergateway library to connect to the MCP server using SSE.

Step 1: Build the MCP server

cd sinch-mcp-server
npm install
npm run build

Step 2: Set up the MCP server configuration

Copy the file `.template.env` and 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 via T3 Env; missing credentials only cause errors when you invoke a tool that requires them. The `.env` file 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=

Step 3: Start the MCP server

npm run start:stdio

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 `--tags` option. 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 the `http://localhost:8000/sse` with the URL of your MCP server if it is not running locally)

Option 3: Native Streamable HTTP server (recommended for remote)

This option runs a native Streamable HTTP MCP server on `/mcp`. Choose single-tenant or multi-tenant deployment — they are mutually exclusive.

Step 1: Build the MCP server

cd sinch-mcp-server
npm install
npm run build

Step 2: Choose a deployment mode

Single-tenant (one Sinch account per server)

Use when every client of this MCP instance shares the same Sinch project. Configure credentials on 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 send one header on every request:

`MCP_API_KEY` (or comma-separated `MCP_API_KEYS` for key rotation) authorizes access to the MCP server. `PROJECT_ID`, `KEY_ID`, and `KEY_SECRET` are read from the server environment only — `X-Sinch-Credentials` is ignored in 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 set `MCP_API_KEY` on the server. Each client sends its own credentials on every request.

Remote clients send one header on every request:

The server does not read `PROJECT_ID`, `KEY_ID`, or `KEY_SECRET` from its environment for OAuth-backed tools in this mode. OAuth clients are cached in memory with LRU eviction (default 256 entries, configurable via `OAUTH_TOKEN_CACHE_MAX_ENTRIES`).

In multi-tenant mode, `CONVERSATION_REGION` is required: the server refuses to start without it, and it is never defaulted to `us`. Each deployment is pinned to a single region, and the region cannot be overridden per request or from the prompt.

`X-Sinch-Credentials` format (multi-tenant only)

1. Build a UTF-8 string: `projectId:keyId:keySecret` (see API credentials).

2. Encode with standard Base64 (no line breaks).

3. Send on each HTTP request (including after MCP session initialization).

The access key secret may contain `:` characters; only the first two colons separate the three fields.

Example (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 "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-Credentials` applies to Conversation, Numbers, and Number Lookup tools. Voice, Verification, and Mailgun still use server environment variables for now. Local stdio (Option 1) always uses server environment variables.

`x-agent-id` header (multi-tenant only)

Agent integrations (e.g. an agent installed in a Gemini Enterprise app) may send an `x-agent-id` header carrying the unique installation identifier (the Marketplace OrderId). Its purpose is to distinguish which installation is calling the MCP server, so it is meant for multi-tenant deployments 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.

`Authorization` user JWT (optional)

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/global_user_id`) and the standard `scope` claim in the request context, logging them for audit purposes only. The token signature is not verified and the claims are never used to resolve API credentials (the `x-agent-id` header 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: in single-tenant mode the `Authorization` header carries the MCP API key instead; an opaque key is not a JWT, so no claims are captured.

MCP_API_KEYS key rotation

Use `MCP_API_KEYS` (comma-separated) in single-tenant mode to accept an old and new gateway key during rotation, then remove the retired key.

Step 3: Start the HTTP server

npm run start:http:server

The server listens on `http://localhost:8000/mcp` by default (override with `PORT`).

Session storage (Redis)

Session identity is stored in Redis, not in process memory, so any pod behind a load balancer can validate any session — no sticky sessions required. Each request builds its own short-lived `McpServer` and `StreamableHTTPServerTransport`, closed once the response finishes; nothing is held in memory between requests. Redis is required — the server exits immediately on startup unless both `REDIS_HOST` and `REDIS_PORT` are set (`REDIS_PASSWORD` is optional; TLS turns on automatically once it's set, e.g. for AWS ElastiCache). If Redis is unreachable after a short retry, the server returns 503 Service Unavailable with JSON-RPC error code `-32003`, distinct from `-32001 Session not found`.

Because there's no persistent per-session transport, the server doesn't support the standalone GET/SSE stream — `GET /mcp` returns 405. Server-initiated notifications sent during a POST (e.g. tool progress) work as usual; a notification pushed independently of any request would have nowhere to go once transports are per-request.

Step 4: Example MCP client configuration

Single-tenant:

{
  "mcpServers": {
    "sinch-remote": {
      "url": "https://your-host.example.com/mcp",
      "headers": {
        "Authorization": "Bearer "
      }
    }
  }
}

Multi-tenant:

{
  "mcpServers": {
    "sinch-remote": {
      "url": "https://your-host.example.com/mcp",
      "headers": {
        "X-Sinch-Credentials": ""
      }
    }
  }
}

After the `initialize` response, include the `mcp-session-id` header returned by the server on subsequent requests.

Contributing

See CONTRIBUTING.md for contributor guidelines, including how to add new tools and pin GitHub Actions.