Soprano Connect MCP Server

Soprano Connect MCP サーバー

Soprano Connect MCP サーバーを使用すると、グローバルな Communications Platform as a Service（CPaaS）である Soprano Connect を通じて、通信、顧客とのエンゲージメント、通信ワークフローの管理を行う AI エージェントを構築できます。Model Context Protocol（MCP）を利用します。

Soprano Connect MCP サーバーを使用すると、AI アシスタント、コパイロット、自律型エージェント、エンタープライズアプリケーションが、Soprano Connect のグローバル CPaaS プラットフォームと安全に連携できます。自然言語を使って、AI エージェントはメッセージの送信、顧客データの管理、アカウントの管理、複数のチャネルにわたる通信の調整を、エンタープライズレベルの管理された環境で行えます。

複雑な API 統合も、独自のミドルウェアも不要です。MCP 対応 AI クライアントを接続するだけで、インテリジェントな通信ワークフローの構築を始められます。Claude、VS Code Copilot、Cursor などの MCP 対応クライアントを Soprano MCP サーバーに接続すれば、エージェントは自然言語を通じて複数のチャネルでメッセージを送信し、配信状況を確認できます。

💡 なぜ Soprano MCP なのか？

Soprano Connect MCP は、通信機能を AI エージェントが直接利用できる、AI ネイティブなツールへと変換します。Soprano MCP を使うと、AI エージェントは次のことができます。

• Soprano Connect プラットフォームがサポートするすべてのチャネルを通じて、オムニチャネル通信を送信する
• 連絡先と顧客の連絡先リストを管理する
• メッセージの履歴と配信状況を照会する
• 顧客エンゲージメントのワークフローを自動化する
• 独自の統合コードを作成せずに、AI を活用した通信ユースケースを構築する
• エンタープライズレベルのセキュリティとガバナンスのフレームワーク内で運用する

🛠️ 主な機能

• SMS、RCS、WhatsApp、Viber、Email、Voice、Mobile Push など、Soprano Connect がサポートする任意のチャネルを通じて通信を送信
• チャネルごとのリッチコンテンツ — WhatsApp（メディア、インタラクティブなボタン／リスト、テンプレート、位置情報、リアクション）、RCS（リッチカード、カルーセル、候補）、Voice（テキスト読み上げ、録音済み音声、Call Control Objects）、Push Notification
• 一斉送信と、単一／一括メッセージのステータス照会
• 保存済みの連絡先、グループ、リストを読み取り専用で照会し、一斉送信の対象となる ID を確認
• WhatsApp Business（WABA）テンプレートの一覧表示と、メディアのアップロード／削除
• プラグイン可能な上流（Soprano）認証 — API Key、OAuth2（クライアント認証情報）、Basic、Legacy OAuth2、および WABA テンプレート用の例外的なセッション Cookie に対応。リクエストごとに選択でき、認証情報は呼び出し元から提供され、サーバー側には保存されません

📋 前提条件

• Soprano Design Connect API アカウント。使用する各チャネルのライセンスが割り当てられている必要があります
• Python 3.12+ と uv — stdio トランスポート（サーバーをローカルでサブプロセスとして実行する場合）でのみ必要です。すでにデプロイ済みの streamable HTTP サーバーへの接続には、ローカルへの Python のインストールは不要です
• MCP クライアントに対応した AI エージェントまたはアプリケーション

各ツール／チャネルは、該当するサービスへの加入とプロビジョニングが済んでいる Soprano アカウントでのみ利用できます。現在の契約に含まれていない機能を使用するには、Soprano のオンボーディングまたはアカウント管理の手続きを通じて、事前に有効化する必要があります。

目次

• 💡 Soprano MCP を選ぶ理由
• 🔌 トランスポート
  • ストリーマブル HTTP
  • stdio
• ✉️ メッセージングチャネル
• 🧰 利用可能なツール
• 🤖 エージェントの権限とアクセス制御
• 🔐 認証
• 🔒 クライアント認証（任意）
• 🚀 インストールと実行
• 🛠️ トラブルシューティング
• 🤝 コントリビューション
• 📄 ライセンス

