Vonage MCP Server

English | 日本語

VonageのSMS送信と音声通話を AIエージェントから安全に使うための MCP (Model Context Protocol) サーバーです。

利用者が自分の環境にコンテナを立て、自分の Vonage 資格情報を設定して使う OSS のリファレンス実装です。このプロジェクトがあなたの資格情報を預かることはありません。

このプロジェクトの前提

脅威モデル — エージェントを信頼できる主体として扱わない

攻撃者はプロンプトインジェクションによって AI エージェントを操れるものとします。

SMS 送信と音声通話は取り消せず、課金が発生し、相手にも迷惑がかかりうる操作です。「エージェントが正しく使えば安全」という前提は置けません。このサーバーのガードレールは、エージェントが敵対的に振る舞っても被害が上限内に収まることを目指しています。

そのため、既定ではツールが1つも公開されません。 使う機能を環境変数で明示的に有効にしてください。

対象範囲

Related MCP server: twilio-mcp

対応プラットフォーム

本サーバーは MCP 仕様に準拠した stdio と Streamable HTTP の2形態を実装しており、プラットフォーム固有の分岐は持ちません。以下は各基盤の公開ドキュメントに基づく対応状況です。

凡例: ✅ 実機で確認済み / 📄 ドキュメント上は対応（未検証）/ ⚠️ 制約あり

ツール実行前の承認について

send_sms / make_voice_call には、MCP のツール注釈で destructiveHint: true を付けています。これを解釈する基盤（Gemini Enterprise など）では、実行前に確認が表示されます。get_sms_status / get_call_status は readOnlyHint: true なので確認は省かれます。

インストール方法

方法1: MCPB Bundle（推奨 - ワンクリックインストール）

Claude Desktopで簡単にインストールできます：

1. MCPBファイルのダウンロード

   • vonage-mcp-server.mcpb をダウンロード

2. Claude Desktopで開く

   • .mcpbファイルをダブルクリック、またはClaude Desktopにドラッグ&ドロップ

3. 環境変数の設定

   • Claude Desktopのインストールダイアログで以下を入力：

     • VONAGE_APPLICATION_ID: Vonage Application ID

     • VONAGE_PRIVATE_KEY_PATH: 秘密鍵ファイルのパス（例: /Users/your-name/vonage/private.key）

     • VONAGE_VOICE_FROM: 音声通話用の電話番号（E.164形式、例: 81345438093）

4. インストール完了

   • Claude Desktopを再起動すると、Vonage MCPサーバーが利用可能になります

方法2: 手動セットアップ

セットアップ

依存関係のインストール

npm install

Vonage設定

1. Vonageアカウントの作成

   • 日本国内でご利用の場合は 日本語での申し込みページ から作成できます（詳細）

   • 海外の場合は Vonage Developer Portal から作成します

   • アプリケーションを作成し、Application IDを取得

2. 秘密鍵の準備

   • Vonage Developer Portalで秘密鍵（private.key）をダウンロード

   • プロジェクトルートに private.key として保存

3. 環境変数の設定

   cp .env.example .env

   .env ファイルを編集して以下を設定：

   VONAGE_APPLICATION_ID=your_application_id_here
   VONAGE_PRIVATE_KEY_PATH=./private.key
   VONAGE_VOICE_FROM=14155550100  # Voice通話用のFROM番号

機能の有効化（capability トグル）

このサーバーは、既定ではツールを1つも公開しません。 使う機能だけを環境変数で明示的に有効にしてください。電話とSMSは実際に課金が発生し、相手にも迷惑がかかりうる操作なので、「気づかないうちに使える状態になっていた」を避けるための設計です。

# SMSの単発送信だけを使う場合
ENABLE_SMS=true

無効なツールは tools/list の結果に含まれません。エージェントが存在しないツールを呼ぼうとして迷走せず、使わないツールの定義がコンテキストを消費することもありません。

安全機能（Guardrails）の環境変数

