Skip to content

MCP Server ​

Control Rymi with natural language. The @rymi/mcp package connects your AI assistant directly to your Rymi account. Create agents, inspect calls, validate configs, and go live without opening the dashboard or writing a single HTTP request.

Works with Claude Desktop, Claude Code, Cursor, Windsurf, or any MCP-compatible client.

Rymi is listed on the official MCP Registry as io.github.rymi-live/rymi-mcp, so clients that browse the registry can find it there.

How it works ​

You (natural language)
    ↓
AI client (Claude, Cursor, etc.)
    ↓  MCP tool calls
mcp.rymi.live  ←  you sign in (OAuth), or pass an API key
    ↓
Rymi API

The MCP server translates your plain-English instructions into typed Rymi API calls. The AI figures out which tools to chain. You describe what you want.

Quickstart: Claude (no API key) ​

Add Rymi as a custom connector and sign in. Nothing to install, no key to paste.

  1. Open claude.ai → Settings → Connectors

  2. Add custom connector, name it Rymi, and paste this URL:

    https://mcp.rymi.live/mcp
  3. Connect, and sign in to Rymi when the browser opens.

Paste the URL exactly, no trailing slash. OAuth identifies the server by that string, and …/mcp/ is a different one.

One-click install, where the client supports it:

Steps for ChatGPT, Windsurf, Grok and other clients are in Connect Rymi to your AI client.

What you're approving

Signing in grants the connector everything you can do in Rymi, acting as you , including placing calls that spend credits, and (if you're an owner or admin) billing and API keys. The consent screen spells this out. Revoke any time from Settings.

Quickstart: API key ​

For clients without OAuth, CI, or scripts. Point at the same host and pass a secret key as a Bearer token.

json
{
  "mcpServers": {
    "rymi": {
      "type": "http",
      "url": "https://mcp.rymi.live/mcp",
      "headers": {
        "Authorization": "Bearer rymi_your_secret_key"
      }
    }
  }
}
json
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "rymi": {
      "type": "http",
      "url": "https://mcp.rymi.live/mcp",
      "headers": {
        "Authorization": "Bearer rymi_your_secret_key"
      }
    }
  }
}

Get your API key from the Rymi dashboard → Settings → API keys. Publishable keys (sb_publishable_… and legacy rymi_pk_…) are rejected; they ship to browsers and never carry tool access.

Run it locally (npm) ​

Run the server on your own machine instead of the hosted endpoint. The @rymi/mcp package is a standalone MCP server you launch with npx. No clone, no build. It talks to the Rymi REST API directly and speaks stdio by default, which is what Claude Desktop, Claude Code, and Cursor expect for a local server.

json
{
  "mcpServers": {
    "rymi": {
      "command": "npx",
      "args": ["-y", "@rymi/mcp"],
      "env": {
        "RYMI_API_KEY": "rymi_your_secret_key"
      }
    }
  }
}
json
{
  "mcpServers": {
    "rymi": {
      "command": "npx",
      "args": ["-y", "@rymi/mcp"],
      "env": {
        "RYMI_API_KEY": "rymi_your_secret_key"
      }
    }
  }
}

