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

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

CLI Environment Variables — RAVI_CONFIG_DIR and RAVI_ACCESS_TOKEN reference
Harness Integration — parallel-safe identity dispatch for orchestrators
Production Patterns — Python and TypeScript patterns for agent systems
Agent Deck, Dorothy — orchestrators with MCP pool support