# MCP

> Connecting the voicast MCP server to Claude, Claude Code, Cursor, ChatGPT and other AI agents: URL, sign-in (OAuth), the tool list and example prompts.

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

Add the MCP URL, sign in in the browser, and you can do everything from a chat with your AI agent: create organizations and API keys, create agents and tenants, review call results and get a top-up link.

## Endpoint

- **URL**: `https://api.voicast.jp/mcp`
- **Transport**: Streamable HTTP (POST only, stateless)
- **Auth**: browser sign-in (OAuth 2.1 with PKCE). For non-interactive use such as CI, an API key

## Claude Code

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

Open `/mcp` in Claude Code and choose "Authenticate" for voicast. A browser opens; sign in and click "Allow".

## Claude (claude.ai and Claude Desktop)

In Settings → Connectors, choose "Add custom connector", enter `https://api.voicast.jp/mcp`, then "Connect" and sign in in the browser.

## Cursor

Add the server to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for all projects), then sign in from "Login" under Settings › MCP.

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

## VS Code

Add the server to `.vscode/mcp.json` and sign in from the "Start" action that appears.

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

## ChatGPT

Turn on developer mode in settings, create a connector (app) with `https://api.voicast.jp/mcp` as the MCP server URL and OAuth as the authentication, then sign in in the browser.

## Sign-in and consent

Sign in with the same methods as the dashboard (email link or passkey) and click "Allow" on the consent page. What you can do is governed by your role in each organization (owner, admin, developer, viewer), the same as in the dashboard.

