@rymi/mcp

<div align="center">

@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

</div>

---

🚀 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=1 hides every mutating tool (including create_call, batch_call, publish_agent). This package speaks stdio only. --transport http was removed in 2.0.0 — use the hosted endpoint above, which the local server could never match on auth (it has no OAuth, and no per-key tool gating).

🧰 Tools

<table> <tr><th>Group</th><th>Tools</th></tr> <tr> <td><b>Agents</b></td> <td><code>list_agents</code> · <code>get_agent</code> · <code>create_agent</code> · <code>update_agent</code> · <code>delete_agent</code> · <code>clone_agent</code> · <code>apply_agent_changes</code> · <code>generate_agent_draft</code> · <code>enrich_company</code> · <code>validate_agent_publish</code> · <code>preview_stack</code></td> </tr> <tr> <td><b>Discovery</b></td> <td><code>list_llm_options</code> · <code>list_voices</code></td> </tr> <tr> <td><b>Knowledge & history</b></td> <td><code>list_knowledge_sources</code> · <code>add_knowledge_source</code> · <code>delete_knowledge_source</code> · <code>list_agent_changes</code> · <code>undo_agent_change</code></td> </tr> <tr> <td><b>Insight</b></td> <td><code>get_usage_summary</code> (minutes-based) · <code>list_agent_templates</code> · <code>run_evals</code> · <code>list_eval_runs</code> · <code>get_eval_run</code></td> </tr> <tr> <td><b>Calls</b> _(read-only)</td> <td><code>list_calls</code> · <code>list_active_calls</code> · <code>get_call</code> · <code>get_call_summary</code> · <code>get_call_transcript</code> · <code>get_call_recording</code> · <code>get_call_queue_stats</code> · <code>reprocess_call</code> · <code>list_calls_for_agent</code></td> </tr> <tr> <td><b>Numbers</b></td> <td><code>list_numbers</code> · <code>register_number</code> · <code>attach_number</code> · <code>remove_number</code></td> </tr> <tr> <td><b>Telephony</b> _(read-only)</td> <td><code>telephony_status</code> · <code>list_telephony_numbers</code></td> </tr> <tr> <td><b>Keys</b> _(read-only)</td> <td><code>list_publishable_keys</code></td> </tr> </table>

⚠️ Gated tools

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.live — tools are filtered by your tenant role, on both OAuth and API keys. An owner/admin sees everything; a member gets agent-scoped tools only, with account-scoped writes (billing, keys, numbers, DNC) never registered. RYMI_MCP_READONLY does not apply there.
• Local @rymi/mcp — no role filtering. Full write surface unless you start it with RYMI_MCP_READONLY=1, which hides every mutating tool at once. That flag is set by whoever starts the server, so it guards a local run you configure, not a key you hand out.

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.

<details> <summary><b>Configuration reference</b></summary>

<br>

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_languages to every BCP-47 tag the agent should handle, e.g. ["hi-IN","en-US"]. The primary language is 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 optionally stt_provider/stt_model and tts_provider/tts_model. Realtime LLMs (and Deepgram TTS) carry their own voice, so leave voice empty for those.
• Fallbacks — llm_fallback_, stt_fallback_, tts_fallback_* set a secondary provider/model per channel. Pass null to clear.
• Self-hosted endpoints (Enterprise) — custom_llm_url, custom_voice_url (+ custom_voice_mode), custom_transcriber_url. https:// or wss:// only; null clears.
• persona — note that callerPersonas entries 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.

</details>

📖 Documentation

Full reference and guides: docs.rymi.live/api/mcp

📄 License

MIT © Rymi