ページの一覧

ドキュメント

MCP

Claude・Claude Code・Cursor・ChatGPT などの AI エージェントから voicast を操作する MCP サーバーのつなぎ方。URL・ログイン(OAuth)・ツールの一覧・頼み方の例。

Markdown で見る

MCP の URL を追加してブラウザでログインすると、AI エージェントとの会話から、組織・API キーの作成、エージェント・テナントの作成、会話の結果の確認、チャージの URL の発行までできます。

接続先#

  • URL: https://api.voicast.jp/mcp
  • 方式: Streamable HTTP(POST だけ。状態を持たない)
  • 認証: ブラウザでのログイン(OAuth 2.1・PKCE)。API キーは /v1 の REST API で使います

Claude Code#

bash
claude mcp add --transport http voicast https://api.voicast.jp/mcp

Claude Code で /mcp を開き、voicast の「Authenticate」を選ぶとブラウザが開きます。ログインして「許可する」を押すと使えます。

Claude(claude.ai・Claude Desktop)#

設定の「コネクタ」→「カスタムコネクタを追加」に https://api.voicast.jp/mcp を入れ、「連携させる」からブラウザでログインします。

Cursor#

プロジェクトの .cursor/mcp.json(すべてのプロジェクトで使うときは ~/.cursor/mcp.json)に足し、Settings › MCP の「Login」からブラウザでログインします。

json
{
  "mcpServers": {
    "voicast": { "url": "https://api.voicast.jp/mcp" }
  }
}

VS Code#

.vscode/mcp.json に足し、表示される「Start」からログインします。

json
{
  "servers": {
    "voicast": { "type": "http", "url": "https://api.voicast.jp/mcp" }
  }
}

ChatGPT#

設定で開発者モードを有効にし、コネクター(アプリ)の作成で MCP サーバーの URL に https://api.voicast.jp/mcp、認証に OAuth を選びます。作成するとブラウザでのログインに進みます。

ログインと許可#

ブラウザでは管理画面と同じ方法(メールのログインリンク・Google・GitHub・パスキー)でログインし、「voicast へのアクセスを許可しますか」で「許可する」を押します。できることは、管理画面と同じロール(owner・admin・developer・viewer)で決まります。

  • 許可したアプリは、管理画面のアカウントの設定の「接続中のアプリ」に並び、そこから取り消せます。
  • アカウントは管理画面で作ります。まだ無いときは https://app.voicast.jp/login で作ってから、MCP の URL を追加します。
  • アクセストークンは 1 時間、リフレッシュトークンは 30 日で、クライアントが自動で更新します。

ツール#

組織・API キー・請求#

ツール できること 要るロール
whoami・list_organizations ログイン中の人と、参加している組織 —
create_organization 組織の作成(プロジェクトと本番・テストの環境ができる) —
update_organization 組織名の変更(請求書・領収書の宛名にも反映) owner
list_projects・list_environments プロジェクトと環境の ID(environment_id) viewer
list_members メンバーの一覧 viewer
invite_member メンバーの招待 admin(owner として招くのは owner)
list_api_keys・create_api_key・revoke_api_key API キーの一覧・作成・取り消し admin
get_tools_secret・rotate_tools_secret ツールの署名シークレットの確認・再発行 admin
set_retention 環境の会話の記録と録音の保存期間の変更(1・7・14・30 日。今の値は get_retention・list_environments) admin
get_billing 契約・残高・オートチャージ・今月の分数と金額・上限 admin
create_topup チャージの URL(500〜300,000 円、税抜) owner
get_billing_portal 請求の管理画面の URL owner
set_spending_cap オートチャージの月の上限を下げる(1〜100,000,000 円。0・null は上限なしで、上げる・外すのは管理画面だけ) owner

環境の中#

list_projects で分かる environment_id を付けて呼びます。見るだけのツールは viewer、変えるツールは developer から使えます。

