Sinch MCP Server

Sinch MCP サーバー — 開発者プレビュー

このリポジトリには、Sinch API と連携するための一連のツールを提供する Sinch MCP サーバーのソースコードが含まれています。この README では、主に Claude Desktop クライアントで MCP サーバーを使用する方法を説明しますが、ほかの MCP クライアントでも使用できます。

ツールの概要

以下は、MCP サーバーで利用できるツールの一覧です（電話番号はすべて E.164 形式で指定する必要があります。たとえば、フランスの場合は +33612345678 です）。

会話ツール

Tool	Description	Tags
send-text-message	対応しているチャネルで、宛先にプレーンテキストメッセージを送信します。 プロンプトの例:「SMSで電話番号 +33612345678 に簡単な最新情報を送信してください。」	会話、通知
send-media-message	メディアメッセージで画像、動画、またはドキュメントを送信します。 プロンプトの例:「WhatsAppで電話番号 +33612345678 に製品パンフレットのPDFを送信してください。」	会話、通知
send-template-message	定義済みのテンプレート（omni-templateのみ）を使用してメッセージを送信します。 プロンプトの例:「Messengerでこのユーザーにスペイン語の予約リマインダーテンプレートを送信してください。」	会話、通知
send-whatsapp-template-message	定義済みのWhatsAppテンプレートを使用してメッセージを送信します。 プロンプトの例:「WhatsAppでテンプレート "appointment-reminder" を使用してメッセージを送信してください。」	会話、通知
send-choice-message	インタラクティブな選択肢（ボタンまたはクイック返信）を含むメッセージを送信します。 プロンプトの例:「電話番号 +33612345678 に、次の選択肢を含む、好みのアイスクリームの味についてのRCSアンケートを送信してください：バニラ、ストロベリー、ヘーゼルナッツ。」	会話、通知
send-location-message	ユーザーに位置情報のピンまたは座標を送信します。 プロンプトの例:「ビルバオのグッゲンハイム美術館の場所を示すピンを、電話番号 +33612345678 に送信してください。」	会話、通知
list-conversation-apps	Sinchアカウントで設定されているすべてのConversationアプリを一覧表示します。 プロンプトの例:「アカウントにはどのメッセージングアプリが設定されていますか？」	会話、通知
create-conversation-app	新しいConversation APIアプリを作成します（作成時にチャネルは不要です）。 プロンプトの例:「EUリージョンにMy Support Botという名前のConversationアプリを作成してください。」	会話、設定
update-conversation-app	Conversation APIアプリの表示名を更新します。 プロンプトの例:「Conversationアプリabc123の名前をMy Support Botに変更してください。」	会話、設定
delete-conversation-app	IDを指定してConversation APIアプリを削除します。 プロンプトの例:「Conversationアプリabc123を削除してください。」	会話、設定
set-sms-channel-on-app	ConversationアプリのSMSチャネルを設定（作成または置換）します。 プロンプトの例:「サービスプランXYZとAPIトークン…を使用して、アプリabc123にSMSを設定してください。」	会話、設定
set-rcs-channel-on-app	ConversationアプリのRCSチャネルを設定（作成または置換）します。 プロンプトの例:「送信者ID…とベアラートークン…を使用して、アプリabc123にRCSを設定してください。」	会話、設定
set-whatsapp-channel-on-app	ConversationアプリのWhatsAppチャネルを設定（作成または置換）します。 プロンプトの例:「送信者ID…とベアラートークン…を使用して、アプリabc123にWhatsAppを設定してください。」	会話、設定
list-messaging-templates	設定済みリージョンのオムニチャネルメッセージテンプレート（Sinchが管理）を一覧表示します。WhatsApp専用テンプレートは list-whatsapp-templates ツールで取得できます。 プロンプトの例:「アカウントにあるすべてのメッセージテンプレートを表示してください。」	会話、通知
list-webhooks	Conversationアプリに設定されているWebhookを一覧表示します。 プロンプトの例:「ConversationアプリのすべてのWebhookを一覧表示してください。」	会話、設定
get-webhook	IDを指定してWebhookを取得します。 プロンプトの例:「Webhook ID abc123の詳細を表示してください。」	会話、設定
create-webhook	Conversation APIのイベントを指定したURLに配信するWebhookを作成します。 プロンプトの例:「https://example.com/callback に受信メッセージ用のWebhookを作成してください。」	会話、設定
update-webhook	Webhookの配信先URLやトリガーを更新します。 プロンプトの例:「Webhook abc123がMESSAGE_DELIVERYイベントも受信するように更新してください。」	会話、設定
delete-webhook	IDを指定してWebhookを削除します。 プロンプトの例:「Webhook abc123を削除してください。」	会話、設定

メールツール（Mailgun）