AIエージェント（Gemini Enterprise / Claude 等）から利用する際の、意図しない課金・スパム送信を防ぐための設定です。すべて任意で、未設定でも動作します。

# 検証中は自分の番号だけに送信を許可する例
ALLOWED_NUMBERS=+819012345678,+819087654321
RATE_LIMIT_PER_HOUR=3
VONAGE_API_SIGNATURE_SECRET=your_signature_secret_here

日本向け SMS の利用条件

守るべき利用条件

これらはサーバー側では判定できません。 本文の内容や同意取得の有無はサーバーからは分からないため、利用者の責任で遵守してください。

配信の不確実性 — もっとも注意が必要な点

このサーバーはこう扱います。

• ブロックはしません。 正当な用途がありますし、拒否基準が非公開である以上こちらで判定しきれません

• 日本宛で URL を含む本文の場合、dry_run と成功レスポンスに delivery_warning を添えます

• send_sms の description に「成功レスポンスは配信保証ではない」と明記しています

重要な連絡に SMS を使う場合は、get_sms_status で配信結果を確認し、別の手段も併用してください。

文字数

Unicode 連結メッセージの上限は Docomo / KDDI / Softbank が 670文字、Rakuten が 660文字です。このサーバーは安全側の 660文字を絶対上限とし、実際の制限はセグメント数で掛けています。

content_id / entity_id について

Vonage Messages API には「特定国の規制要件を満たすためのパラメータ」として content_id / entity_id がありますが、これらはインドの DLT（Distributed Ledger Technology）登録制度のためのものです。entity_id が DLT に登録した Principal Entity ID、content_id が承認済みテンプレート ID にあたります。

日本宛の送信では不要なため、このサーバーでは使用していません。

送信者ID（sender ID）のルール

SMS の from には Vonage 公式ルールが適用されます。**英数字1〜11文字（A-Z a-z 0-9）**で、先頭文字と最小長の制限はありません。2FA や AB も有効です。

日本宛には、これに加えて日本の携帯キャリア固有の制限がかかります。

日本以外が宛先の場合、これら2つの制限は適用されません（自社の発信元電話番号を送信元に使えます）。

宛先のガードレール

宛先には、緩められるものと緩められないものの2種類の制限がかかります。

これらは AND で効きます。ALLOWED_NUMBERS に載せた番号でも、国番号が許可されていなければブロックされます。判定はすべて dry_run: true の時点で行われるので、「dry_run は通ったのに本番で弾かれた」は起きません。

レートリミットの数え方

「ツール呼び出し回数」ではなく「送信件数」で消費されます。 どのツールを使ったかではなく、何件送ったかで枠が減ります。

ただしSMS の課金はセグメント単位です（SMS の課金単位）。件数の枠は「操作の回数」を抑えるもので、費用そのものを抑えたい場合は segments の枠を使ってください。

枠はツールごとではなく、次の2層で管理されます。

1回の送信は該当するバケットを同時に消費します。どれか1つでも足りなければどれも消費せずエラーになるので、「送っていないのに枠だけ減る」ことはありません。エラーレスポンスの exceeded_bucket に、どのバケットで不足したかが入ります。

SMS の課金単位 — セグメント

SMS の課金は通数ではなくセグメント単位です。 1セグメントに入る文字数はエンコーディングで変わります。

非ASCII文字が1文字でも混ざると、本文全体が UCS-2 になります。 英数字159文字＋日本語1文字で、1セグメントから3セグメントに跳ねます。

本文の上限はセグメント数で指定します（SMS_MAX_SEGMENTS、既定 3）。文字数で縛っても課金と対応しないためです。既定の3セグメントは、日本語なら約200文字、英数字なら約450文字に相当します。

dry_run のレスポンスに encoding と segments が含まれるので、送信前にユーザーへ提示してください。

開発用依存関係のインストール

npm install --save-dev @types/node typescript ts-node

