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 touching the dashboard or writing a single HTTP request.

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

How it works

You (natural language)
    ↓
AI client (Claude, Cursor, etc.)
    ↓  MCP tool calls
mcp.rymi.live  ←  your 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 just describe what you want.

Quickstart

No install needed. Point your client at https://mcp.rymi.live and pass your API key as a Bearer token.

Claude Code (~/.claude.json)Claude Desktop

json

{
  "mcpServers": {
    "rymi": {
      "type": "http",
      "url": "https://mcp.rymi.live/",
      "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/",
      "headers": {
        "Authorization": "Bearer rymi_your_secret_key"
      }
    }
  }
}

Get your API key from the Rymi dashboard → Settings → API Keys.

Run it locally (npm)

Prefer to run the server on your own machine instead of the hosted endpoint? The @rymi/mcp package is a standalone MCP server you can 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.

Claude Desktop / CursorClaude Code (~/.claude.json)

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 / flag	Effect
`RYMI_API_KEY`	Required. Your Rymi secret key.
`RYMI_MCP_READONLY=1`	Restrict to read-only tools — hides every mutating tool, including `create_call`, `batch_call`, and `publish_agent`.
`--transport http`	Serve over HTTP instead of stdio (to self-host a `mcp.rymi.live`-style endpoint).
`RYMI_MCP_PORT`	Port to bind when running with `--transport http`.

Local gating differs from the hosted server

The hosted mcp.rymi.live keeps publish_agent, create_call, and batch_call gated per API key (see Opt-in tools). The local @rymi/mcp server exposes the full write surface by default — those billable and irreversible tools are available unless you start it with RYMI_MCP_READONLY=1. In shared or automated environments, use a read-only key or set that flag.

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

Tool	What it does
`list_agents`	List all your voice agents
`get_agent`	Fetch a single agent's full config
`create_agent`	Create a new voice agent. Supports `supported_languages` (multi-language), STT/LLM/TTS model selection, per-channel fallbacks, and custom endpoints
`update_agent`	Modify an existing agent's config (same fields as create)
`clone_agent`	Duplicate an agent (great for A/B variants)
`delete_agent`	Permanently remove an agent
`apply_agent_changes`	Dry-run a change-set — validates without saving
`validate_agent_publish`	Check if an agent passes all publish requirements
`preview_stack`	Resolve the per-language model stack (STT/LLM/TTS) + blockers/warnings before saving (operator/specialist/executive; not concierge)
`enrich_company`	Auto-generate a company description from a URL
`generate_agent_draft`	Generate a full agent config from a plain-English prompt
`publish_agent`	Make an agent live (opt-in, see below)

Discovery

Tool	What it does
`list_llm_options`	Full catalog of available LLMs and voices
`list_voices`	Just the voices, filterable by `provider` or `model_id` — far smaller payload than `list_llm_options`

Calls (read-only)

Tool	What it does
`list_calls`	Browse all calls across the account
`list_active_calls`	Calls currently in progress
`get_call`	Details, participants, duration, and cost for one call
`get_call_summary`	Post-call summary
`get_call_transcript`	Full transcript
`get_call_recording`	Recording metadata / playback URL
`get_call_queue_stats`	Outbound queue statistics
`reprocess_call`	Re-run post-call intelligence for a call
`list_calls_for_agent`	Call history scoped to one agent

Call control (write)

Tool	What it does
`end_call`	Hang up an in-progress call
`add_call_participant`	Add a participant to a live call (warm transfer / conference)

Numbers, telephony & keys

Tool	What it does
`list_numbers`	All numbers on the account and their attached agent
`register_number`	Register a number, optionally attaching it to an agent
`attach_number`	Route an existing number to an agent
`remove_number`	Remove a number from the account
`telephony_status`	Whether a carrier is connected, and which
`list_telephony_numbers`	Numbers available on the connected carrier
`list_publishable_keys`	Browser-safe keys (prefixes only, never full secrets)