ツール	説明	タグ
send-email	定義済みの HTML テンプレート、または HTML／テキストの生コンテンツを使用してメールを送信します。 プロンプトの例：「[email protected] にオンボーディング用テンプレートを使ってウェルカムメールを送信してください。」	メール、通知
list-email-templates	特定のドメインで利用可能なすべてのメールテンプレートを一覧表示します。 プロンプトの例：「利用できるメールテンプレートを教えてください。」	メール、通知
retrieve-email-info	特定のメールメッセージのメタデータ、コンテンツ、配信状況を取得します。 プロンプトの例：「ID が のメールの配信状況を確認できますか？」	メール、通知
list-email-events	バウンス、開封、クリックなど、最近のメール配信イベントを取得して分類します。 プロンプトの例：「アカウントの最近のメールアクティビティをすべて表示してください。」	メール
analytics-metrics	開封率やクリック率などのメール分析指標を取得します。 プロンプトの例：「先週の開封率を教えてください。」	メール

認証ツール

ツール	説明	タグ
number-lookup	電話番号のステータスと機能を照会します。 プロンプトの例：「次の電話番号の機能を照会してください：+33501020304。」	認証
start-sms-verification	ユーザーの電話番号に OTP を送信して、SMS 認証を開始します。 プロンプトの例：「番号 +33612345678 の電話番号認証を開始してください。」	認証
report-sms-verification	ワンタイムパスワード（OTP）を送信して、SMS 認証を完了します。 プロンプトの例：「このコードで電話番号を認証してください：1234。」	認証

音声ツール

ツール	説明	タグ
tts-callout	音声通話を発信し、テキスト読み上げを使ってメッセージを読み上げます。 プロンプトの例: 「電話番号 +33612345678 に電話して、『ご予約は明日の午前10時です』と伝えてください。」	voice, notification
get-call-information	ID を使って通話の情報を取得します。 プロンプトの例: 「通話 ID abc123 の詳細を取得してください。」	voice, notification
list-calls	サービス、エンドポイント、期間、種類、結果、理由で通話を一覧表示および絞り込みます。 プロンプトの例: 「今日完了した通話を一覧表示してください。」	voice, notification
get-session-information	セッション ID を使って音声セッションとそのすべての通話レッグを取得します。 プロンプトの例: 「セッション 01BX5ZZKBKACTAV9WEVGEMMVRB の詳細を取得してください。」	voice, notification
create-voice-service	Voice サービスを作成します。 プロンプトの例: 「Customer Support という名前でデフォルトの Voice サービスを作成してください。」	voice
set-voice-service-webhook	Voice サービスのプライマリ Webhook とフォールバック URL を設定します。 プロンプトの例: 「サービス 6e124178-c29d-46a5-943c-5c2ae544aade の Webhook とフォールバックを設定してください。」	voice
remove-voice-service-webhook	Voice サービスの Webhook 処理を削除します。 プロンプトの例: 「サービス 6e124178-c29d-46a5-943c-5c2ae544aade の Webhook を削除してください。」	voice
assign-number-to-voice-service	有効な Sinch 番号を Voice サービスに割り当てます。 プロンプトの例: 「+14155550100 を Voice サービス 6e124178-c29d-46a5-943c-5c2ae544aade に割り当ててください。」	voice
tts-batch-callout	同じテキスト読み上げメッセージを再生する一括発信を開始します。 プロンプトの例: 「これらの番号に一括で電話して、このリマインダーを読み上げてください。」	voice, notification
get-voice-batch-summary	バッチ実行の合計を取得し、必要に応じて各セッションの状態も取得します。 プロンプトの例: 「バッチ 01BX5ZZKBKACTAV9WEVGEMMVRB の概要とセッションの詳細を取得してください。」	voice, notification

音声バッチ、セッション、通話の階層

• バッチは、複数の宛先への発信を開始する非同期リクエストをまとめたものです。tts-batch-callout はバッチ ID を返し、宛先ごとに独自のセッションが生成されます。
• セッションは1つの通話フローを表し、1つ以上の通話を含みます。tts-callout はセッション ID を直接返します。get-session-information を使って通話レッグを取得します。
• 通話はセッション内の個々のレッグで、通話 ID で識別されます。特定のレッグの状態や詳細が必要な場合は、get-call-information を使います。

バッチを上から順に確認するには、セッション詳細を有効にして get-voice-batch-summary を使い、返されたセッション ID を get-session-information に渡し、さらに返された通話 ID を get-call-information に渡します。

RCS Sender Tools

