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). 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 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 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.