Compliance — Do-Not-Call

Tool	What it does
`list_dnc`	List numbers on the Do-Not-Call registry
`check_dnc`	Check whether numbers are blocked, without adding them (read-only)
`add_dnc`	Add a single number to the registry (write)
`add_dnc_batch`	Add up to 1000 numbers at once (write)
`remove_dnc`	Remove a number, re-enabling outbound to it (write)

Webhooks

Tool	What it does
`list_webhooks`	List registered webhook endpoints
`create_webhook`	Register an endpoint for event delivery (write)
`update_webhook`	Change an endpoint's URL, events, or secret (write)
`delete_webhook`	Remove a webhook endpoint (write)

Knowledge & history

Tool	What it does
`list_knowledge_sources`	RAG sources attached to an agent
`add_knowledge_source`	Add a source from raw text or a URL
`delete_knowledge_source`	Remove a source
`list_agent_changes`	Recorded config-change history
`undo_agent_change`	Revert a single change to its previous value

Insight

Tool	What it does
`get_usage_summary`	Remaining voice minutes, Studio AI usage, post-call usage
`list_agent_templates`	Published template catalog — use a template's `defaults` to seed `create_agent`
`run_evals`	Run the evaluation suite (`synthetic` or `live`)
`list_eval_runs`	Past evaluation runs for an agent
`get_eval_run`	A single run with per-scenario scores

Billing & cost

Tool	What it does
`estimate_call_cost`	Estimate a call's cost for a role/duration before dialing (read-only)
`set_auto_recharge`	Configure automatic balance top-ups (write)
`set_spend_alerts`	Configure spend-threshold and low-balance alerts (write)

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 require a higher agent_role.

Example prompts

Once connected, just talk to your AI client:

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

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:

Tool	Discovers
`list_llm_options`	LLM, STT, TTS, and voice options the current tenant can use
`list_agents`	Existing agents the connected key can see
`get_agent`	The full config + runtime-affecting fields for one agent
`apply_agent_changes`	Whether a proposed change-set would validate (dry-run, no save)
`validate_agent_publish`	Whether an agent passes every publish requirement, with reason codes for any blockers
`list_calls_for_agent`	Recent 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.

Opt-in tools (off by default)

On the hosted mcp.rymi.live server, two classes of tool are disabled by default so an AI can't take an irreversible or billable action without you explicitly opting in. To enable either, contact support@rymi.live or toggle it in your dashboard API key settings.

Tool(s)	Why it's gated
`publish_agent`	Makes an agent immediately callable by end users
`create_call`, `batch_call`	Place real, billable outbound phone calls

Local server is the inverse

The local @rymi/mcp package exposes these tools by default (it trusts whoever can read the RYMI_API_KEY on the machine). Start it with RYMI_MCP_READONLY=1 — or connect a read-only key — to hide every mutating tool at once.

WARNING

Once enabled, these tools have real-world effects — publish_agent goes live to end users, and create_call / batch_call dial real numbers and incur per-minute charges. Only use them in supervised workflows.

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.

MCP Server ​

How it works ​

Quickstart ​

Run it locally (npm) ​

Local server options ​

Available tools ​

Agents ​

Discovery ​

Calls (read-only) ​

Call control (write) ​

Numbers, telephony & keys ​

Compliance — Do-Not-Call ​

Webhooks ​

Knowledge & history ​

Insight ​

Billing & cost ​

Example prompts ​

Capability discovery ​

Opt-in tools (off by default) ​

MCP Server

How it works

Quickstart

Run it locally (npm)

Local server options

Available tools

Agents

Discovery

Calls (read-only)

Call control (write)

Numbers, telephony & keys

Compliance — Do-Not-Call

Webhooks

Knowledge & history

Insight

Billing & cost

Example prompts

Capability discovery

Opt-in tools (off by default)