Tool	Description	Tags
list-rcs-senders	プロジェクトのすべてのRCS送信者を、ページネーションに対応して一覧表示します。 使用例:「RCS送信者をすべて表示してください。」	rcs, configuration
get-rcs-sender	IDでRCS送信者の詳細を取得します。認証情報、状態、ブランドの詳細、テスト番号、国のステータスが含まれます。 使用例:「RCS送信者abc123の詳細を取得してください。」	rcs, configuration
create-rcs-sender	新しいRCS送信者を作成します。ブランドの詳細、アンケート、国は、作成時に指定することも、update-rcs-senderで段階的に追加することもできます。 使用例:「課金カテゴリをCONVERSATIONALに設定して、EU地域向けのRCS送信者を作成してください。」	rcs, configuration
update-rcs-sender	RCS送信者のブランド、国、テスト番号、アンケートを更新します。 使用例:「RCS送信者abc123にブランドロゴのURLを設定してください。」	rcs, configuration
launch-rcs-sender	Googleと通信事業者による審査にRCS送信者を申請します。申請前に、ブランドの詳細、国、アンケートのすべての項目を入力する必要があります。 使用例:「RCS送信者abc123を申請してください。」	rcs, configuration
add-rcs-test-number	RCS送信者にテスト用電話番号を追加します（1リクエストあたり最大20件、送信者あたり合計200件）。 使用例:「+14155552671をRCS送信者のテスト番号として追加してください。」	rcs, configuration
delete-rcs-test-number	RCS送信者からテスト番号を削除します。 使用例:「テスト番号+14155552671をRCS送信者から削除してください。」	rcs, configuration
resend-rcs-test-number-invite	状態がPENDINGまたはUNVERIFIEDの場合に、テスト番号の招待を再送します。 使用例:「送信者abc123のテスト番号+14155552671への招待を再送してください。」	rcs, configuration
get-rcs-test-number-state	1件のRCSテスト番号の確認状態を取得します。 使用例:「送信者abc123のテスト番号+14155552671の状態を教えてください。」	rcs, configuration
get-rcs-number-capabilities	テスト番号の端末でサポートされているRCS機能（アクション、リッチカードのレイアウト、取り消し）を取得します。 使用例:「+14155552671でサポートされているRCS機能を教えてください。」	rcs, configuration

WhatsApp ツール

ツール	説明	タグ
get-whatsapp-account	プロジェクトの WhatsApp Business Account（WABA）について、オンボーディング状態、WABA ID、ビジネスの詳細、利用停止状態、1 日あたりのメッセージ上限、対応地域を取得します。 プロンプトの例: 「WhatsApp Business Account の現在の状況を教えてください。」	whatsapp, configuration
list-whatsapp-templates	WhatsApp チャネル固有のメッセージテンプレート（Meta が管理）を一覧表示します。オムニチャネルのテンプレートは、list-messaging-templates ツールで取得できます。 プロンプトの例: 「WhatsApp のテンプレートを表示してください。」	whatsapp, configuration
create-whatsapp-template	WhatsApp メッセージテンプレートを、下書きとして、または審査に提出して作成します。 プロンプトの例: 「本文が 'Your order {{1}} has shipped.' の、英語の WhatsApp UTILITY テンプレートを order_confirmation という名前で作成してください。」	whatsapp, configuration
update-whatsapp-template	名前と言語を指定して、WhatsApp メッセージテンプレートの下書きを更新します（または APPROVED／REJECTED／PAUSED／DISABLED 状態のテンプレートを下書きに戻します）。 プロンプトの例: 「order_confirmation の EN WhatsApp テンプレートの本文を 'Your order {{1}} has shipped today.' に更新し、審査に提出してください。」	whatsapp, configuration
delete-single-whatsapp-template-language	WhatsApp メッセージテンプレートの特定の言語版を、名前と言語を指定して削除します。同じテンプレート名の他の言語版には影響しません。 プロンプトの例: 「order_confirmation の EN WhatsApp テンプレートの下書きを削除してください。」	whatsapp, configuration
delete-all-whatsapp-template-languages	WhatsApp メッセージテンプレートのすべての言語版を、1 回の呼び出しで名前を指定して削除します。 プロンプトの例: 「order_confirmation WhatsApp テンプレートのすべての言語版を削除してください。」	whatsapp, configuration

電話番号ツール

ツール	説明	タグ
list-available-regions	プロジェクトで電話番号を利用できるすべての地域を一覧表示します。番号の種類（MOBILE、LOCAL、TOLL_FREE）で絞り込めます。 プロンプトの例:「フリーダイヤル番号を利用できる地域はどこですか？」	電話番号
list-rented-numbers	プロジェクトで現在利用中（レンタル中）の電話番号をすべて一覧表示します。地域、種類、パターン、機能で絞り込めます。 プロンプトの例:「米国で現在利用中の電話番号をすべて表示してください。」	電話番号
search-for-available-numbers	レンタル可能な電話番号を、地域、種類、パターン、機能で絞り込んで検索します。 プロンプトの例:「米国でSMSに対応した、利用可能なローカル番号を探してください。」	電話番号
rent-sinch-virtual-numbers	E.164形式で電話番号を指定して、1つ以上の電話番号をレンタル（有効化）します。 プロンプトの例:「電話番号+12025551234をレンタルしてください。」	電話番号
release-rented-number	レンタル中の電話番号をプロジェクトから解放します。 プロンプトの例:「電話番号+12025551234を解放してください。」	電話番号
get-rented-number-configuration	レンタル中の番号1つと、現在または予定されているサービス設定を取得します。 プロンプトの例:「+12025551234の設定とプロビジョニング状況を表示してください。」	電話番号、設定

