Ravi

Ravi MCP Server

What Is the Ravi MCP Server?

The Ravi MCP server (@ravi/mcp-server) is a Model Context Protocol server that exposes Ravi's full identity toolkit as MCP tools. Any MCP-compatible agent runtime — Claude Code, Codex, Gemini, or a custom orchestrator — can call Ravi tools directly from its tool loop without shelling out to the CLI.

Agent runtime → MCP client → @ravi/mcp-server → Ravi API

This is the preferred integration path for orchestrators that already have MCP infrastructure (Agent Deck, Dorothy, Claude Desktop), and for agents that need low-latency access to credentials and inbox without subprocess overhead.

Installation

# Install globally
npm install -g @ravi/mcp-server

# Or use via npx (no install required)
npx -y @ravi/mcp-server

Authentication

The MCP server authenticates the same way the CLI does — via the token file at ~/.ravi/auth.json. If you have already run ravi auth login on the machine, the MCP server will use those credentials automatically.

For headless environments (CI, Docker, remote machines), inject the token via environment variable:

RAVI_ACCESS_TOKEN=<your-token> npx -y @ravi/mcp-server

To extract your token for injection:

# On a machine where you've run `ravi auth login`
cat ~/.ravi/auth.json | jq -r '.access_token'

Token expiry: Access tokens expire after 1 hour. For long-running MCP pool processes, mount the full auth.json at ~/.ravi/auth.json so the server can refresh tokens automatically. RAVI_ACCESS_TOKEN injection is best for short-lived jobs.

Configuration

Claude Desktop

Add the Ravi MCP server to your Claude Desktop configuration at ~/.claude/settings.json:

{
  "mcpServers": {
    "ravi": {
      "command": "npx",
      "args": ["-y", "@ravi/mcp-server"]
    }
  }
}

If you need to inject credentials in a headless environment:

{
  "mcpServers": {
    "ravi": {
      "command": "npx",
      "args": ["-y", "@ravi/mcp-server"],
      "env": {
        "RAVI_ACCESS_TOKEN": "<your-token>"
      }
    }
  }
}

Agent Deck (MCP pool)

Agent Deck supports shared MCP servers via Unix socket pooling — one Ravi MCP process serves all sessions, cutting memory overhead by 85–90%. Add Ravi to your Agent Deck config at ~/.agent-deck/config.toml:

[[mcp_servers]]
name    = "ravi"
command = "npx"
args    = ["-y", "@ravi/mcp-server"]
scope   = "global"   # available to all sessions
pool    = true        # share via Unix socket

Dorothy

Add Ravi as Dorothy's 6th MCP server via the shared ~/.claude/settings.json Dorothy reads at launch (see the Dorothy integration guide for full setup).

Generic MCP config

For any MCP-compatible runtime that reads a mcp-servers.json config:

{
  "ravi": {
    "command": "ravi-mcp-server",
    "args": []
  }
}

Or with npx (no global install):

{
  "ravi": {
    "command": "npx",
    "args": ["-y", "@ravi/mcp-server"]
  }
}

Available Tools

Once connected, the following tools are available in the agent's tool loop:

Identity

Tool Description
ravi_identity_list List all provisioned Identities
ravi_identity_create Create a new Identity (provisions email + phone)
ravi_get_info Get the active Identity's email address and phone number

Email

Tool Description
ravi_inbox_email List email threads; pass unread=true for new messages only
ravi_read_email Read all messages in a thread (returns full content + attachments)
ravi_email_compose Compose and send a new email from the Identity's address
ravi_email_reply Reply to an existing message (threaded)
ravi_email_forward Forward a message to a new recipient

SMS

Tool Description
ravi_inbox_sms List SMS conversations; pass unread=true for new messages
ravi_read_sms Read all messages in a conversation (extract OTPs from body text)
ravi_sms_send Send an SMS from the Identity's phone number

Passwords (website credentials)

Tool Description
ravi_passwords_list List all saved credentials (passwords hidden; use get for plaintext)
ravi_passwords_get Retrieve a credential entry with decrypted password
ravi_passwords_create Save a new credential entry (E2E encrypted)
ravi_passwords_update Update an existing credential entry
ravi_passwords_delete Delete a credential entry
ravi_generate_password Generate a strong random password

Secrets (API keys and tokens)

Tool Description
ravi_secrets_list List all secret keys (values hidden)
ravi_secrets_get Retrieve a secret by key name (decrypted)
ravi_secrets_set Store a new secret (E2E encrypted)
ravi_secrets_delete Delete a secret

Contacts

Tool Description
ravi_contacts_list List all contacts
ravi_contacts_search Fuzzy search contacts by name or email
ravi_contacts_get Get a specific contact by UUID
ravi_contacts_create Create a new contact
ravi_contacts_update Update an existing contact
ravi_contacts_delete Delete a contact

Identity Scoping

The MCP server operates against the active Identity — the one set by ravi identity use or the .ravi/config.json in the working directory. For parallel agent fleets where each worker needs its own Identity, set RAVI_CONFIG_DIR per process:

# Worker 1 — scoped to its own config directory
RAVI_CONFIG_DIR=/workspace/agent-1/.ravi npx -y @ravi/mcp-server

# Worker 2 — independent scope
RAVI_CONFIG_DIR=/workspace/agent-2/.ravi npx -y @ravi/mcp-server

See RAVI_CONFIG_DIR and Harness Integration for the full pattern.

Common Patterns

OTP extraction during service signup

An agent can complete a full verification loop without human intervention:

1. ravi_identity_create  → provisions email + phone
2. ravi_get_info         → returns email and phone for form fill
3. [agent fills signup form on external service]
4. ravi_inbox_sms(unread=true)  → polls for OTP (retry in loop)
5. ravi_read_sms         → extracts the verification code
6. [agent submits OTP to complete signup]
7. ravi_passwords_create → stores the new credentials

Credential retrieval at task start

1. ravi_secrets_get("GITHUB_TOKEN")   → fetch API key
2. ravi_passwords_get(<uuid>)         → fetch service login
3. [agent proceeds with full credentials, no env var juggling]

Human approval via email

1. ravi_email_compose    → send approval request to a human
2. ravi_inbox_email(unread=true)  → poll for reply (retry loop)
3. ravi_read_email       → parse APPROVE/DENY from reply body

See the Human Approval guide for a complete example.

Troubleshooting

command not found: ravi-mcp-server Install globally first: npm install -g @ravi/mcp-server. Alternatively use the npx form in your MCP config — it doesn't require a global install.

401 Unauthorized on first tool call The server can't find a valid token. Run ravi auth login on the machine, or inject RAVI_ACCESS_TOKEN via environment variable.

403 Identity not found No active Identity is set. Run ravi identity use <name> or set RAVI_CONFIG_DIR to a directory containing a valid config.json.

Token expiry in long-running pool processes Mount ~/.ravi/auth.json from a machine with active auth rather than using RAVI_ACCESS_TOKEN. The server will refresh tokens automatically from the file.

Next Steps