# MCP

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

Source: https://voicast.jp/docs/mcp

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](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` に対応しています。