設定ツール

ツール	説明	タグ
sinch-mcp-configuration	Sinch MCP サーバーで利用可能なすべてのツールとそのステータスを一覧表示します。ツールが無効になっている場合は、その理由が表示されます。 プロンプトの例:「Sinch MCP サーバーで利用できるツールはどれですか？」

はじめに

前提条件

• Node.js 20.xまたは22.x（LTS）
• プロビジョニング済みのSinch Buildアカウント
• Claude Desktop（またはその他のMCPクライアント）。このREADMEではClaude Desktopを対象としていますが、MCP サーバーはどのMCPクライアントでも使用できます。

API 認証情報

MCP ツールで使用する API を利用するには、以下の認証情報が必要です。

• RCS API 認証情報：Sinch プロジェクトで RCS を有効にする必要があります。有効化するには、[email protected] にお問い合わせください。有効化後、RCS では Conversation API と同じ PROJECT_ID、KEY_ID、KEY_SECRET を使用します（以下を参照）。

• WhatsApp Template API 認証情報：Conversation API と同じ PROJECT_ID、KEY_ID、KEY_SECRET を使用します（以下を参照）。

• Conversation / Numbers / Voice v2 API 認証情報：

  • （必須）PROJECT_ID：使用するプロジェクトを Sinch Build ダッシュボードから選択します（上部ツールバーの左側にあります）。
  • （必須）KEY_ID：Sinch Build ダッシュボードの アクセスキーセクションで、アクセスキーを選択するか、新しく作成します。
  • （必須）KEY_SECRET：これは、前の手順で選択または作成した Access Key に関連付けられたシークレットです。Access Key の作成時に Access Key Secret が表示されるのは一度だけなので、ご注意ください。紛失した場合は、新しい Access Key を作成する必要があります。
  • CONVERSATION_APP_ID：これは、使用する会話アプリの ID です。Sinch Build ダッシュボードの Conversation API / Apps セクションで確認できます。設定しない場合は、プロンプトで指定する必要があります。
  • CONVERSATION_REGION：これは、会話アプリとテンプレートが配置されているリージョンです。us、eu、br のいずれかを指定できます。設定しない場合は、デフォルトで us になります（ただし、マルチテナントモードでは必須であり、デフォルト値は設定されません）。
  • SMS チャネルを使用する場合は、SMS メッセージの送信元として使用する電話番号を DEFAULT_SMS_ORIGINATOR 環境変数に設定することもできます。国によっては、この設定が必須の場合があります。
  • ロケーション機能を使用する場合は、Google Geocoding API キーを GEOCODING_API_KEY 環境変数に設定することもできます。住所を緯度・経度のペアに変換するために必要です。

• Verification API 認証情報：Sinch Build ダッシュボードの Verification / Apps セクションに移動し、新しいアプリを作成するか、既存のアプリを選択します。以下の認証情報が必要です。

  • （必須）APPLICATION_KEY
  • （必須）APPLICATION_SECRET

• Voice サービス、通話、セッション、およびバッチのツールでは、上記のプロジェクト認証情報にある PROJECT_ID、KEY_ID、KEY_SECRET を使用します。

  • 必要に応じて、Voice 機能を備えた有効な Sinch 番号を CALLING_LINE_IDENTIFICATION に設定できます。これは tts-callout と tts-batch-callout のデフォルトの発信元として使用されます。また、呼び出し時にどちらのツールにも発信元を指定できます。どちらも設定されていない場合、発信者番号通知なしで通話が発信されます。

• Mailgun API 認証情報：Mailgun ダッシュボードの Mailgun / Domains セクションに移動し、新しいドメインを作成するか、既存のドメインを選択します。以下の認証情報が必要です。

  • （必須）MAILGUN_API_KEY
  • MAILGUN_DOMAIN
  • MAILGUN_SENDER_ADDRESS

MCP サーバーの設定

Sinch MCP サーバーは、実行用の NPM パッケージとして提供されています。Claude Desktop の設定ファイル（claude_desktop_config.json）で設定する方法は次のとおりです。環境変数には、ご自身の認証情報を設定してください。

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