開発

開発サーバーの起動

npm run dev:start

TypeScriptのコンパイル

npm run build

コンパイルされたコードの実行

# 環境変数ファイル(.env)を使用して実行（推奨・Node.js v22以降）
npm start

# 環境変数ファイルを使用せずに実行（従来方式）
npm run start:legacy

ファイル監視モード（コンパイル）

npm run dev

ビルドファイルのクリーンアップ

npm run clean

テストの実行

npm test

テストの監視モード

npm run test:watch

カバレッジ付きテスト

npm run test:coverage

Claude Desktopでの利用

このMCPサーバーをClaude Desktopで利用するための設定方法を説明します。

方法1: MCPB Bundle（推奨 - ワンクリックインストール）

.mcpbファイルを使用すると、Claude Desktopに簡単にインストールできます。

インストール手順

1. MCPBファイルの作成

   mcpb CLI が必要です（未インストールなら一度だけ）。

   npm install -g @anthropic-ai/mcpb

   npm run build:mcpb

   これにより vonage-mcp-server.mcpb ファイルが作成されます。

2. Claude Desktopで開く

   • 作成された .mcpb ファイルをダブルクリック

   • または Claude Desktop にドラッグ&ドロップ

3. 環境変数の設定 Claude Desktop のインストールダイアログで以下を入力：

   • Vonage Application ID: Vonage Application ID

   • Private Key Path: 秘密鍵ファイルの絶対パス（例: /Users/your-name/vonage/private.key）

   • Voice Call From Number: 音声通話用の電話番号（E.164形式、例: 81345438093）

4. インストール完了 Claude Desktop を再起動すると、Vonage MCP サーバーが利用可能になります。

MCPBファイルの配布

作成した .mcpb ファイルは他のユーザーと共有できます：

• GitHub Releases で配布

• 直接ファイルを共有

方法2: 手動セットアップ

1. サーバーのビルドと起動

# プロジェクトをビルド
npm run build

# サーバーを起動（Node.js v22以降、推奨）
npm start

# または従来方式で起動（環境変数ファイルを使用しない場合）
npm run start:legacy

2. Claude Desktopの設定

Claude Desktopの設定ファイル claude_desktop_config.json に以下の設定を追加します：

{
  "mcpServers": {
    "vonage-mcp-server": {
      "command": "node",
      "args": ["--env-file=.env", "dist/index.js"],
      "cwd": "/Users/your-username/path/to/vonage-mcp-server"
    }
  }
}

または環境変数を直接指定する方法もあります：

{
  "mcpServers": {
    "vonage-mcp-server": {
      "command": "node",
      "args": ["/Users/your-username/path/to/vonage-mcp-server/dist/index.js"],
      "env": {
        "VONAGE_APPLICATION_ID": "your-application-id",
        "VONAGE_PRIVATE_KEY_PATH": "/Users/your-username/path/to/vonage-mcp-server/private.key"
      }
    }
  }
}

設定ファイルの場所

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

設定手順

1. 上記のパスにある claude_desktop_config.json を開く

2. mcpServers セクションに上記の設定を追加

3. ファイルを保存

4. Claude Desktopを再起動

3. 利用可能な機能

設定完了後、Claude Desktopで以下の機能が利用できます：

ツール

すべてのツールは軽量なJSONを返します（Vonage APIの生レスポンスは返しません）。詳細は ツールのレスポンス形式 を参照してください。

• send_sms: 単発SMS送信ツール

  • 入力:

    • to (必須): 送信先の電話番号（E.164形式 +819012345678 または日本の国内形式 09012345678）

    • message (必須): 送信するメッセージ（最大3セグメント — 日本語なら約200文字、英数字なら約450文字。SMS の課金単位を参照）

    • from (オプション): 送信元。英数字1〜11文字（A-Z a-z 0-9）。省略時は'VonageMCP'。dry_run の時点で検証される。送信者ID（sender ID）のルールを参照

    • dry_run (オプション): true で送信せず検証のみ（デフォルト: false）

  • 機能:

    • 日本の電話番号（0から始まる）は自動的にE.164形式に変換

    • {"status":"success","message_id":"...","to":"+81..."} を返却

