ページの一覧

ドキュメント

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）。CI などの非対話の用途は 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 を選びます。作成するとブラウザでのログインに進みます。

ログインと許可#

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

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

道具#

組織・API キー・請求（ログインのとき）#

道具 できること 要る役割
whoami・list_organizations ログイン中の人と、参加している組織 —
create_organization 組織の作成（プロジェクトと本番・テストの環境ができる） —
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
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 キーでつないだときは、キーの環境の中だけを扱い、environment_id は要りません。

道具 できること 同じ API
list_agents・get_agent 会話の設定の一覧・中身 GET /v1/agents
list_agent_versions 会話の設定の版の一覧 GET /v1/agents/{id}/versions
create_agent・update_agent・delete_agent 会話の設定の作成・変更（新しい版）・削除 POST・PUT・DELETE /v1/agents
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 設定の選択肢（カレンダー・シート・アプリなど） GET /v1/connections/{id}/options
update_connection 連携の設定（設定待ちの連携は、正しい設定で使えるようになる） PATCH /v1/connections/{id}
create_connection API キー・URL でつなぐ連携（teams・shannon_booking・http） POST /v1/connections
create_connect_link 事業者がつなぐ画面のリンク POST /v1/tenants/{id}/connect-links
delete_connection 連携の解除 DELETE /v1/connections/{id}
get_integration_guide 組み込み方の手引き（Markdown） —

確認の要る道具#

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

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

API キーだけの道具#

API キーでつないだときは、組織と環境がキーで決まるので、次の道具を引数なし（create_topup は amount_yen だけ）で使えます。

道具 できること 同じ API
get_billing キーの組織の請求の状態（残高・オートチャージ・1 分の値段・支払い方法） GET /v1/billing
create_topup チャージの URL（500〜300,000 円、税別） POST /v1/billing/topups
get_tools_secret・rotate_tools_secret キーの環境の、道具の署名の鍵の確認・作り直し（作り直しは confirm: true が要る） GET /v1/tools/secret・POST /v1/tools/secret/rotate

エラー#

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

頼み方の例#

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

API キーでつなぐ（CI など）#

ブラウザを開けない用途では、管理画面で作った API キーを Authorization に付けます。キーの環境（本番かテスト）の中の道具と、上の「API キーだけの道具」を使えます。組織・メンバー・API キーの道具と、請求の管理画面・月の上限の道具はありません。

bash
claude mcp add --transport http voicast https://api.voicast.jp/mcp \
  --header "Authorization: Bearer $VOICAST_API_KEY"
json
{
  "mcpServers": {
    "voicast": {
      "url": "https://api.voicast.jp/mcp",
      "headers": { "Authorization": "Bearer vk_test_…" }
    }
  }
}

制限#

  • ログインでの呼び出しは、1 人あたり 1 分 300 回までです（超えると 429）。
  • API キーでの呼び出しは、/v1 と合わせて API キーごとに 1 分 600 回までです（超えると 429 と Retry-After）。
  • ブラウザから直接の呼び出し（Origin 付き）は受けません。
  • MCP の版は 2025-11-25・2025-06-18・2025-03-26・2024-11-05 に対応しています。