The server reads your key from the RYMI_API_KEY environment variable (it exits immediately if it's missing).

Local server options ​

Variable / flagEffect
RYMI_API_KEYRequired. Your Rymi secret key.
RYMI_MCP_READONLY=1Restrict to read-only tools. Hides every mutating tool, including create_call, batch_call, and publish_agent.

stdio only

@rymi/mcp speaks stdio. --transport http and RYMI_MCP_PORT were removed in 2.0.0: the hosted endpoint above serves HTTP, with OAuth and role-based tool gating the local server never had.

Mutating tools are on unless you turn them off

A local @rymi/mcp server exposes the full write surface, including publish_agent, create_call, and batch_call, by default, with RYMI_MCP_READONLY=1 as the single switch that hides them all at once. In shared or automated environments, run it with that flag set. The hosted endpoint instead filters by tenant role. See Mutating tools and what limits them.

Available tools ​

These are the tools your AI can invoke once connected. They cover the full lifecycle: discover → preview → build → attach a number → reach → observe → feed knowledge → audit → measure.

Agents ​

ToolWhat it does
list_agentsShort summary per agent: id, name, persona, languages, STT/LLM/TTS models, publish and pause state. Call get_agent for prompts and the full config
get_agentFetch a single agent's full config
create_agentCreate a new voice agent. Supports supported_languages (multi-language), STT/LLM/TTS model selection, per-channel fallbacks, and custom endpoints
update_agentModify an existing agent's config (same fields as create)
clone_agentDuplicate an agent (great for A/B variants)
delete_agentPermanently remove an agent
apply_agent_changesDry-run a change-set. Validates without saving
validate_agent_publishCheck if an agent passes all publish requirements
preview_stackResolve the per-language model stack (STT/LLM/TTS) + blockers/warnings before saving
enrich_companyAuto-generate a company description from a URL (write)
generate_agent_draftGenerate a full agent config from a plain-English prompt (write)
publish_agentMake an agent live (write)
get_pending_publishOn a phone line from Rymi, the latest held edit and its review status (pending, approved, rejected, stale)

API tools (webhooks) & secrets ​

An agent's API tools (call_webhook bindings) are edited by name, so existing tools are never resent or lost. Edits are saved to the live agent and apply from its next call; each one is logged in list_agent_changes. Header values come back only as {{secrets.NAME}} references; any literal value shows as [redacted].

ToolWhat it does
list_agent_toolsAn agent's tool bindings, with header secrets redacted
add_agent_toolAdd an API tool: https URL, method, purpose, fields, headers, timeout_ms (1000–10000)
update_agent_toolChange one API tool by name. Headers merge by name; omitted ones are kept
remove_agent_toolRemove one API tool by name
list_tool_secretsSecret names and the host each is pinned to (values are never returned)
set_tool_secretStore a secret for headers like x-api-key: "{{secrets.NAME}}". Only sent to its host (sensitive)

Credential headers (authorization, x-api-key, *token*, *secret*) must use a {{secrets.NAME}} reference; a literal key is rejected.

Built-in tool switches ​

Built-in tools are switched on or off per agent. Connected-app tools (calendar, CRM lookup, Freshdesk tickets, WhatsApp, Telegram, shareable assets) are opt-in: connecting the app under Settings → Connectors makes them available, and an agent gets one only when you switch it on. Other agents are not affected. Changes are saved to the live agent and apply from its next call.

ToolWhat it does
set_agent_toolsSwitch tools on or off for one agent. Takes tool ids (lookup_customer, send_whatsapp_message, handoff_to_human, end_call, …) or the groups calendar (all five calendar tools) and tickets

Example prompt: "Turn the calendar off for the Navratri invite agent and keep it on for Isha."

One link per agent that anyone can open and talk to in the browser, billed to your workspace within the limits you set.

ToolWhat it does
get_share_linkThe agent's link: URL, limits, minutes used and remaining (link: null if none)
set_share_linkCreate the link or change it: enabled, minutes_limit (0–6000), max_call_seconds (60–1800), max_concurrent (1–10), calls_per_ip_hour (1–30). New links default to 30 min, 300 s per call, 2 at once, 3 per IP per hour (sensitive)
regenerate_share_linkIssue a new URL; the old one stops working at once (sensitive)

Discovery ​

ToolWhat it does
list_llm_optionsFull catalog of available LLMs and voices
list_voicesVoices only, filterable by provider, model_id, gender or a query on label or name. Returns 50 a page (limit up to 500, offset) with total matches

Calls (read-only) ​

ToolWhat it does
list_callsBrowse all calls across the account
list_active_callsCalls currently in progress
get_callDetails, participants, duration, and cost for one call
get_call_summaryPost-call summary
get_call_transcriptFull transcript
get_call_recordingRecording metadata / playback URL
get_call_queue_statsOutbound queue statistics
reprocess_callRe-run post-call intelligence for a call
list_calls_for_agentCall history scoped to one agent

Call control (write) ​

ToolWhat it does
end_callHang up an in-progress call
add_call_participantAdd a participant to a live call
start_test_number_confirmationOpen WhatsApp confirmation for a shared-test-line destination. Returns a wa.me link and the exact message that phone must send. Does not confirm the number. Needs calls:write
get_test_number_confirmationWhether that number is confirmed for this user, plus any code still waiting. Read-only. Needs calls:read
request_test_number_codeSend a 6-digit WhatsApp code to that number. Returns delivery, expiry, resend cooldown and entry_url, never the code. Needs calls:write
submit_test_number_codeReturn the secure page where the user types the code. Takes no code. Read-only. Needs calls:read

A regular create_call through a personal assistant agent needs personal_call, and the owner's yes first. See Personal assistant calls.

create_call with test: true dials from the shared test number and returns phone_not_confirmed until get_test_number_confirmation reports confirmed: true. The request expires in 10 minutes. Each user can start 20 confirmations a day. One user at a time holds the pending request for a number. Confirmation is stored on the API key's user, the same user the test call checks. These tools cannot submit a code or mark the number confirmed. "Send code instead" stays in Studio, because a correct code can become a login number.

Example prompt: "Confirm +919876543210 for test calls, then place a test call to it from this agent once it is confirmed."

Enter a code securely ​

A verification code is a secret, and anything you type into a chat or a tool call stays in the transcript. So no Rymi tool accepts a code.

  1. The assistant calls request_test_number_code. Rymi sends the code to that phone on WhatsApp.
  2. The assistant gives you entry_url. You can also get it again from submit_test_number_code.
  3. You open the link in a browser signed in to the same Rymi account and type the code there.
  4. The assistant calls get_test_number_confirmation until it reports confirmed: true.

Do not paste the code into the chat, and do not let an assistant read it from your phone. A code lasts 10 minutes and allows 5 attempts. If request_test_number_code returns status: refused, reason says why and retry_after gives the seconds to wait. start_test_number_confirmation still works when codes are unavailable.

Both methods confirm a test-call destination only. They never change your login number or account, are not consent to future calls, and do not place a call. Ask before you call.

Task calls ​

Make a phone call from plain instructions through an opted-in agent (features.task_calls_enabled: true). See Use Rymi from your AI agent.

ToolWhat it does
place_task_callCall a number through an opted-in agent, do one task, and extract up to 20 return_fields. Places a real, billable call
wait_for_callWait up to timeout_s (5 to 240, default 90) for a call and its post-call results, then return status, summary and fields. Returns done: false while the call runs

Cards ​

Some tools come with an interactive card (an MCP App). In a host that renders MCP Apps, such as Claude, ChatGPT or VS Code, the card appears under the tool result. Hosts without MCP Apps support show the same JSON text result as before. Both the hosted server and the npm package serve the cards. Cards follow the host's light or dark theme, and the device setting when the host doesn't say.

CardToolsWhat it shows
Call card (ui://rymi/call-card.html)get_call, create_call, place_task_call, wait_for_callLive: status, an elapsed clock and the transcript as it happens. Finished: a recording player, sentiment, whether the goal was met and its score, the WhatsApp follow-up status, the summary, extracted fields and the full transcript
Voice picker (ui://rymi/voice-picker.html)list_voicesEvery voice with a play button for its preview, a search box and a gender filter. When there are more voices than the first page, search and the filter ask list_voices again, so they cover every voice. Use sends your pick to the chat so the model sets that voice
Agent card (ui://rymi/agent-card.html)get_agent, create_agent, update_agent, clone_agent, validate_agent_publish, publish_agentWhether the agent is live, a draft or has changes not yet live; who it answers as; its speech-to-text, LLM and voice models, with a play button for its voice; recording and consent settings; any publish blockers and warnings; and a link to the agent in Studio
Calls list (ui://rymi/calls-list.html)list_calls, list_calls_for_agent, list_active_callsEach call's status, number, agent, time, how it ended, sentiment and duration. Live calls tick, and the card checks them with get_call every 5 seconds until they end. Click a row to read its summary. Load more fetches the next page
Campaign report (ui://rymi/campaign-report.html)get_campaign, get_campaign_reportThe funnel from contacts to the campaign goal, goal rate, cost and cost per goal in credits, talk time in minutes, answer rate by hour with the best hour marked, outcomes, sentiment and top failure reasons. Refreshes every 15 seconds while the campaign runs, for up to 30 minutes. A link opens the campaign in Studio
Campaign suggestions (ui://rymi/campaign-suggestions.html)list_campaign_suggestions, accept_campaign_suggestionEach suggestion's category, what to change and why, the numbers behind it, and the change itself: a policy change next to the campaign's current value, or the new agent setting. Accept calls accept_campaign_suggestion
Usage and plan (ui://rymi/usage-plan.html)get_usage_summary, get_planVoice minutes left, Studio AI and post-call intelligence quotas as percentage bars, any plan recommendation, and every plan with its monthly price and call discount. Change plan opens billing in Studio

The cards fetch through the host with the same tools you can call: the call card polls get_call every 4 seconds while a call runs, stops after 20 minutes, and after the call ends waits up to 3 more minutes for the summary. Their only other requests load recordings and voice previews from Rymi storage and fonts from Google Fonts.

Some hosts draw a card but don't let it call tools. There the card shows the result it arrived with: a live call card or calls list stops its clocks and says it's a snapshot, and a finished call card still shows the transcript, outcome and recording, because get_call returns them.

Numbers, telephony & keys ​

ToolWhat it does
list_numbersAll numbers on the account and their attached agent
register_numberRegister a number, optionally attaching it to an agent
attach_numberRoute an existing number to an agent
remove_numberRemove a number from the account
telephony_statusWhether a carrier is connected, and which
list_telephony_numbersNumbers available on the connected carrier
get_phone_lineYour phone line from Rymi: status, KYC items still missing, call limits, release date when rental is unpaid
request_phone_lineStart or resume a phone line from Rymi for IN or US and get the Studio onboarding link (write)
list_publishable_keysBrowser-safe keys (prefixes only, never full secrets)

Compliance: Do-Not-Call ​

ToolWhat it does
list_dncList numbers on the Do-Not-Call registry
check_dncCheck whether numbers are blocked, without adding them (read-only)
add_dncAdd a single number to the registry (write)
add_dnc_batchAdd up to 1000 numbers at once (write)
remove_dncRemove a number, re-enabling outbound to it (write)
record_contact_consentRecord voice consent (or a revoke) for a number, with the exact wording the person saw (write)

Compliance settings ​

The workspace's operating country, callee-local calling hours, do-not-call check, voice consent, recording-notice default, and destination countries. Compliance is yours; these settings help. Blocked calls fail with destination_not_allowed, outside_calling_hours, or no_voice_consent. See Compliance settings.

ToolWhat it does
get_compliance_settingsRead the settings, including every country preset (read)
update_compliance_settingsSet operating_country ("IN", or null to clear it) and a partial rules object. A country fills every setting you have not already edited (write)

Example prompt: "Set this workspace's operating country to India, and turn on hours and consent for single calls."

Accounts ​

Over OAuth, your role decides. A secret key lists a tool only when GET /v1/keys/self shows the tool's scope. These four ask for accounts:read or accounts:write. Those strings are not scopes you can put on a key, so a scoped key does not list them. A legacy key does. The REST routes use account_members:read, account_members:write, and workspaces:read. See Accounts.

ToolWhat it does
list_accountsAccounts you belong to, with your role (owner, admin, billing, or none) (read)
list_account_membersPeople in an account and their roles (read)
add_account_memberAdd a person by email as owner, admin, or billing. An Owner can grant owner. An Admin can grant admin or billing (sensitive)
remove_account_memberRemove a person. The last Owner stays (last_owner) (sensitive)

Example prompt: "List my accounts, then invite arvind@example.com to Rymi as billing."

Workspaces ​

A connection starts in the workspace of the key or the person who signed in. To act somewhere else for one request, pass workspace (an id from list_workspaces) to any tool: every tool takes it. An account key may name any workspace in its account. A workspace key that names another workspace gets workspace_forbidden. To move the whole connection, send the Rymi-Workspace header on the hosted server, or set RYMI_WORKSPACE for the local package. See Workspaces.

ToolWhat it does
list_workspacesWorkspaces you can act in, with account_id, account_name, account_role, and the effective role. current marks the one this request is in (read)
create_workspaceA workspace in the current account. You need to be account Owner or Admin. It does not get the free monthly credit. parent must name a workspace in that account (write)
update_workspaceRename it, change operating_country, or set spend_cap_cents_monthly in credits on a workspace that is not the primary (null removes the cap) (write)
delete_workspaceDelete an empty workspace: no agents, numbers, calls or campaigns. Account Owner only. The primary workspace returns cannot_delete_primary. workspace_not_empty includes blockers (sensitive)
get_workspace_usageCalls, minutes, and credits for one calendar month (UTC). Client and Viewer responses omit credits (read)
list_workspace_membersPeople in a workspace and their roles (read)
add_workspace_memberAdd someone by email with role admin, editor, client, or viewer (default client). Someone without a Rymi account gets an invite email (sensitive)
remove_workspace_memberRemove someone's access (sensitive)

Example prompt: "Create a workspace called Acme Workspace in this account, cap it at 5,000 credits a month, and invite arvind@example.com as an editor."

Webhooks ​

ToolWhat it does
list_webhooksList registered webhook endpoints
create_webhookRegister an endpoint for event delivery (write)
update_webhookChange an endpoint's URL, events, or secret (write)
delete_webhookRemove a webhook endpoint (write)

Knowledge & history ​

ToolWhat it does
list_knowledge_sourcesRAG sources attached to an agent
add_knowledge_sourceAdd a source from raw text or a URL
delete_knowledge_sourceRemove a source
list_agent_changesRecorded config-change history
undo_agent_changeRevert a single change to its previous value

Insight ​

ToolWhat it does
get_usage_summaryRemaining voice minutes, Studio AI usage, post-call usage
list_agent_templatesPublished template catalog. Use a template's defaults to seed create_agent
run_evalsRun the evaluation suite (synthetic or live)
run_eval_suiteRun the eval suite across many agents at once and return the aggregate report
list_eval_runsPast evaluation runs for an agent
get_eval_runA single run with per-scenario scores

Campaigns ​

See Campaigns for how campaigns, members and live lead intake fit together.

ToolWhat it does
list_campaignsCampaigns in the workspace, filterable by status
get_campaignOne campaign with its policies and counters
get_campaign_reportOutcomes, goal rate, cost and breakdowns
list_campaign_attemptsIndividual dial attempts and their outcomes
list_campaign_suggestionsImprovement suggestions with their evidence
list_contactsContacts in the workspace
create_campaignCreate a campaign in draft: goal, calling window, retries, concurrency. Places no calls (write)
import_campaign_contactsAdd contacts as members (JSON rows or CSV). Works on a running campaign (write)
launch_campaignStart dialing. Places real calls and incurs charges (sensitive)
pause_campaignStop new dials (write)
resume_campaignResume dialing (sensitive)
accept_campaign_suggestionApply a suggestion as an agent draft or a campaign-policy patch (write)
get_campaign_intakeThe campaign's lead-intake settings and when it last received a lead
set_campaign_intakeCreate the lead-intake URL (shown once) or change assume_voice_consent / default_country (sensitive)
rotate_campaign_intakeIssue a new intake URL; the old one stops at once (sensitive)
disable_campaign_intakeRemove the intake URL (write)

Billing & cost ​

ToolWhat it does
estimate_call_costEstimate a custom stack's cost (stt_model/llm_model/tts_model + duration_seconds) before dialing (read-only)
set_auto_rechargeConfigure automatic balance top-ups (write)
set_spend_alertsConfigure spend-threshold and low-balance alerts (write)
get_planCurrent monthly plan, discount, renewal date, minutes left, the plans on sale, and whether the next plan would have cost less over the last 30 days (read-only)
get_plan_studio_linkStudio billing link for upgrading, downgrading or cancelling a plan. Plan changes happen in Studio, never through MCP (read-only)

Bug reports ​

ToolWhat it does
report_bugReport a bug with a title, description, optional steps, expected and actual behaviour, severity, area, and a linked call_id or agent_id. It goes to the Rymi team as pending_review before anyone works on it. See Bug Reports (write)
list_bug_reportsThe workspace's bug reports, newest first, with their status: pending_review, approved, in_progress, fixed (with fix_ref), rejected or duplicate. Filter by status (read-only)

Multi-language agents

To build a bilingual agent, pass supported_languages (e.g. ["hi-IN", "en-US"]) to create_agent. Call preview_stack first to confirm the language set resolves to a valid model stack. Some languages may fall back to a different provider.

Example prompts ​

Once connected, talk to your AI client:

Report a bug

"The Hindi agent cut off mid-sentence on my last call. Report it as a bug."

The AI will chain: list_calls → report_bug (with the call_id)


Build an agent from scratch

"Create a receptionist agent for BrightSmile Dental. Warm and professional tone. Grab the company info from brightsmile.example.com."

The AI will chain: list_llm_options → enrich_company → generate_agent_draft → create_agent


Tweak an existing agent

"Switch my Support agent to the Charon voice and update it to GPT-4o."

The AI will chain: list_agents → apply_agent_changes → update_agent


Validate before going live

"Is my agent abc-123 ready to publish?"

The AI calls: validate_agent_publish → surfaces any missing fields or config issues


Call people who sign up on a form

"Make an outbound campaign for agent abc-123 that calls between 9 AM and 8 PM India time, and give me a URL my subscribe form can post to. The form collects consent and 10-digit numbers."

The AI chains: create_campaign → launch_campaign (after you confirm) → set_campaign_intake with assume_voice_consent: true and default_country: "IN", then hands you the URL once


Share an agent for testing

"Turn on a public link for agent abc-123 with 120 free minutes."

The AI calls: get_share_link → set_share_link with enabled: true, minutes_limit: 120


Make a phone call as one step of a task

"Call +919812345678 for Sharma Clinic using agent abc-123. Confirm tomorrow's 10 AM appointment and ask how many people are coming. Give me booked and party_size."

The AI finds an agent with features.task_calls_enabled: true via list_agents, then chains: place_task_call → wait_for_call, and repeats wait_for_call until it returns done: true


Voice agents creating voice agents

A deployed Rymi agent with this MCP wired in can respond to a caller in real time: "Set up a new booking agent for my dental clinic" → the agent calls create_agent directly. No human in the loop required.

Capability discovery ​

Before mutating an agent, ask the server what is allowed. Each of these is a read-only call, safe to chain from any prompt:

ToolDiscovers
list_llm_optionsLLM, STT, TTS, and voice options the current tenant can use
list_agentsExisting agents the connected key can see
get_agentThe full config + runtime-affecting fields for one agent
apply_agent_changesWhether a proposed change-set would validate (dry-run, no save)
validate_agent_publishWhether an agent passes every publish requirement, with reason codes for any blockers
list_calls_for_agentRecent call history, including statuses and reason codes

The AI should resolve "what can this agent do" by calling get_agent + validate_agent_publish rather than guessing from the prompt. Errors carry machine-readable codes you can branch on; treat the human-readable message as display copy and the code as the routing key.

Mutating tools and what limits them ​

The write tools have real-world effects: publish_agent goes live to end users, and create_call / batch_call dial real numbers and spend credits. create_call with test: true marks that call as a test and uses the shared test number when you omit from_number. The destination must be confirmed on WhatsApp first (start_test_number_confirmation, then get_test_number_confirmation). What restrains them depends on which server you're talking to.

Hosted (mcp.rymi.live), over OAuth: tools are filtered by your role. Account Owner maps to owner. Account Admin and workspace Admin map to admin. Anyone else maps to member.

Your roleWhat's exposed
owner / adminEvery tool, including account-scoped ones (billing, keys, numbers, DNC)
memberAgent-scoped tools only; account-scoped writes are not registered at all

Over a secret key, hosted and local both call GET /v1/keys/self once and list only tools whose scope the key holds. A legacy key lists every tool. Calling a billing write from that list still returns scope_missing. See API keys and scopes.

Local (npx @rymi/mcp): no OAuth role filter. The key's scopes still apply. RYMI_MCP_READONLY=1 hides every mutating tool on top of that. That flag is set by whoever starts the server.

Role is not a sandbox

Role filtering bounds the tool surface, not the credential. An API key or OAuth token remains valid against the REST API directly, where the same permissions apply as any other client. Treat MCP access as equivalent to handing over that credential. For a narrow job, use a workspace key with only the scopes that job needs.

Every tool carries MCP annotations, so a client can tell them apart before it asks you to approve a call. Tools that only read are marked readOnlyHint. Tools that delete, remove or end something (delete_agent, remove_number, end_call and the rest) are marked destructiveHint. The hints are advisory and don't replace the role and scope limits above.

Carrier connect/disconnect and publishable-key creation/revocation are intentionally not available over MCP. They enter credentials and change standing configuration, so do them from the dashboard.