• make_voice_call: 音声通話ツール

  • 入力:

    • to (必須): 発信先電話番号（E.164形式または0ABJ形式）

    • message (必須): 読み上げるメッセージ（最大1000文字）

    • voice (オプション): 女性 または 男性（デフォルト: 女性）

    • dry_run (オプション): true で発信せず検証のみ

  • 機能:

    • 指定番号に発信してメッセージを音声で読み上げ

    • 日本語音声対応（女性・男性）

    • NCCO（Nexmo Call Control Object）を使用

    • 通話時間の自動見積もり。見積もりから通話の強制切断時間（length_timer）を決めるため、dry_run で提示した時間を大きく超えて課金されることはない

    • dry_run は estimated_duration_seconds（見積もり）と max_duration_seconds（実際に適用される上限）の両方を返す

• get_call_status: 通話ステータス取得ツール

  • 入力:

    • call_id (必須): 取得する通話のCall ID（UUID形式）

  • 機能:

    • Vonage Voice APIから通話のステータス情報を取得

    • call_status（通話ステータス）、start_time、price、rate、duration_seconds を返却

    • 環境変数から自動的にApplication IDとPrivate Keyを読み込み

• get_sms_status: SMS配信ステータス取得ツール

  • 入力:

    • message_id (必須): send_sms が返した message_id

  • 機能:

    • delivery_status（submitted / delivered / failed 等）を返却

    • Vonage Messages APIは配信ステータスを同期取得できないため、HTTPサーバー版の Status Webhook（POST /webhooks/message-status）で受信した結果を参照する

    • Webhook未設定時・stdio版では submitted のまま（note フィールドで明示される）

    • 記録はオンメモリで24時間保持（プロセス再起動でクリア）

ツールのレスポンス形式

エラー時は必ず reason（原因）と suggestion（AIが次に取るべき行動）が含まれます。再試行が無意味なケースでは suggestion にその旨が明記されるため、AIエージェントの無限リトライを防げます。

4. 使用例

Claude Desktopで以下のような質問ができます：

単発SMS送信

「090XXXXYYYYに「これはVonage MCPサーバーを使って送信しています。」とSMSを送ってください」
→ send_smsツールを使用してSMS送信

音声通話

「090XXXXYYYYに女性の声で『会議は明日の10時からです』と電話をかけて」
→ make_voice_callツールを使用して発信・音声読み上げ

「080XXXXYYYYに男性の声で『システム障害が発生しました。至急対応をお願いします』と電話で伝えて」
→ make_voice_callツールを使用して緊急連絡

通話ステータス取得

「Call ID ca6b7710-3423-4c8d-b630-7b981ec4b2c2 の通話ステータスを取得してください」
→ get_call_statusツールを使用して通話情報を取得

「先ほどの通話の料金と時間を教えてください」
→ get_call_statusツールで通話詳細を確認

Voice通話機能

機能概要

Voice APIを使用して自動音声通話を発信し、指定されたメッセージを日本語で読み上げます。

主な特徴

• 自動発信: 指定番号への自動発信

• 日本語音声: 女性・男性音声による自然な読み上げ

• NCCO制御: Nexmo Call Control Objectによる通話フロー制御

• 通話時間見積: メッセージ長から自動的に通話時間を算出し、通話の強制切断時間に連動させる

音声オプション

使用例

// 会議リマインダー
make_voice_call({
  to: "090-1234-5678",
  message: "明日の会議は10時から会議室Aで行います。資料をご準備ください。",
  voice: "女性"
})

// 緊急連絡
make_voice_call({
  to: "080-9876-5432",
  message: "システム障害が発生しました。至急対応をお願いします。",
  voice: "男性"
})