- Apps you allowed are listed under Connected apps in your account settings in the dashboard, where you can revoke them.
- Accounts are created in the dashboard. If you do not have one, create it at [https://app.voicast.jp/login](https://app.voicast.jp/login) before adding the MCP URL.
- Access tokens last 1 hour and refresh tokens 30 days; clients refresh them automatically.

## Tools

### Organizations, API keys and billing (signed in)

| Tool | Does | Role needed |
| --- | --- | --- |
| `whoami`, `list_organizations` | Who is signed in, and their organizations | — |
| `create_organization` | Create an organization (with a project and live/test environments) | — |
| `list_projects`, `list_environments` | Projects and environment IDs (`environment_id`) | viewer |
| `list_members` | List members | viewer |
| `invite_member` | Invite a member | admin (owner to invite an owner) |
| `list_api_keys`, `create_api_key`, `revoke_api_key` | List, create and revoke API keys | admin |
| `get_tools_secret`, `rotate_tools_secret` | Read and rotate the tools signing secret | admin |
| `get_billing` | Contract, balance, auto-recharge, this month's minutes and amount, caps | admin |
| `create_topup` | A top-up checkout URL (¥500–¥300,000, excl. tax) | owner |
| `get_billing_portal` | A billing management URL | owner |
| `set_spending_cap` | Lower the monthly cap (¥1–¥100,000,000; 0 or null means no cap, and raising or removing it is dashboard-only) | owner |

### Inside an environment

When signed in, pass the `environment_id` from `list_projects`. Read tools need viewer, write tools developer. When connected with an API key, the tools work inside the key's environment and need no `environment_id`.

| Tool | Does | Same as |
| --- | --- | --- |
| `list_agents`, `get_agent` | List agents, read one | `GET /v1/agents` |
| `list_agent_versions` | List an agent's versions | `GET /v1/agents/{id}/versions` |
| `create_agent`, `update_agent`, `delete_agent` | Create, update (new version), delete | `POST`, `PUT`, `DELETE /v1/agents` |
| `list_tenants`, `get_tenant` | List tenants, read one | `GET /v1/tenants` |
| `create_tenant`, `update_tenant` | Create and update tenants | `POST`, `PATCH /v1/tenants` |
| `rotate_tenant_secret`, `delete_tenant` | Rotate the connection secret, delete a tenant | `POST /v1/tenants/{id}/secret`, `DELETE /v1/tenants/{id}` |
| `list_calls`, `get_call`, `get_call_by_provider`, `get_transcript` | Calls (page with `cursor`) and transcripts. The call's cost is `billed_yen` | `GET /v1/calls` |
| `create_session` | A Web/app session (`client_token`, `ice_servers`) | `POST /v1/sessions` |
| `create_webhook_portal_link` | A link to register webhook endpoints (`locale` for the page language) | `POST /v1/webhooks/portal` |
| `get_usage` | Usage by tenant, day or channel | `GET /v1/usage` |
| `list_connectors`, `list_connections` | Available connectors and existing connections | `GET /v1/connectors`, `/v1/connections` |
| `get_connection` | One connection (status and settings) | `GET /v1/connections/{id}` |
| `list_connection_options` | Choices for the settings (calendars, sheets, apps…) | `GET /v1/connections/{id}/options` |
| `update_connection` | Save a connection's settings (a `needs_setup` connection becomes usable with valid settings) | `PATCH /v1/connections/{id}` |
| `create_connection` | Connect with an API key or URL (`teams`, `shannon_booking`, `http`) | `POST /v1/connections` |
| `create_connect_link` | A connect-page link for a business | `POST /v1/tenants/{id}/connect-links` |
| `delete_connection` | Delete a connection | `DELETE /v1/connections/{id}` |
| `get_integration_guide` | The integration guide (Markdown) | — |

### Tools that need confirmation

`revoke_api_key`, `rotate_tools_secret`, `delete_agent`, `delete_tenant`, `rotate_tenant_secret`, `delete_connection` and `set_spending_cap` do nothing until called with `confirm: true`; without it they return the target and what would happen. The agent should check with you, then call again with the same arguments plus `confirm: true`.

Top-ups (`create_topup`) and billing management (`get_billing_portal`) return URLs. Payment happens in your browser.

### API-key-only tools

With an API key, the organization and environment come from the key, so these tools take no arguments (`create_topup` takes only `amount_yen`).

| Tool | Does | Same as |
| --- | --- | --- |
| `get_billing` | Billing for the key's organization (balance, auto-recharge, per-minute price, payment method) | `GET /v1/billing` |
| `create_topup` | A top-up checkout URL (¥500–¥300,000, excl. tax) | `POST /v1/billing/topups` |
| `get_tools_secret`, `rotate_tools_secret` | Read and rotate the key environment's tools signing secret (rotation needs `confirm: true`) | `GET /v1/tools/secret`, `POST /v1/tools/secret/rotate` |

### Errors

Tool failures (insufficient role, invalid input, not found and so on) come back as results with `isError: true`, containing `code (status): message`, per-argument problems and how to fix them, so the agent can correct itself.

## Example prompts

```
Create a voicast API key for the test environment and put it in .env as VOICAST_API_KEY
```

```
Create a voicast agent for a dental clinic's front desk. Collect name, phone number and purpose, hand off sudden pain to a person, and use the Kore voice
```

```
Create tenant clinic-123 with that agent and store its connection secret in our server config
```

```
Read get_integration_guide, then add voicast TwiML and the post-call transfer to our Twilio incoming-call handler
```

```
List yesterday's calls that ended in handoff and count them by reason
```

```
Make a table of this month's minutes and amounts per tenant
```

```
Check our balance and give me a link to top up ¥10,000
```

## Connecting with an API key (CI and similar)

Where a browser cannot be opened, put an API key from the dashboard in `Authorization`. The tools inside the key's environment (live or test) and the API-key-only tools above are available; the organization, member and API key tools, the billing portal and the monthly cap are not.

```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_…" }
    }
  }
}
```

## Limits

- Signed-in calls are limited to 300 per minute per user (then 429).
- Calls with an API key share the key's limit with `/v1`: 600 per minute (then 429 with `Retry-After`).
- Calls straight from a browser (with an `Origin` header) are refused.
- Supported MCP protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`.