All pages

Docs

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.

View as Markdown

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). API keys are for the /v1 REST API

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 with the same methods as the dashboard (email sign-in link, Google, GitHub, 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 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#

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) —
update_organization Rename the organization (also used as the addressee on invoices and receipts) owner
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
set_retention Change the environment's retention period for call records and recordings (1, 7, 14 or 30 days; read it with get_retention or list_environments) 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 auto-recharge monthly cap (¥1–¥100,000,000; 0 or null means no cap, and raising or removing it is dashboard-only) owner

Inside an environment#

Pass the environment_id from list_projects. Read tools need viewer, write tools developer.

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
list_agent_templates Agent templates (replace the placeholders, then pass to create_agent) GET /v1/agent-templates
create_agent, update_agent, delete_agent Create, update (new version), delete POST, PUT, DELETE /v1/agents
try_tool Call an agent tool once and return what it answered (status code, body, elapsed time). Pass a saved tool's name (requires agent_id) or an unsaved definition. Not billed and not recorded as a call (see Trying tools) POST /v1/tools/try
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 (filter by channel or tenant) GET /v1/usage
list_connectors, list_connections Available connectors and existing connections (see Connections) GET /v1/connectors, /v1/connections
get_connection One connection (status and settings) GET /v1/connections/{id}
list_connection_options Choices for the settings (only for connectors that have them; URL-and-API-key connections return {}) 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 Create a URL-and-API-key connection (http) POST /v1/connections
create_connect_link A link to the embedded connect page where a business (tenant) connects its own account (15 minutes) POST /v1/tenants/{id}/connect-links
delete_connection Delete a connection DELETE /v1/connections/{id}
get_retention Retention period (days) for call records and recordings GET /v1/retention
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, set_spending_cap and set_retention (when shortening the period) 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.

try_tool really calls the API without asking for confirmation. It calls tools marked "confirm before use" (confirm) without asking too, so the agent should check with you before trying tools that change data, such as booking. Up to 30 per minute per environment.

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

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 firm female voice (female-firm)
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

From CI or a server#

Where a browser cannot be opened, such as CI or a server, call the /v1 REST API with an API key instead of MCP (see the API reference). Create API keys with the MCP tool create_api_key or in the dashboard.

Limits#

  • Signed-in calls are limited to 300 per minute per user (then 429).
  • 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.