通話ステータス取得機能

機能概要

Vonage Voice APIを使用して、過去の通話のステータス情報を取得します。通話の詳細（ステータス、料金、レート、通話時間）を確認できます。

主な特徴

• 詳細情報取得: 通話のステータス、料金、レート、通話時間を一度に取得

• 自動設定読み込み: 環境変数から自動的にApplication IDとPrivate Keyを取得

• エラーハンドリング: 存在しないCall IDに対する適切なエラーメッセージ

パラメータ

返却される情報

• status: 通話のステータス（completed, answered, busy, failed など）

• start_time: 通話開始時刻（ISO 8601形式）

• price: 通話料金（数値形式）

• rate: 通話レート（1分あたりの料金）

• duration: 通話時間（秒単位）

使用例

// Call IDを指定して通話ステータスを取得
get_call_status({
  call_id: "ca6b7710-3423-4c8d-b630-7b981ec4b2c2"
})

// 結果例:
// ステータス: completed
// 開始時刻: 2025-12-10T03:53:19.000Z
// 料金: 0.06287850
// レート: 0.13973000
// 通話時間: 27秒

5. トラブルシューティング

サーバーが起動しない場合

• npm run build が正常に完了しているか確認

• npm start でエラーが出ないか確認

• Node.jsバージョンが20.6.0以降であることを確認（node -v）

Claudeデスクトップでのエラー

• JSON解析エラー「Unexpected token 'd', "[dotenv@17."... is not valid JSON」が表示される場合:

  • claude_desktop_config.jsonのargsに--env-file=.envが含まれていることを確認

  • サーバーコードがdotenvを使用していないことを確認（最新のコードではdotenvは使用していません）

  • MCPサーバーを再起動

Claude Desktopで認識されない場合

• claude_desktop_config.json の設定が正しいか確認

• 作業ディレクトリ（cwd）のパスが正しいか確認

• Claude Desktopを再起動

機能が利用できない場合

• サーバーのログを確認（Claude Desktopの設定画面で確認可能）

• サーバーを再起動

Voice通話機能のトラブルシューティング

• Voice通話が発信されない場合:

  • VONAGE_VOICE_FROM環境変数が正しく設定されているか確認

  • VonageアプリケーションでVoice機能が有効になっているか確認

  • FROM番号がVonageアカウントに登録されているか確認

• 通話は繋がるが音声が再生されない場合:

  • NCCOパラメータの音声設定を確認

  • 音声オプション（女性/男性）が正しく指定されているか確認

プロジェクト構造

vonage-mcp-server/
├── src/                    # TypeScriptソースコード
│   ├── index.ts           # stdio版エントリーポイント
│   ├── http-server.ts     # HTTP版エントリーポイント・Webhook受信
│   ├── tools.ts           # MCPツール定義の共通レジストリ（stdio/HTTP共用）
│   ├── guardrails.ts      # 電話番号検証・ホワイトリスト・レートリミット
│   ├── toolResponse.ts    # 軽量JSONレスポンスの整形
│   ├── messageStatusStore.ts # SMS配信ステータスのオンメモリ保持
│   ├── webhookAuth.ts     # Vonage署名付きWebhookの検証
│   ├── vonage.ts          # Vonage SMS送信機能
│   ├── voiceCall.ts       # Voice通話機能・NCCO生成
│   └── callStatus.ts      # 通話ステータス取得機能
├── tests/                  # テストファイル
│   ├── index.test.ts      # メイン機能のテスト
│   ├── utils.test.ts      # ユーティリティのテスト
│   ├── callStatus.test.ts # 通話ステータス取得のテスト
│   ├── tools.test.ts      # ツールレジストリ・ガードレール統合のテスト
│   ├── guardrails.test.ts # ホワイトリスト・レートリミットのテスト
│   ├── messageStatusStore.test.ts # 配信ステータス保持のテスト
│   ├── http-server.test.ts # HTTPラッパーのテスト
│   └── integration.test.ts # 統合テスト
├── docs/
│   ├── deployment.md      # デプロイ手順
│   ├── setup-guide.md     # セットアップガイド (PDF の元原稿)
│   ├── gemini-enterprise-adk.md # Gemini Enterprise (ADK 経路) の手順
│   ├── dify.md            # Dify から使う手順
│   ├── agentcore.md       # AWS Bedrock AgentCore Gateway の手順
│   └── gemini_system_instruction.md # Gemini Enterprise向けSystem Instruction

