Retell AI

@mindstone/mcp-server-retell-ai

Retell AI API を通じて、音声エージェントの電話発信、一括発信キャンペーン、通話管理、エージェント設定、LLM プロンプト管理、ナレッジベース、チャット履歴、音声の検索を行います。

通話の発信、通話履歴の確認、ユーザー確認を経たエージェントのプロンプト調整に使える、ローカルの音声操作コネクターを求める MCP ホストに最適です。

ステータス

• バージョン： 0.3.0 · npm
• 認証： API キー (RETELL_API_KEY)
• ツール： 32（通話、エージェント、LLM、音声、ナレッジベース、チャット）
• インターフェース： cloud-api
• 機械可読： STATUS.json

このパッケージの目的

Retell がホストする MCP サーバーは、HTTP 経由のリモート MCP に対応するクライアントに最適です。このパッケージは、リポジトリ内の他のパッケージと同じ npm ベースのコネクター導入フローで、Retell の音声操作を利用したいローカルの stdio ホスト向けです。

音声エージェントの操作を、明確なアシスタントのワークフローにします。エージェントとプロンプトを確認し、適切な電話番号を選び、通話を発信するかウェブ通話を作成してから、結果を監視します。価値は API にアクセスできることだけではありません。実際の通話操作を意図的かつ確認可能なものにし、適切なエージェント設定に結び付けるのに役立ちます。

インタラクション例

「サポートエージェントを使って、明日の予約確認のためジェーンに電話してください。」

ホストが呼び出すツール：

1. list_agents — サポートエージェントとそのエージェント ID を検索します。
2. get_retell_llm — プロンプトと、サポートされている動的変数を確認します。
3. list_phone_numbers — 登録済みの発信番号を検索します。
4. create_phone_call — ホストまたはユーザーの確認後に電話をかけます。
5. get_call — 通話ステータス、文字起こし、録音の詳細を確認します。

応答（一部省略）：

{
  "ok": true,
  "call_id": "call_01HXX...",
  "status": "registered",
  "from_number": "+14155551234",
  "to_number": "+14155559876",
  "warnings": []
}

要件

• Node.js 20+
• npm
• Retell AI API キー

ワンクリックでインストール

ボタンをクリックすると、ホストから RETELL_API_KEY の入力を求められます。

{
  "mcpServers": {
    "Retell AI": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-retell-ai"
      ],
      "env": {
        "RETELL_API_KEY": ""
      }
    }
  }
}

クイックスタート

インストールとビルド

cd <path-to-repo>/connectors/retell-ai
npm install
npm run build

npx

npx -y @mindstone/mcp-server-retell-ai

ローカル

node dist/index.js

設定

次の環境変数を設定します。

MCP ホストの設定

{
  "mcpServers": {
    "retell-ai": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-retell-ai"],
      "env": {
        "RETELL_API_KEY": "your-api-key"
      }
    }
  }
}

セキュリティに関する注意事項

発信電話にはホストによる確認が必要です

create_phone_call は、現実世界に影響を及ぼすアクションとしてマークされています。MCP ホストは、これを実行する前に、ユーザーの明示的な確認を必ず求める必要があります。 発信電話は Retell AI プランに対して分単位で課金され、誤発信は取り消せない現実世界への影響（見知らぬ人の電話が鳴る、録音が記録される、アカウントに請求される）をもたらします。

このコネクターを統合するホストには、以下が求められます。

• 実行のたびに、提案された from_number と to_number をユーザーに提示します。
• ユーザーが明示的に確認するまで、通話をブロックします。
• 以前の承認に基づいて create_phone_call を自動承認しません。通話ごとに個別の確認が必ず必要です。

上流へのリクエストを行う前に、from_number と to_number は E.164 正規表現 /^\+[1-9]\d{1,14}$/ に照らして検証されます。番号には次の条件があります。

• + の後に、1～9 の国番号の数字が続くこと（先頭にゼロは不可）。
• 数字のみで構成されること。スペース、ハイフン、括弧は拒否されます。
• 国番号を含めて、2～15 桁であること。

形式が正しくない番号は、構造化された INVALID_PHONE_NUMBER エラーとしてローカルで拒否され、上流には送信されません。

バッチ通話は影響範囲を拡大させます

create_batch_call は、タスクごとに実際の課金対象となる電話を 1 件発信します。バッチ全体に対して、create_phone_call と同じ確認ルールが適用されます。ホストは、実行前に受信者リスト全体（from_number とすべての to_number）を提示し、ユーザーの明示的な確認を得る必要があります。キャンペーンによって着信対応の容量が圧迫されないよう、先に get_concurrency を確認することを検討してください。

ナレッジベースへのファイルアップロードはワークスペース内に制限されます

create_knowledge_base と add_knowledge_base_sources は、ローカルの file_paths を受け取ります。読み取りは、正規化されたパスの前方一致による包含チェックを使って、MCP_WORKSPACE_PATH（未設定の場合はシステムの一時ディレクトリ）内に制限されます。.. によるトラバーサル、サンドボックス外の絶対パス、サンドボックスから外に抜けるシンボリックリンクは、ディスク読み取りの前に拒否されます。読み取りは、まず開いてから検証する方式です。コネクターはファイル記述子を開き、開かれた inode がサンドボックスで許可されたファイルであることを確認してから、その記述子を通じて読み込み、読み込み後に記述子を再確認します。検証と読み取りの間にファイルが差し替え、置換、または変更された場合は、安全側に倒して処理を拒否します。また、50MB の上限は実際に読み取られたバイト数に適用されます。Retell では、アップロードは最大 25 ファイル、各 50MB に制限されています。