---

🔌 トランスポート

Soprano MCP サーバーは、MCP 仕様で定義されている2種類のトランスポートをサポートしています。ホスト型のマルチテナントサービスとは異なり、サーバーはローカルで実行するか、デプロイしてご自身で運用するため、チャネルごとにエンドポイントやプロセスが用意されるのではなく、単一のエンドポイント／プロセスを使用します。

ストリーマブル HTTP

リモート環境やデプロイ環境（ALB、Lambda Function URL、API Gateway の背後など）で使用するためのストリーマブル HTTP トランスポートをサポートしています。MCP クライアントをサーバーの /mcp エンドポイントに接続し、<mems-mcp-server-url> をデプロイ先の URL に置き換えてください（ローカルで実行する場合は http://127.0.0.1:8000 を指定します）。

サーバーでクライアント認証（MCP_CLIENT_AUTH_MODE=oauth2.1）が有効になっており、レイヤー 2 フォールバックも有効な場合（ホスト型のデプロイに推奨される設定）、X-Soprano-* ヘッダーは一切必要ありません。

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

MCP クライアントによって OAuth ログイン／同意ページにリダイレクトされるので、そこで Soprano Connect の API ID と API KEY を入力します。指定する認証情報はこれだけです。サーバーはこの情報をユーザーの認証（レイヤー 1）と、レイヤー 2 フォールバックを介した Soprano への代理リクエストの認証の両方に使用するため、リクエストごとのヘッダーは不要になります。

それ以外の場合（MCP_CLIENT_AUTH_MODE=none の場合や、リクエストごとに異なる Soprano 認証情報を渡す場合）は、レイヤー 2 の認証情報を X-Soprano-* ヘッダーで明示的に指定してください。

{
  "servers": {
    "mems-mcp (http)": {
      "type": "http",
      "url": "<mems-mcp-server-url>/mcp",
      "headers": {
        "X-Soprano-Auth-Method": "api_key",
        "X-Soprano-Api-Id": "${input:soprano-api-id}",
        "X-Soprano-Api-Key": "${input:soprano-api-key}"
      }
    }
  }
}

X-Soprano-Domain-Url は通常、省略できます。サーバーの公開ホスト名が mcp- 命名規則に従っている場合（例：mcp-aus.sopranodesign.com）、サーバーはそのプレフィックスを削除して Soprano ドメイン（https://aus.sopranodesign.com）を自動的に導き出します。この規則に従わない環境にデプロイした場合や、ホスト名から推定されるものとは異なるドメインを指定する場合に限り、このヘッダーを明示的に設定してください。

上記の X-Soprano-* ヘッダーは api_key メソッド用です。代わりに、対応しているほかの認証方法を使用する場合は、認証の説明に従って、該当するヘッダーセットに置き換えてください。

// oauth2 (client credentials)
"headers": {
  "X-Soprano-Auth-Method": "oauth2",
  "X-Soprano-Client-Id": "${input:soprano-client-id}",
  "X-Soprano-Client-Secret": "${input:soprano-client-secret}"
}

// basic
"headers": {
  "X-Soprano-Auth-Method": "basic",
  "X-Soprano-Username": "${input:soprano-username}",
  "X-Soprano-Password": "${input:soprano-password}"
}

// legacy_oauth2
"headers": {
  "X-Soprano-Auth-Method": "legacy_oauth2",
  "X-Soprano-Username": "${input:soprano-username}",
  "X-Soprano-Password": "${input:soprano-password}"
}

ストリーマブル HTTP にまだ対応していない MCP クライアント向けに、従来の sse トランスポート（サーバーに --transport sse フラグを追加し、エンドポイント /sse を使用）も利用できます。

stdio

ローカルで使用する場合（VS Code、Claude Desktop などからサブプロセスとして起動する場合など）は、--transport stdio を指定して実行します。stdio では HTTP ヘッダーを使用できないため、Soprano の認証情報は代わりに SOPRANO_* 環境変数で指定します。

