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.
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
/v1REST API
Claude Code#
claude mcp add --transport http voicast https://api.voicast.jp/mcpOpen /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.
{
"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.
{
"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 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_KEYCreate 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 configRead get_integration_guide, then add voicast TwiML and the post-call transfer to our Twilio incoming-call handlerList yesterday's calls that ended in handoff and count them by reasonMake a table of this month's minutes and amounts per tenantCheck our balance and give me a link to top up ¥10,000From 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
Originheader) are refused. - Supported MCP protocol versions:
2025-11-25,2025-06-18,2025-03-26,2024-11-05.