@rymi/mcp
The Rymi MCP server — create and manage AI voice agents from any MCP-capable client.
Point Claude Desktop, Claude Code, Cursor, or a Rymi voice agent at this server and manage your entire voice-agent fleet — agents, calls, numbers, knowledge, and usage — without writing a line of HTTP code.
Documentation · Dashboard · Node SDK · Python SDK
🚀 Two ways to run it
☁️ Hosted — no install, no API key
Add https://mcp.rymi.live/mcp as a custom connector and sign in. In Claude:
Settings → Connectors → Add custom connector. Paste the URL exactly — no
trailing slash, since OAuth identifies the server by that string.
Signing in grants the connector everything you can do in Rymi, acting as you. Revoke any time from Settings.
Clients without OAuth (and CI) can pass a secret key against the same host instead:
{
"mcpServers": {
"rymi": {
"type": "http",
"url": "https://mcp.rymi.live/",
"headers": {
"Authorization": "Bearer rymi_your_secret_key"
}
}
}
}
💻 Local — via npx
Run the server on your own machine — it speaks stdio by default and talks to the Rymi REST API directly. The key is read from the RYMI_API_KEY environment variable.
{
"mcpServers": {
"rymi": {
"command": "npx",
"args": ["-y", "@rymi/mcp"],
"env": {
"RYMI_API_KEY": "rymi_your_secret_key"
}
}
}
}
Options:
RYMI_MCP_READONLY=1hides every mutating tool (includingcreate_call,batch_call,publish_agent).RYMI_WORKSPACEmakes the local server act in that workspace (sent as theRymi-Workspaceheader). On the hosted endpoint, send theRymi-Workspaceheader on the HTTP request instead. Every tool also takes an optionalworkspaceargument, so one connection can act in any workspace it can reach, such as an agency's client workspaces.This package speaks stdio only.
--transport httpwas removed in 2.0.0. Use the hosted endpoint above. The local server has no OAuth. It does filter tools by the key's scopes.
🧰 Tools
⚠️ Gated tools
place_task_call, create_call and batch_call place real, billable outbound calls; publish_agent flips an agent live to end users.
What restrains them depends on which server you're talking to.
- Hosted
mcp.rymi.liveover OAuth: tools are filtered by role. Account Owner isowner. Account Admin and workspace Admin areadmin. Anyone else ismember. Anowner/adminsees every tool. Amembergets agent-scoped tools only, with account-scoped writes (billing, keys, numbers, DNC) left out.RYMI_MCP_READONLYdoes not apply there. - A secret key, hosted or local: the server calls
GET /v1/keys/selfonce and lists tools whose scope the key holds. A legacy key lists every tool. A billing write from that list still returnsscope_missing. - Local
@rymi/mcp: no OAuth role filter.RYMI_MCP_READONLY=1hides every mutating tool on top of the key's scopes. That flag is set by whoever starts the server.
Either way, role filtering bounds the tool surface, not the credential: a key or token stays valid against the REST API directly. Treat MCP access as equivalent to handing over your own account access.
Carrier connect/disconnect and publishable-key creation/revocation are intentionally not exposed over MCP (they enter credentials and change standing configuration) — do those from the dashboard.
⚙️ Configuring an agent
create_agent and update_agent accept the full agent configuration surface. Always call list_llm_options first to get valid model and voice IDs.
Agents created over MCP are custom agents — you choose the model stack and they're billed at component cost + a flat $0.02/min platform fee. (Managed "Rymi-Curated" SKUs are picked from the dashboard.)
- Multi-language / bilingual — set
supported_languagesto every BCP-47 tag the agent should handle, e.g.["hi-IN","en-US"]. The primarylanguageis merged in automatically. The server resolves the per-language model stack for you; some languages may fall back to a different provider. - Model stack — pin
llm_provider+llm_model, and optionallystt_provider/stt_modelandtts_provider/tts_model. Realtime LLMs (and Deepgram TTS) carry their own voice, so leavevoiceempty for those. - Fallbacks —
llm_fallback_*,stt_fallback_*,tts_fallback_*set a secondary provider/model per channel. Passnullto clear. - Self-hosted endpoints (Enterprise) —
custom_llm_url,custom_voice_url(+custom_voice_mode),custom_transcriber_url.https://orwss://only;nullclears. persona— note thatcallerPersonasentries are objects of shape{ type, approach, detectedWhen }, not plain strings.
provider_config is server-derived (recomputed from the resolved stack + supported languages on every write) and is not accepted as an input.
📖 Documentation
Full reference and guides: docs.rymi.live/api/mcp
📄 License
MIT © Rymi