{
  "servers": {
    "mems-mcp (stdio)": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "${workspaceFolder}", "mems-mcp", "--transport", "stdio"],
      "env": {
        "SOPRANO_DOMAIN_URL": "https://aus.sopranodesign.com",
        "SOPRANO_AUTH_METHOD": "api_key",
        "SOPRANO_API_ID": "${input:soprano-api-id}",
        "SOPRANO_API_KEY": "${input:soprano-api-key}"
      }
    }
  }
}

上記と同様に、別の認証方法を使用する場合は、env ブロックを置き換えてください。

// oauth2 (client credentials)
"env": {
  "SOPRANO_DOMAIN_URL": "https://aus.sopranodesign.com",
  "SOPRANO_AUTH_METHOD": "oauth2",
  "SOPRANO_CLIENT_ID": "${input:soprano-client-id}",
  "SOPRANO_CLIENT_SECRET": "${input:soprano-client-secret}"
}

// basic
"env": {
  "SOPRANO_DOMAIN_URL": "https://aus.sopranodesign.com",
  "SOPRANO_AUTH_METHOD": "basic",
  "SOPRANO_USERNAME": "${input:soprano-username}",
  "SOPRANO_PASSWORD": "${input:soprano-password}"
}

// legacy_oauth2
"env": {
  "SOPRANO_DOMAIN_URL": "https://aus.sopranodesign.com",
  "SOPRANO_AUTH_METHOD": "legacy_oauth2",
  "SOPRANO_USERNAME": "${input:soprano-username}",
  "SOPRANO_PASSWORD": "${input:soprano-password}"
}

✉️ メッセージングチャネル

チャネルごとに MCP サーバーを用意するのではなく、すべてのチャネルを汎用の send_message ツールで利用できます（送信先は channel パラメーターで選択します）。これにより、ツールの範囲（およびトークン使用量）を抑えながら、Connect API がサポートする各チャネル固有のリッチコンテンツタイプをすべて利用できます。

チャネル	channel の値	サポートされるリッチコンテンツ
SMS	sms	プレーンテキストのみ
WhatsApp	whatsapp	メディア（画像／動画／ドキュメント／音声）、インタラクティブなボタン／リスト、事前承認済みテンプレート、位置情報、リアクション、コンテキスト（返信）
RCS	rcs	リッチカード、カルーセル、返信候補／アクション候補、メディア
Email	email	プレーンテキスト
Voice	voice	テキスト読み上げ、録音済み音声ファイル、Call Control Objects
Viber	viber	プレーンテキスト（Connect API ガイドにはリッチコンテンツの記載なし）
Mobile Push Notification	pushnotification	タイトル＋本文

send_message は、1 回の呼び出しにつき受信者 1 人にのみ送信します（カンマまたはセミコロン区切りの受信者リストは拒否されます）。多数の受信者に送るには、Soprano アカウントに保存済みのリスト、連絡先、またはグループを指定して send_broadcast を使用してください。ID を確認するには、list_contacts、list_groups、list_lists を使用します。

🧰 利用可能なツール