ツール できること 同じ API
list_agents・get_agent エージェントの一覧・中身 GET /v1/agents
list_agent_versions エージェント設定のバージョンの一覧 GET /v1/agents/{id}/versions
list_agent_templates エージェントのテンプレート(変更する箇所を変更して create_agent に渡す) GET /v1/agent-templates
create_agent・update_agent・delete_agent エージェントの作成・変更(新しいバージョン)・削除 POST・PUT・DELETE /v1/agents
try_tool エージェントのツールを 1回呼んで、相手の応答(状態コード・本文・処理時間)を返す。保存したツールの名前(agent_id が必要)か、保存の前の定義を渡す。会話の料金はかからず、会話の記録に残らない(ツールを試す) POST /v1/tools/try
list_tenants・get_tenant テナントの一覧・1 件 GET /v1/tenants
create_tenant・update_tenant テナントの登録・変更 POST・PATCH /v1/tenants
rotate_tenant_secret・delete_tenant 接続シークレットの再発行・テナントの削除 POST /v1/tenants/{id}/secret・DELETE /v1/tenants/{id}
list_calls・get_call・get_call_by_provider・get_transcript 会話の一覧(続きは cursor)・1 件・文字起こし。利用料は billed_yen GET /v1/calls
create_session Web・アプリの接続(client_token・ice_servers) POST /v1/sessions
create_webhook_portal_link Webhook の送り先を登録する画面のリンク(locale で画面の言葉) POST /v1/webhooks/portal
get_usage 利用の内訳(テナント・日・経路ごと。経路・テナントで絞れる) GET /v1/usage
list_connectors・list_connections 連携先と、作成した連携(連携) GET /v1/connectors・/v1/connections
get_connection 連携 1 つ(状態と設定) GET /v1/connections/{id}
list_connection_options 設定の選択肢(選択肢のある連携先だけ。URL と API キーの連携は {}) GET /v1/connections/{id}/options
update_connection 連携の設定(設定待ちの連携は、正しい設定で使えるようになる) PATCH /v1/connections/{id}
create_connection URL と API キーの連携の作成(http) POST /v1/connections
create_connect_link テナント(事業者)が自分のアカウントで連携する、埋め込みの連携の画面のリンク(15 分) POST /v1/tenants/{id}/connect-links
delete_connection 連携の解除 DELETE /v1/connections/{id}
get_retention 会話の記録と録音の保存期間(日) GET /v1/retention
get_integration_guide 組み込み方の手引き(Markdown) —

確認の要るツール#

revoke_api_key・rotate_tools_secret・delete_agent・delete_tenant・rotate_tenant_secret・delete_connection・set_spending_cap・set_retention(保存期間を短くするとき)は、confirm: true を付けるまで実行せず、対象と何が起きるかを返します。AI エージェントは利用者に確かめてから、同じ引数に confirm: true を付けて呼び直します。

try_tool は確認を求めずに、相手の API を実際に呼びます。「確認してから使う」(confirm)のツールも確認なしで呼ぶので、予約を入れるツールなど書き換えるツールは、利用者に確かめてから呼びます。環境ごとに 1分 30回までです。

チャージ(create_topup)と請求の管理(get_billing_portal)は URL を返します。支払いは利用者がブラウザで行います。

エラー#

ツールの失敗(権限が足りない・入力の誤り・見つからないなど)は、isError: true の結果で、code(状態): 説明 と、引数ごとの誤り・直し方を返します。AI エージェントはこれを読んで直せます。

頼み方の例#

voicast にテストの環境の API キーを作って、.env の VOICAST_API_KEY に入れて
歯科医院の受付のエージェントを作って。名前・電話番号・用件を聞き取り、急な痛みは人に引き継ぐ。声はきっぱりした女性(female-firm)で
テナント clinic-123 を作って、さっきのエージェント設定を割り当てて。接続シークレットはサーバーの設定に保存して
このリポジトリの Twilio の着信の処理に、voicast につなぐ TwiML と、終わったあとの転送を足して(get_integration_guide を読んでから)
昨日の会話で handoff になったものを一覧にして、理由ごとに数えて
今月のテナントごとの利用の分数と金額を表にして
残高を確かめて、1 万円をチャージする URL を出して

CI・サーバーから使う#

ブラウザを開けない CI やサーバーからは、MCP ではなく /v1 の REST API を API キーで呼びます(API リファレンス)。API キーは MCP の create_api_key か管理画面で作れます。

制限#

  • ログインでの呼び出しは、1 人あたり 1 分 300 回までです(超えると 429)。
  • ブラウザから直接の呼び出し(Origin 付き)は受けません。
  • MCP のバージョンは 2025-11-25・2025-06-18・2025-03-26・2024-11-05 に対応しています。