MCP サーバーをローカルで実行する

オプション 1：Claude Desktop で stdio を使用して MCP サーバーを起動する

Claude Desktop で MCP サーバーをローカル実行するには、リポジトリをクローンして MCP サーバーをビルドする必要があります。この方法は、ローカルでの開発やテストに便利です。

ステップ 1：リポジトリをクローンする

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

ステップ 2：MCP サーバーをビルドする

cd sinch-mcp-server
npm install
npm run build

ステップ 3：Claude Desktop の設定をセットアップする

MCP サーバーを設定する方法の例を以下に示します。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": ""
      }
    }
  }
}

ステップ 4：（任意）MCP サーバーで利用できるツールをフィルタリングする

ツールが多すぎるとコンテキストが大きくなり、トークンの使用量が増え、LLM が適切なツールを選ぶ際に混乱しやすくなります。
tags オプションを使って、MCP サーバーで利用できるツールをフィルタリングできます。たとえば、会話ツールだけを使いたい場合は、次のオプションを args 配列に追加します。

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

タグはカンマで区切ることで複数組み合わせられます。たとえば、会話ツールと検証ツールの両方を使いたい場合は、次のコマンドを使用できます。

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

利用できるタグ：conversation、rcs、whatsapp、email、verification、voice、numbers、notification、configuration、all。

すべてのツールを使いたい場合は、--tags オプションを省略するか、タグ all を使用します。

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

オプション 2：MCP サーバーをリモートで起動し、SSE を使って接続する

このオプションでは、リモートマシンで MCP サーバーを実行し、Server-Sent Events（SSE）を使って接続できます。MCP サーバーをクラウドサーバーまたは専用マシンで実行したい場合に便利です。 デフォルトでは、Claude Desktop は STDIO を使って MCP サーバーに接続します。SSE を使って MCP サーバーに接続するため、supergateway ライブラリを使用します。

ステップ 1：MCP サーバーをビルドする

cd sinch-mcp-server
npm install
npm run build

ステップ 2：MCP サーバーの設定を行う

.template.env ファイルをコピーし、名前を .env に変更します。次に、プレースホルダーを独自の認証情報に置き換え、不要なキーを削除します。環境変数はサーバーの起動時に T3 Env を介して解析され、型付けされます。認証情報が不足していても、それを必要とするツールを呼び出したときにのみエラーが発生します。.env ファイルは次のようになります（）。

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

ステップ 3：MCP サーバーを起動する

npm run start:stdio

デフォルトでは、このコマンドは利用可能なすべてのツールを含む MCP を起動します。MCP サーバーで利用できるツールをフィルタリングする場合は、--tags オプションを使用できます。たとえば、会話ツールだけを使いたい場合は、次のようにコマンドを変更します。

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

タグはカンマで区切ることで複数組み合わせられます。たとえば、会話ツールと検証ツールの両方を使いたい場合は、次のコマンドを使用できます。

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

ステップ 4：Claude Desktop で MCP サーバーを設定する

次のように、Claude の設定ファイルで MCP サーバーを設定できます。

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

（ローカルで実行していない場合は、http://localhost:8000/sse を MCP サーバーの URL に置き換えてください）

オプション 3：ネイティブ Streamable HTTP サーバー（リモート向けに推奨）

このオプションでは、/mcp 上でネイティブ Streamable HTTP MCP サーバーを実行します。シングルテナントまたはマルチテナントのいずれかです（以下を参照）。

ステップ 1：MCP サーバーをビルドする

cd sinch-mcp-server
npm install
npm run build

ステップ 2：テナンシーを選択する

テナンシーは、最初に読み取られる MCP_AUTH_MODE によって決まります。

• MCP_AUTH_MODE が client-credentials の場合は multi-tenant（クライアントクレデンシャル）
• MCP_AUTH_MODE が sinchid-agent の場合は multi-tenant（sinchid-agent）
• MCP_AUTH_MODE が未設定の場合は single-tenant — この場合、PROJECT_ID、KEY_ID、KEY_SECRET が必要です

MCP_AUTH_MODE	テナンシー	PROJECT_ID/KEY_ID/KEY_SECRET	ツールの実行主体
既知のモードに設定	マルチテナント	読み取られない	呼び出し元から送信された認証情報
それ以外の値に設定	—	—	起動を拒否
未設定	シングルテナント	3 つすべて必須	サーバーの環境変数の認証情報

モードはほかの情報より先に読み取られるため、環境に残っている認証情報によって、マルチテナントサーバーが暗黙のうちに 1 つの共有アカウントに切り替わることはありません。このモードでは、認証情報の解決にもテレメトリにも使用されません。認識できない値は起動エラーとなり、受信認証をすべて無効にするシングルテナントへのフォールバックは行われません。MCP_AUTH_MODE が未設定の場合、3 つの値の一部しか設定されていなくても起動は拒否されます。3 つすべてを設定するか、すべて未設定にしてモードを指定してください。