動的変数は通話前に順序どおり検証され、その結果が明示されます

create_phone_call、create_web_call、create_batch_call は、通話／セッション／キャンペーンの作成前に、渡された retell_llm_dynamic_variables を現在のプロンプトと照合して検証します。検証は有効な (agent_id, agent_version) をキーとして行われるため、検証対象のプロンプトと実際に実行されるプロンプトが一致します。このチェックによって、明示的に要求された通話がブロックされることはありませんが、失敗が黙って処理されることもありません。一致しない変数、特定できないプロンプト（例：会話フローエージェント）、検索の失敗は、それぞれツールの応答に明示的な warnings として示されます。

削除ツールによる削除は取り消せません

delete_agent、delete_retell_llm、delete_phone_number による削除は取り消せません。エージェントと LLM を削除すると、すべてのバージョンが削除されます。また、電話番号を削除すると解放されるため、同じ番号を再取得できない場合があります。ホストは明示的な確認を求め、事前に関連付けを確認するよう促す必要があります（list_phone_numbers、get_agent）。

設定変更にも確認が必要です

このコネクターでは、エージェントの作成／更新、エージェントの公開、LLM プロンプトの作成／更新、電話番号の更新、ウェブ通話の作成、進行中の通話の停止、API キーの設定も、確認が必要なアクションとしてマークされています。これらは進行中の通話の動作、コスト、または認証情報を変更する可能性があるため、ホストは慎重に扱う必要があります。

ツール（32）

電話通話

• create_phone_call — Retell AI 音声エージェントを使用して発信通話を作成します
• create_web_call — Retell AI エージェントとのブラウザベースの音声通話を作成します
• get_call — 特定の通話の詳細（ステータス、文字起こし、録音）を取得します
• list_calls — エージェント、期間、またはステータスで通話を一覧表示し、絞り込みます
• stop_call — アクティブな通話を終了します
• get_concurrency — 一括発信や短時間の集中発信の前に、アカウントの通話容量の余裕を確認します

一括発信

• create_batch_call — 発信キャンペーンをスケジュールまたは開始します（1つの from_number から複数の宛先へ）

エージェント

• get_agent — 音声エージェントの全設定を取得します
• list_agents — 設定済みの音声エージェントを一覧表示します（ページネーション対応）
• create_agent — 新しい音声エージェントを作成します
• update_agent — 既存のエージェント設定を更新します
• publish_agent — エージェントのドラフトを公開し、通話可能にします
• get_agent_versions — エージェントのバージョン履歴を一覧表示します
• delete_agent — エージェントとすべてのバージョンを完全に削除します

LLM 設定

• update_retell_llm — LLM 設定（プロンプト、あいさつ、モデル）を更新します
• get_retell_llm — LLM 設定全体を取得します
• create_retell_llm — 新しい LLM 設定を作成します
• list_retell_llms — すべての LLM 設定を一覧表示します
• delete_retell_llm — LLM 設定とすべてのバージョンを完全に削除します

ナレッジベース

• list_knowledge_bases — ナレッジベースとその処理状況を一覧表示します
• get_knowledge_base — ナレッジベースのソースとステータスを取得します
• create_knowledge_base — テキスト、URL、またはサンドボックス化されたローカルファイルからナレッジベースを作成します
• add_knowledge_base_sources — 既存のナレッジベースにテキスト、URL、またはファイルを追加します

チャット

• list_chat_agents — 設定済みのチャットエージェントを一覧表示します（ページネーション対応）
• list_chats — エージェントまたは期間でチャットセッションを一覧表示し、絞り込みます
• get_chat — チャットの全文の文字起こしと分析を取得します

検索

• list_voices — 利用可能なテキスト読み上げ音声を一覧表示します
• list_phone_numbers — 登録済みの電話番号を一覧表示します
• get_phone_number — 特定の電話番号の詳細を取得します
• update_phone_number — 電話番号に割り当てられたエージェントを更新します
• delete_phone_number — 電話番号を完全に解放します

設定

• configure_retell_api_key — Retell AI API キーを保存します

ベンダーの非推奨化に関する注意

Retell は、破壊的なエンドポイント変更を短い予告期間で実施します。このコネクターはすでに2回移行しています（0.2.0でのv2/v3通話エンドポイントの変更、および2026-07-31の非推奨化後に list_agents が統合された POST /v2/list-agents に移行）。メンテナーの方は、各リリース前、および以前は動作していたツールから理由不明の404/410が返された後に、Retell の非推奨化に関するお知らせを再確認してください。今後予定されている変更：「Update Call を終了済みの通話に限定」（2026-08-31）。このコネクターは update-call を公開していないため、現時点で対応は不要です。

ライセンス

FSL-1.1-MIT — Functional Source License, Version 1.1。将来的にMITライセンスとなります。このソフトウェアは2030-04-08にMITライセンスへ移行します。