### HTTPラッパー (Dify / 外部アプリ用)

HTTPラッパーを使用してサーバーを実行することで、外部アプリケーション（Difyなど）からHTTP POSTリクエスト経由でMCPツールを呼び出すことができます。

```bash
npm run start:http

これにより、ポート3000（デフォルト）でHTTPサーバーが起動します。

認証

MCP エンドポイント (/mcp) は Bearer トークンで認証します。

# 32バイトのランダムな値を生成して設定する
MCP_AUTH_TOKEN=$(openssl rand -hex 32)

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

OAuth 2.1（ChatGPT / Gemini Enterprise のコネクタなど）

MCP 仕様が定める認可の標準は OAuth 2.1 です。 上の MCP_AUTH_TOKEN による静的 Bearer は仕様には存在せず、基盤が任意のヘッダを設定させてくれる場合にだけ使えます（Claude Code / ADK / Dify / AgentCore / n8n はこれに当たります）。

一方、エンドユーザーが触る入り口 — ChatGPT のカスタムプラグイン、Gemini Enterprise のカスタムコネクタ — は「OAuth か認証なし」の2択しか出しません。 課金の発生するサーバーに「認証なし」は選べないため、この経路には OAuth でしか繋がりません。

このサーバーが担うのはリソースサーバー（RS）だけです。 認可サーバー（AS）は MCP 仕様でも明確にスコープ外とされており、外部の IdP（Auth0 / Okta / Entra ID / Keycloak など）を使ってください。

OAUTH_ISSUER=https://your-tenant.example.com
OAUTH_RESOURCE=https://vonage-mcp.example.com/mcp
OAUTH_JWKS_URI=https://your-tenant.example.com/.well-known/jwks.json

設定すると次の2つが有効になります。

• GET /.well-known/oauth-protected-resource（およびリソースのパスを付けた /.well-known/oauth-protected-resource/mcp）— RFC 9728 の保護リソースメタデータ。認証不要です。クライアントはトークンを持つ前にここを読み、どの認可サーバーへ行けばよいかを知ります

• /mcp の 401 / 403 に WWW-Authenticate: Bearer resource_metadata="..." が付きます — これが discovery の起点です

推奨構成: 認証は手前の層に置く

もっとも堅いのは、Cloud Run IAM や API Gateway をこのサーバーの手前に置く構成です。認証の実装をこのサーバーから切り離せるうえ、鍵のローテーションや監査ログもプラットフォーム側の仕組みに乗せられます。

その場合は TRUST_UPSTREAM_AUTH=true を設定してください（起動のたびに警告が出ます）。手前で認証していない環境でこれを有効にすると完全に無防備になります。

# Cloud Run IAM で認証する例（--allow-unauthenticated は付けない）
gcloud run deploy vonage-mcp-server \
  --set-env-vars TRUST_UPSTREAM_AUTH=true,ENABLE_SMS=true \
  --no-allow-unauthenticated

APIエンドポイント

ALL /mcp

MCP の Streamable HTTP エンドポイントです。POST (JSON-RPC) / GET (SSE) / DELETE (セッション終了) を MCP SDK の StreamableHTTPServerTransport が処理します。手書きの JSON-RPC 実装ではないので、仕様の追加に追従できます。

仕様どおり、クライアントは POST に Accept: application/json, text/event-stream を付ける必要があります（欠けていると 406 になります）。

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

エラーは2種類に分かれます。

前者は MCP SDK が inputSchema で検証して弾くため、ハンドラに到達しません（エラーメッセージにはスキーマに書いた説明がそのまま入ります）。後者は原因が reason、次に取るべき行動が suggestion に入ります。

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"send_sms","arguments":{"to":"09012345678","message":"hello"}}}

POST /webhooks/message-status

Vonage Messages API の Status Webhook（配信結果 / DLR）の受信エンドポイントです。Vonage から呼ばれるため Bearer トークン認証の対象外ですが、別途Webhook認証が必須です。

受信した配信結果はオンメモリに24時間保持され、get_sms_status ツールから参照できます。

認証は以下の優先順位で行われます。

1. VONAGE_API_SIGNATURE_SECRET が設定されていれば、Authorization: Bearer <JWT> の署名（HS256）と、ボディを束縛する payload_hash クレームを検証する（推奨）

2. VONAGE_WEBHOOK_SECRET が設定されていれば、x-webhook-secret ヘッダーと照合する

3. どちらも未設定なら 503 を返してエンドポイントを無効化する

# 共有シークレット方式の例
curl -X POST http://localhost:3000/webhooks/message-status \
  -H "Content-Type: application/json" \
  -H "x-webhook-secret: $VONAGE_WEBHOOK_SECRET" \
  -d '{"message_uuid":"abc-123","to":"819012345678","status":"delivered","channel":"sms"}'

POST /webhooks/inbound

受信メッセージ用のスタブ（常に 200 を返す）。Vonage側の設定必須項目を満たすために用意しています。

POST /webhooks/voice/answer

音声の着信に対して NCCO を返すエンドポイントです。このサーバーは発信専用で、着信を処理する機能を持ちません。 案内を読み上げて通話を終了します（文面は VOICE_INBOUND_MESSAGE で変更できます）。

それでも用意しているのは、Vonage の番号をアプリケーションにリンクすると、その番号への着信がアプリに向くためです。Answer URL が無いと、発信者は無言のまま切られます。

POST /webhooks/voice/event

通話イベントの受信エンドポイントです。受信した内容はオンメモリに24時間保持され、get_call_status ツールのレスポンスに detail と sip_code として重ねて返されます。

detail は status ごとに意味が異なります（公式リファレンス）。まとめて「宛先が悪い」と解釈しないでください。

get_call_status は、接続できなかった通話にこの分類に沿った note を添えます。

受信したイベントはオンメモリに24時間保持されます（最大1000件）。このうち、このサーバーが発信していない通話（着信レグや、同じ Application を共用する別システムの通話）には専用枠 200 件を設けています。 枠を分けないと、着信が多い環境で get_call_status から引ける記録のほうが押し出されるためです。

どちらのエンドポイントも認証は /webhooks/message-status と同じです（署名付きJWT を推奨、未設定なら 503 で無効化）。

Vonage Dashboard の Application 設定で、次のように登録します。

Gemini Enterprise などのAIエージェントから利用する

AIエージェントに設定すべき System Instruction（承認フロー、dry_run の使い方、エラー対処方針）を docs/gemini_system_instruction.md にまとめています。そのまま貼り付けられる形式です。

あわせて、サーバー側で ALLOWED_NUMBERS と RATE_LIMIT_PER_HOUR を設定することを強く推奨します。System Instruction はプロンプトインジェクションで破られる前提で読んでください。 実効的な防御はサーバー側の設定だけです。

⚠️ Gemini Enterprise のカスタム MCP サーバーコネクタを使う場合

公式ドキュメントによれば、このコネクタが送れる認証は 「認証なし」と「OAuth 2.0」の2つだけで、任意のヘッダを設定する欄がありません。つまり MCP_AUTH_TOKEN はこの経路では使えません。

かつコネクタは、MCP サーバーが公開インターネット上の HTTPS エンドポイントで到達可能であることを要求します。

取りうる構成は次の2つです。

構成A: 上流で OAuth 2.0 を終端する

API Gateway や Identity-Aware Proxy をこのサーバーの手前に置いて OAuth 2.0 を処理し、本サーバーには TRUST_UPSTREAM_AUTH=true を設定します。認証の実装をこのサーバーから切り離せるうえ、監査ログもプラットフォーム側の仕組みに乗せられます。詳しくは推奨構成: 認証は手前の層に置くを参照してください。

構成B: ADK でエージェントを書く（実機で確認済み・推奨）

コネクタを使わず、Agent Development Kit の McpToolset から StreamableHTTPConnectionParams で接続します。任意のヘッダを送れるので MCP_AUTH_TOKEN がそのまま使えます。

ツール実行前の承認も ADK の require_confirmation で取れます。 Gemini Enterprise の Apps に承認ウィンドウが表示され、承認するまで送信されません（2026-08-25 に dry_run → 承認 → 実送信 → delivered まで確認しました）。

手順は Gemini Enterprise の Agent Apps から使う（ADK 経由） にまとめています。

import os

from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# 完全な実装では Secret Manager から解決する（下記リンク先を参照）
MCP_AUTH_TOKEN = os.environ["MCP_AUTH_TOKEN"]

def confirm_unless_dry_run(**kwargs) -> bool:
    """dry_run: true 以外の呼び出しに承認を要求する。"""
    return kwargs.get("dry_run") is not True

# 課金対象のツールだけを、承認を必須にして渡す
sending = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://your-server.example.com/mcp",
        headers={"Authorization": f"Bearer {MCP_AUTH_TOKEN}"},
    ),
    tool_filter=["send_sms", "make_voice_call"],
    require_confirmation=confirm_unless_dry_run,
)

プロジェクト構造（続き）

├── dist/                  # コンパイルされたJavaScript
├── package.json           # プロジェクト設定
├── tsconfig.json          # TypeScript設定
├── jest.config.js         # Jest設定
├── .env.example           # 環境変数設定例
├── private.key            # Vonage秘密鍵（要設定・リポジトリには含めない）
├── LICENSE                # Apache License 2.0
├── SECURITY.md            # セキュリティポリシー
├── CONTRIBUTING.md        # コントリビューションガイド
└── README.md             # このファイル

依存関係

主要パッケージ

• @vonage/server-sdk - Vonage SMS機能

• @vonage/voice - Voice通話機能専用SDK

• @vonage/jwt - Webhook の署名検証

• @modelcontextprotocol/sdk - MCP Server実装

• zod - スキーマ検証

• zod-to-json-schema - ZodスキーマからJSON Schemaを生成（HTTP版の tools/list 用）

• express / cors - HTTPラッパー

Vonage アカウントについて

このサーバーを使うには Vonage の Application ID と秘密鍵が必要です。

日本国内でご利用の場合は、日本語での申し込みページ からのお申し込みをご検討ください。日本語でのサポートと請求に対応しています。

海外からご利用の場合は Vonage Developer Portal から直接開設してください。

このサーバーはどちらの経路で開設したアカウントでも同じように動作します。 特定の経路を強制することはありません。

提供元

このプロジェクトは 株式会社KDDIウェブコミュニケーションズ が Vonage のリセラーとして開発・公開しています。

私たちはこのサーバーをサービスとして運営していません。 OSS のリファレンス実装として提供しており、利用者の資格情報を預かることはありません。

ライセンス

Apache License 2.0

Copyright 2026 KDDI Web Communications Inc.

関連ドキュメント

• セキュリティポリシー — 脆弱性の報告方法と脅威モデル

• コントリビューションガイド

• デプロイ手順

• Gemini Enterprise の Agent Apps から使う（ADK 経由） — 実機で確認済みの手順

• Gemini Enterprise 向け System Instruction