シングルテナント（MCP_AUTH_MODE 未設定）

この MCP インスタンスを使うすべてのクライアントが同じ Sinch プロジェクトを共有する場合に使用します。実際には、ローカル開発向けです。認証情報はサーバー上にあり、3 つすべてが必須です。

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

注： このモードでは、/mcp で受信認証が行われません。MCP_AUTH_MODE が未設定であること自体が設定のすべてなので、検証する呼び出し元ごとの認証情報はなく、ポートに接続できる人なら誰でもそのアカウントで処理を実行できます。localhost にバインドし、外部に公開しないでください。リモートから接続できるサーバーには、マルチテナントモードを使用してください。

ここでは CONVERSATION_REGION は引き続き省略可能（デフォルトは us）で、プロンプトから上書きすることもできます。

マルチテナント（MCP_AUTH_MODE=client-credentials）

クライアントごとに異なる Sinch プロジェクトを使用する必要がある場合に使います。各クライアントは、リクエストごとに自身の認証情報を送信します。

ヘッダー	値
Authorization	Bearer <Base64-encoded projectId:keyId:keySecret>

このモードでは、OAuth を利用するツールにもスパン属性にも、サーバー環境の PROJECT_ID、KEY_ID、KEY_SECRET は読み取られません。OAuth クライアントはメモリ内にキャッシュされ、LRU 方式で削除されます（デフォルトは 256 件で、OAUTH_TOKEN_CACHE_MAX_ENTRIES によって設定できます）。

マルチテナントモードでは、CONVERSATION_REGION が必須です。指定しないとサーバーは起動を拒否し、us がデフォルトとして設定されることもありません。各デプロイメントで使用できるリージョンは 1 つに固定されており、リクエストごとにもプロンプトからもリージョンを上書きできません。

形状チェックの動作

形状チェックは、マルチテナントモードでのみ行われます。リクエストは設定された形状と照合され、それ以外の場合は 401 と WWW-Authenticate: Bearer チャレンジを返して拒否されます。

• client-credentials では、projectId:keyId:keySecret にデコードされるトークンが必要です。SinchID JWT には . 区切り文字が含まれるため、認証情報のトリプルにデコードされることはなく、ここで拒否されます。x-agent-id は無視されます。このデプロイメントでは読み取られません。
• sinchid-agent では、3 セグメントの JWT と x-agent-id ヘッダーが必要です。認証情報は、そのヘッダーが示すエージェントのインストールと、検証済みトークンクレームの Sinch プロジェクト ID から解決されるため、ヘッダーがないリクエストは処理を完了できません。Base64 の認証情報トリプルは JWT ではないため、ここで拒否されます。JWT の形をしているだけでは不十分です。リクエストが許可される前に、トークンは暗号学的に検証されます（下記のSinchID トークンの検証を参照）。

Authorization がまったくないリクエストには、理由をレスポンス本文に含めて、RFC 6750 のレルムのみのチャレンジ（Bearer realm="sinch-mcp"）が返されます。誤った種類のトークンを送信したリクエスト、または検証に失敗した JWT を送信したリクエストには、error="invalid_token" と説明が返されます。

同じイメージをそれぞれ独自の MCP_AUTH_MODE で 2 つデプロイすることで、互いの認証情報を受け入れることなく、別々のホスト名で 2 つの対象ユーザーに対応できます。MCP_AUTH_MODE は stdio では効果がありません。

SinchID トークンの検証（sinchid-agent のみ）

すべての sinchid-agent リクエストの Authorization JWT は、リクエストが許可される前に、設定された JWKS に照らして検証されます。検証項目は署名（RSA。アルゴリズムは RS256 に固定され、トークン自体の alg ヘッダーから取得されることはありません）、発行者、オーディエンス、有効期限（exp クレームのないトークンも拒否されます）、および空でないプロジェクト、アカウント、グローバルユーザー、スコープの各クレームです。偽造されたトークン、期限切れのトークン、発行者またはオーディエンスが不正なトークン、不完全なトークンは 401 で拒否され、セッションの作成やツールの実行には進みません。

JWT の検証には 3 つの環境変数が必要です。sinchid-agent モードではすべて必須であり、設定されていない場合、サーバーは起動を拒否します。

変数	値
SINCHID_JWT_ISSUER	期待される iss クレーム（例：https://id.sinch.com/）
SINCHID_JWT_AUDIENCE	期待される aud クレーム
SINCHID_JWT_JWKS_URI	発行者の JWKS ドキュメント（公開署名鍵）の URL