ツール	説明	対応するエンドポイント
send_message	サポートされている任意のチャネル（SMS、WhatsApp、RCS、Email、Voice、Viber、Push）で、受信者 1 人にリアルタイムメッセージを 1 件送信します。 プロンプトの例：「+33612345678 に、注文が発送されたことを知らせる WhatsApp メッセージを送信してください。」	POST /cgpapi/messages/{channel}
get_message_status	以前に送信したメッセージ 1 件の配信状況を確認します。 プロンプトの例：「SMS メッセージ 123456 の配信状況はどうなっていますか？」	GET /cgpapi/messages/{channel}/{id}
get_batch_status	複数の SMS メッセージの配信状況をまとめて確認します。 プロンプトの例：「この 10 件の SMS メッセージ ID の配信状況を確認してください。」	POST /cgpapi/batch/messages/status
send_broadcast	Soprano アカウントに保存済みのリスト、連絡先、グループに一斉送信 SMS を送信します（ID で指定。電話番号を直接指定することはできません）。 プロンプトの例：「『North Region』の連絡先リストに登録されている全員に、嵐への警戒を促す SMS を一斉送信してください。」	POST /cgpapi/broadcast/sms
list_contacts	保存済みの連絡先（ID、名前、携帯電話番号、メールアドレス）を検索し、send_broadcast の宛先として使用する ID を取得します。読み取り専用です。名、姓、携帯電話番号、またはメールアドレスで絞り込みできます。ページ分割され、1 ページあたり最大 100 件です。 プロンプトの例：「Jo Smith の連絡先 ID を探してください。」	GET /rest/contacts
list_groups	保存済みの連絡先グループ（ID、名前）を検索します。読み取り専用です。名前で絞り込みでき、ページ分割されます。 プロンプトの例：「名前に『alert』が含まれるグループはありますか？」	GET /rest/groups
list_lists	保存済みの受信者リスト（ID、名前）を検索します。読み取り専用です。名前で絞り込みでき、ページ分割されます。 プロンプトの例：「『Appointments』リストの ID を教えてください。」	GET /rest/lists
list_whatsapp_templates	承認済みの WhatsApp Business（WABA）メッセージテンプレートを一覧表示します。 プロンプトの例：「注文確認用として承認済みの WhatsApp テンプレートは何ですか？」	GET /cgpapi/waba/templates
upload_whatsapp_media	WhatsApp メッセージで使用するメディア（画像／動画／ドキュメント／音声）をアップロードします。 プロンプトの例：「この商品画像をアップロードして、WhatsApp で送れるようにしてください。」	POST /cgpapi/waba/media/{source}
delete_whatsapp_media	以前アップロードした WhatsApp メディアを削除します。 プロンプトの例：「今アップロードした WhatsApp メディアファイルを削除してください。」	DELETE /cgpapi/waba/media/{id}

list_contacts、list_groups、list_lists の結果を読み取る

それぞれ {items, page, limit, total, has_more} を返します。フィルターは部分一致で、大文字と小文字は区別されません。list_contacts に複数のフィルターを指定した場合は、すべてに一致する必要があります。limit のデフォルトは 25（最大 100）です。

• items が空の場合、一致するレコードはありません。
• 次のページを取得するには、has_more が true の間、同じフィルターと limit を指定して、page に 1 を加えて再度呼び出します。すべてのページを順に取得するより、フィルターを使うことをおすすめします。
• total がわかるのは 1 ページ目のみです。また、list_lists では name フィルターを使用すると null になります。
• list_contacts が返すのは通常の連絡先のみです（バックエンドの検索対象はこの連絡先タイプに限定されています）。ユーザーなど、ほかの連絡先タイプのレコードは返されません。
• グループ名とリスト名は一意ではないため、id を使用してください。

🤖 エージェントの権限とアクセス制御

すべてのツールには、MCP の標準的なツールアノテーション（readOnlyHint、destructiveHint、openWorldHint）が付与されています。これにより、クライアントはツールの呼び出し前にガバナンスを適用できます。たとえば、send_message／send_broadcast／upload_whatsapp_media は読み取り専用ではなく、オープンワールドにアクセスします（実際のメッセージ配信や費用が発生します）。また、delete_whatsapp_media には破壊的操作のフラグも付与されています。list_contacts、list_groups、list_lists は読み取り専用ですが、list_contacts は実際の携帯電話番号とメールアドレスをエージェントのコンテキストに返すため、エージェントに付与する認証情報の範囲を適切に制限してください。メッセージの送信には実際の費用と評判への影響が伴うため、エージェントに無制限のアクセスを許可するのではなく、MCP クライアント／ホストの権限制御（確認プロンプト、許可リスト、スコープを限定した認証情報）をこれらのツールに適用してください。詳しくは、ガイダンスとして MCP 仕様の実装上の考慮事項を参照してください。

🔐 認証

Soprano の認証情報はリクエストごとに指定され、サーバー側に保存されたり、呼び出し間でキャッシュされたりすることはありません。指定方法はトランスポートによって異なります（streamable-http／sse では HTTP ヘッダー、stdio では環境変数を使用します）。

