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.

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.

Open claude.ai → Settings → Connectors
Add custom connector, name it Rymi, and paste this URL:
```
https://mcp.rymi.live/mcp
```
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.

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.

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. Publishable keys (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.

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`.

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

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
`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 (write)

Discovery

Tool	What it does
`list_llm_options`	Full catalog of available LLMs and voices
`list_voices`	Voices only, 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 custom stack's cost (`stt_model`/`llm_model`/`tts_model` + `duration_seconds`) 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 may fall back to a different provider.

Example prompts

Once connected, 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.

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. What restrains them depends on which server you're talking to.

Hosted (mcp.rymi.live) — tools are filtered by your tenant role, the same policy the Studio assistant uses, whether you connect over OAuth or with an API key:

Your role	What's exposed
`owner` / `admin`	Every tool, including account-scoped ones (billing, keys, numbers, DNC)
`member`	Agent-scoped tools only; account-scoped writes are not registered at all

Local (npx @rymi/mcp) — no role filtering. Every tool is exposed 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.

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 your own account access, and use a member-role account for anything that shouldn't touch billing.

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 — Claude (no API key) ​

Quickstart — API key ​

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 ​

Mutating tools and what limits them ​

MCP Server

How it works

Quickstart — Claude (no API key)

Quickstart — API key

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

Mutating tools and what limits them