Secret Manager の認証には、Google Application Default Credentials を使用します。ローカル開発では、gcloud auth application-default login を実行してください。Google クライアントは、エージェントごとの環境変数認証情報やフォールバックを使わずに、開発者の ADC を使用します。ADC がシークレットを所有するプロジェクトを推測できない場合は、GOOGLE_CLOUD_PROJECT を設定してください。サービスアカウントの JSON ファイルをローカルで使用する場合に限り、GOOGLE_APPLICATION_CREDENTIALS が必要です。この変数にはファイルの絶対パスを設定し、絶対にコミットしないでください。Kubernetes では、エージェントのリリース時に、デプロイによって管理される Secret から sa-key.json がマウントされます。

JWKS ドキュメント全体はメモリ内に保持されます。ネットワーク通信がない状態が 3 秒続くと、JWKS の HTTP リクエストは中断されます。10 分後にサーバーはドキュメントの更新を試みますが、既知の鍵を先に破棄することはありません。予定された更新に失敗した場合、キャッシュ済みの鍵を使うトークンは、最後に取得に成功してから最大 1 時間、引き続き検証できます。後続の更新に成功すると、ドキュメントは直ちに置き換えられ、発行者が公開しなくなった鍵は削除されます。鍵 ID が見つからないトークンによる更新試行は、30 秒のクールダウンごとに最大 1 回です。この間隔は、失敗を含むすべての試行を基準に計測されます。そのため、障害やランダムな鍵 ID の大量送信によって JWKS エンドポイントに過剰なリクエストが送られることはありません。新たに公開された署名鍵は、クールダウン後、最初に成功した更新で取得されます。JWKS の検索に成功した後も未知の鍵は 401 で拒否されます。503 が返されるのは、試行した検索を完了できなかった場合、または最後に取得に成功したドキュメントが古すぎて、期限切れのキャッシュによるフォールバックを利用できない場合に限られます。

sinchid-agent の認証情報は、リクエスト時に Google Secret Manager から、最新バージョンの sinch-agent-m2m_<orderId>_<projectId> として読み込まれます。ペイロードは、client-credentials で使われるものと同じ Base64 の projectId:keyId:keySecret ブロブです。orderId は x-agent-id ヘッダーから取得し、projectId は検証済みトークンの https://sinch.com/project_id クレームから導出します。両方の識別子は正規 UUID でなければならず、シークレット ID の構築時に小文字に変換されます。デコードした認証情報のプロジェクトは、検証済みのプロジェクトと一致する必要があります。シークレットが存在しない、アクセスできない、空である、形式が不正である、一致しない、または名前が無効である場合は、応答を返して処理を拒否します。このモードでは PROJECT_ID、KEY_ID、KEY_SECRET へのフォールバックは行いません。これらの変数は引き続き、スタンドアロンの単一テナントモードでのみ使用されます。

Authorization 認証情報の形式（HTTP のみ）

1. UTF-8 文字列 projectId:keyId:keySecret を作成します（API 認証情報を参照）。
2. 標準 Base64 でエンコードします（改行なし。標準の +／/ アルファベットを使用し、base64url は使用しません）。
3. MCP セッションの初期化後も含め、すべての HTTP リクエストで Authorization: Bearer <base64> として送信します。

アクセスキーのシークレットには : 文字を含めることができます。3 つのフィールドを区切るのは、最初の 2 つの : のみです。

Authorization ヘッダーがないリクエスト、Bearer 以外のスキームを使用するリクエスト、またはトークンが Base64 でエンコードされた projectId:keyId:keySecret の 3 要素ではないリクエストは、HTTP レイヤーでは拒否されません。OAuth によって認証されるツールは、Missing or invalid Authorization header (expected "Bearer <Base64 of projectId:keyId:keySecret>"). と示すプロンプト応答を返します。

例（マルチテナント）：

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

適用範囲： Authorization 認証情報は、Conversation、Numbers、Number Lookup の各ツールに適用されます。Voice、Verification、Mailgun は、現時点では引き続きサーバーの環境変数を使用します。ローカル stdio（オプション 1）では、常にサーバーの環境変数を使用します。

x-agent-id ヘッダー（sinchid-agent のみ）

エージェントとの連携（Gemini Enterprise アプリにインストールされたエージェントなど）では、一意のインストール識別子（Marketplace の OrderId）を含む x-agent-id ヘッダーを送信します。Sinch のプロジェクト ID は、Authorization JWT 内の検証済み https://sinch.com/project_id クレームから取得されます。この 2 つを組み合わせて、サーバーが呼び出し元の Sinch 認証情報を取得する Google Secret Manager シークレット（sinch-agent-m2m_<orderId>_<projectId>）を特定します。MCP_AUTH_MODE=sinchid-agent で動作するデプロイでは、x-agent-id ヘッダーは必須です。このヘッダーがないリクエストは、ツールに到達する前に 401 で拒否されます。それ以外の環境ではこのヘッダーは読み取られません。他のモードでは無視され、stdio では認証情報は常に環境変数から取得されます。このカスタムヘッダーは、M2M 認証でトークン交換機能が利用可能になるまでの一時的な仕組みです。