認証方式	stdio 環境変数	HTTP ヘッダー
API Key	SOPRANO_AUTH_METHOD=api_key、SOPRANO_API_ID、SOPRANO_API_KEY	X-Soprano-Auth-Method: api_key、X-Soprano-Api-Id、X-Soprano-Api-Key
OAuth2（クライアント認証情報）	SOPRANO_AUTH_METHOD=oauth2、SOPRANO_CLIENT_ID、SOPRANO_CLIENT_SECRET	X-Soprano-Auth-Method: oauth2、X-Soprano-Client-Id、X-Soprano-Client-Secret
Basic	SOPRANO_AUTH_METHOD=basic、SOPRANO_USERNAME、SOPRANO_PASSWORD	X-Soprano-Auth-Method: basic、X-Soprano-Username、X-Soprano-Password
Legacy OAuth2	SOPRANO_AUTH_METHOD=legacy_oauth2、SOPRANO_USERNAME、SOPRANO_PASSWORD	X-Soprano-Auth-Method: legacy_oauth2、X-Soprano-Username、X-Soprano-Password
セッション Cookie（list_whatsapp_templates のみ）	SOPRANO_AUTH_METHOD=session_cookie、SOPRANO_SESSION_COOKIE	X-Soprano-Auth-Method: session_cookie、X-Soprano-Session-Cookie

どちらのトランスポートでも、対象ドメインも必要です。stdio では SOPRANO_DOMAIN_URL、HTTP では X-Soprano-Domain-Url を使用します。例：https://aus.sopranodesign.com。streamable-http／sse では、サーバー自体の公開ホスト名が mcp- で始まる命名規則に従っている場合（例：mcp-aus.sopranodesign.com）、このヘッダーを省略できます。その場合、プレフィックスを取り除いてドメインが自動的に導出されます。

🔒 クライアント認証（任意）

上記はすべてレイヤー 2（このサーバー → Soprano）です。これとは独立して、受信する MCP リクエストに認証を必須にすることもできます（レイヤー 1 — クライアント → このサーバー）。デフォルトでは無効です。

環境変数	必須	説明
MCP_CLIENT_AUTH_MODE	—	none（デフォルト）または oauth2.1
MCP_OAUTH_ISSUER_URL	oauth2.1 の場合	認可サーバーの発行者 URL。複数のドメインをこのデプロイで処理する場合は、カンマ区切りで指定します。組み込みのセルフホスト可能な AS を使用する場合は、リクエストごとに呼び出し元の Host ヘッダーから自動的に導出されるため、未設定のままにできます。
MCP_OAUTH_AUDIENCE	oauth2.1 の場合	想定するトークンの aud クレーム。カンマ区切りで指定します。セルフホスト可能な AS を使用する場合は、上記と同様にリクエストごとに導出されます。
MCP_OAUTH_RESOURCE_SERVER_URL	oauth2.1 の場合	このサーバーの公開 URL。リクエストの Host が設定済みのドメインに一致しない場合のフォールバックのデフォルト値です。
MCP_OAUTH_JWKS_URI	任意	デフォルトは {issuer}/.well-known/jwks.json です
MCP_OAUTH_REQUIRED_SCOPES	任意	必須スコープをカンマ区切りで指定します

標準に準拠した任意の OAuth2/OIDC 認可サーバー（Auth0、Okta、Cognito など）で動作します。

組み込みのセルフホスト可能な認可サーバー

一部の MCP クライアント（確認済み：Zendesk Agent）は、ベアラートークンの検証だけでなく、インタラクティブな OAuth 2.0 認可コードと同意のフロー全体を必要とします。別の IdP を立ち上げる代わりに、このサーバーを独自の認可サーバーとして動作させ、呼び出し元の Connect API ID/API KEY をその ID として使用できます。以下のルートは常にマウントされており、MCP_CLIENT_AUTH_MODE=oauth2.1 を設定し、MCP_OAUTH_ISSUER_URL をこのデプロイ自体に向けると利用できます。

