@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=1 hides every mutating tool (including create_call, batch_call, publish_agent). RYMI_WORKSPACE makes the local server act in that workspace (sent as the Rymi-Workspace header). On the hosted endpoint, send the Rymi-Workspace header on the HTTP request instead. Every tool also takes an optional workspace argument, so one connection can act in any workspace it can reach, such as an agency's client workspaces.

This package speaks stdio only. --transport http was 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.

Related MCP server: VoxMesh

🧰 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.live over OAuth: tools are filtered by role. Account Owner is owner. Account Admin and workspace Admin are admin. Anyone else is member. An owner/admin sees every tool. A member gets agent-scoped tools only, with account-scoped writes (billing, keys, numbers, DNC) left out. RYMI_MCP_READONLY does not apply there.

• A secret key, hosted or local: the server calls GET /v1/keys/self once and lists tools whose scope the key holds. A legacy key lists every tool. A billing write from that list still returns scope_missing.

• Local @rymi/mcp: no OAuth role filter. RYMI_MCP_READONLY=1 hides 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_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.

📖 Documentation

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

📄 License

MIT © Rymi