ヘッダー	値
x-agent-id	エージェントのインストール識別子（例：GE の OrderId）

Authorization ユーザー JWT（エージェントのデプロイ）

エンドユーザーが OAuth のログインと同意のフローを完了した後、エージェント連携では、結果として得られた Auth0 ユーザー JWT を各リクエストで送信できます。

ヘッダー	値
Authorization	Bearer <user JWT>

トークンの検証が完了すると（上記の SinchID トークンの検証を参照）、サーバーは Sinch クレーム（https://sinch.com/project_id、https://sinch.com/account_id、https://sinch.com/global_user_id）と標準の scope クレームをリクエストコンテキストに取り込み、監査目的でログに記録します。検証済みの https://sinch.com/project_id クレームは x-agent-id と組み合わせて、Secret Manager から M2M API 認証情報（sinch-agent-m2m_<orderId>_<projectId>）を解決します。シングルテナントでは Authorization を読み取りません。マルチテナントモードでは、トークンがデプロイの形式と一致し、検証に合格する必要があり、そうでない場合、リクエストは 401 で拒否されます。将来的には、ユーザー JWT を M2M JWT に交換し、カスタムヘッダーを置き換える予定です。

Authorization トークンの内容は、デプロイ方法によって異なります。

デプロイ方法	Bearer トークン	Sinch 認証情報の取得元
シングルテナント	読み取らず、不要	サーバーの PROJECT_ID／KEY_ID／KEY_SECRET
マルチテナント、client-credentials	Base64 の projectId:keyId:keySecret	トークン自体
マルチテナント、sinchid-agent	SinchID アクセストークン（3 セグメントの JWT）	エージェントのインストール環境（Google Secret Manager）

2 つのマルチテナント形式は互いに排他的です。JWT には . 区切り文字が含まれますが、これは Base64 の文字セットにないため、認証情報の組み合わせがトークンとして読み取られることも、JWT から認証情報が解決されることもありません。各マルチテナントデプロイは独自の形式のみを受け付け、もう一方の形式には 401 を返します。詳しくは MCP_AUTH_MODE を参照してください。

リクエストで使用できる Authorization ヘッダーは 1 つだけなので、上記の監査クレームが取り込まれるのは、トークンが JWT の場合、つまり sinchid-agent デプロイの場合のみです。client-credentials の呼び出し元はユーザートークンではなく認証情報を送信するため、そのクレームはログに記録されません。

ステップ 3：HTTP サーバーを起動する

npm run start:http:server

サーバーはデフォルトで http://localhost:8000/mcp をリッスンします（PORT で変更できます）。

セッションストレージ（Redis）

セッション ID はプロセスメモリではなく Redis に保存されるため、ロードバランサー配下のどのポッドでもすべてのセッションを検証できます。スティッキーセッションは不要です。各リクエストでは専用の短時間だけ有効な McpServer と StreamableHTTPServerTransport が作成され、レスポンスの完了後に閉じられます。リクエスト間でメモリに保持されるものはありません。Redis は必須です。REDIS_HOST と REDIS_PORT の両方が設定されていない場合、サーバーは起動時にただちに終了します（REDIS_PASSWORD は省略可能です。AWS ElastiCache などで使用する場合のように、設定すると TLS が自動的に有効になります）。短時間の再試行後も Redis に接続できない場合、サーバーは JSON-RPC エラーコード -32003 を含む 503 Service Unavailable を返します。これは -32001 Session not found とは異なるエラーです。

セッションごとに永続するトランスポートがないため、サーバーは単独の GET／SSE ストリームをサポートしません。GET /mcp は 405 を返します。POST 中に送信されるサーバー起点の通知（ツールの進捗状況など）は通常どおり機能します。リクエストとは独立してプッシュされる通知は、トランスポートがリクエストごとに作成されるため、送信先がありません。

ステップ 4：MCP クライアントの設定例

どのモードでも同じ形式のヘッダーを送信します。異なるのは、トークンに含まれる認証情報の所有者です。シングルテナントのクライアントはサーバーのトリプルをエンコードし、マルチテナントのクライアントは自身のトリプルをエンコードします。

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

initialize のレスポンスを受信した後、以降のリクエストにはサーバーから返された mcp-session-id ヘッダーを含めてください。

コントリビューション

新しいツールの追加方法や GitHub Actions のバージョンを固定する方法など、コントリビューター向けのガイドラインについては、CONTRIBUTING.md を参照してください。

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。