• GET/POST /oauth/authorize — ログインと同意のフォームです。リクエスト自身の Host ヘッダーから導出した Connect API ドメイン（mcp- の規則に従う場合）に対して API ID/API KEY を検証し、導出できない場合は MEMS_CONNECT_API_URL にフォールバックします
• POST /oauth/token — authorization_code（PKCE 対応）、client_credentials、refresh_token の各グラント
• POST /oauth/register — RFC 7591 Dynamic Client Registration。常に公開クライアント（PKCE で保護）を登録し、client_secret は発行しません
• GET /.well-known/oauth-authorization-server / GET /.well-known/jwks.json — RFC 8414/7517 のディスカバリーメタデータ

ほとんどの MCP クライアントは、そのメタデータから必要なスコープを自動的に検出します。検出されない場合は、{your-deployment-url}/.well-known/oauth-authorization-server にある scopes_supported リストを確認し、クライアントで手動設定してください。

環境変数	必須	説明
MEMS_CONNECT_API_URL	はい	フォールバックの Connect API ドメインです。リクエストの Host から mcp- の規則によってドメインを導出できない場合（例：1 つのデプロイで複数のドメインを処理する場合）に使用します
MCP_OAUTH_SIGNING_KEY（または AWS Secrets Manager ARN 用の MCP_OAUTH_SIGNING_KEY_SECRET_ARN）	推奨	発行する JWT の署名に使用する PEM RSA 秘密鍵です。どちらも設定されていない場合は一時鍵が生成されます（警告が表示されます）。単一のローカルプロセスでのみ使用する場合は問題ありません
MCP_OAUTH_CLIENTS_TABLE / _CODES_TABLE / _CONSENTS_TABLE / _AUDIT_TABLE / _REFRESH_TOKENS_TABLE	任意	クライアント／コード／同意／監査／リフレッシュトークンのストレージを担う DynamoDB テーブル名です（デフォルトは mems-mcp-oauth-*）。boto3 用の AWS 認証情報が必要です
MCP_OAUTH_LAYER2_FALLBACK / MCP_OAUTH_LAYER2_CREDENTIALS_TABLE	任意	X-Soprano-* ヘッダーを送信できないクライアントが、レイヤー 1 で認証に使用した Connect ID をレイヤー 2 の呼び出しでも再利用できるようにします（オプトイン方式。実際の API KEY をサーバー側にキャッシュし、TTL で期限を制限します）

🚀 インストールと実行

git clone https://github.com/soprano-mcp/mcp.git
cd mcp
uv sync

# stdio (local subprocess, e.g. launched by an MCP client config)
uv run mems-mcp --transport stdio

# streamable-http (remote/deployable)
uv run mems-mcp --transport streamable-http
# host/port: MEMS_MCP_HOST (default 127.0.0.1), MEMS_MCP_PORT (default 8000)

🛠️ トラブルシューティング

認証の問題

• X-Soprano-* ヘッダー（または SOPRANO_* 環境変数）が、ドメイン URL を含め、サポートされている 5 つの認証方式のいずれかと完全に一致していることを確認してください。
• list_whatsapp_templates は session_cookie 認証が必要な唯一の例外です。それ以外のすべてのツールでは、残りの 4 つの方式を使用できます。

メッセージ配信の問題

• 送信先がチャネルに対して有効であることを確認してください（SMS／WhatsApp／RCS／Voice／Viber では電話番号、Email ではメールアドレス）。
• get_message_status（SMS の場合は get_batch_status）を確認してください。send_message が成功したという応答は、Soprano がリクエストを受け付けた（ENROUTE）ことを示すだけで、配信済みであることを意味するわけではありません。
• チャネルやアカウントによっては、Soprano 側で明示的なライセンス付与やプロビジョニング（例：Viber クライアント接続）が必要です。認証やペイロードに問題がないのに API からライセンス関連のエラーが返される場合は、Soprano サポートに確認してください。

その他の問題

• Connect API のエラーは、ツールのエラーテキスト（Soprano の errorDescription フィールド）を通じて表示されます。HTTP レベルの詳細については、Connect API ガイドのレスポンス／エラー形式のドキュメントを参照してください。

🤝 コントリビューション

リポジトリへのイシューやプルリクエストを歓迎します。

📄 ライセンス

MIT