# MCP Server

Use RoRvsWild from your AI assistant


<div class="alert is-warning">
<b>MCP is a Beta feature (server version `0.1.0`). Endpoints, tools, and arguments may change.</b>
</div>

RoRvsWild provides an MCP Server that lets you discuss your application monitoring data with your AI agents in natural language.

After configuration, your assistant will be able to inspect metrics and provide answers from the comfort of any MCP-compatible editor or agent (*Cursor*, *Claude Code*, *VS Code*, …):

- “What were the slowest endpoints last hour?”
- “Summarize errors since the last deploy.”
- “Compare server load between yesterday and today.”
- “Give me an overview of this app for the last 7 days.”
- …

## What you need

1. **A RoRvsWild account** with at least one monitored application you belong to.
2. **To enable MCP for each app** you want to query (Application **Settings** in RoRvsWild. MCP is opt-in per app).
3. **Your MCP token** from **Account settings** ([`/account`](/account)), a personal token that starts with `rvw_mcp_`. This is **not** the application API key used by the Ruby gem.
4. **A client that supports MCP over HTTP** (*Cursor*, *Claude Code*, *VS Code*, *Windsurf*, or any other MCP-compatible editor).

## Authentication

One MCP connection authenticates **you**, not a single application. Pass your token as a Bearer header:

```
Authorization: Bearer rvw_mcp_…
```

Copy the token from **Account settings** ([`/account`](/account)). Use **reset** there if you need to rotate it (update your editor config afterward).

**Note:** The application **API key** (on each app’s settings page) is only for the RoRvsWild gem and ingestion API. It does **not** work on `/mcp`.

**Team access:** If you are removed from a team, access to that application’s data stops on the next tool call. You do not need to revoke or reset your MCP token.

## Choosing an application

Most tools need to know **which app** to query. You have three ways to specify it:

1. **`list_applications`**: Call this first (no arguments). It returns a Markdown table of your apps with id, MCP enabled, operational status, and recent throughput.
2. **`application` argument**: Pass an app **id** (e.g. `42`) or **name** (e.g. `My App Production`) on any data tool.
3. **Automatic default**: If you have exactly **one** MCP-enabled app, you can omit `application` and the server picks it for you.

If you have several MCP-enabled apps and omit `application`, the tool returns an error listing your apps. Ask the assistant to call `list_applications` or name the app explicitly.

Example prompts that work well with multiple apps:

- “Call `list_applications`, then show errors for **My App Production** in the last 24 hours.”
- “Using application id `42`, what were the slowest requests in the last hour?”

## Configuration

All editors support MCP over HTTP, but the config format varies slightly. Replace `<rvw_mcp_token>` with the token from **Account settings** ([`/account`](/account)).

**Recommended: global (personal) config.** Your MCP token identifies **you**, not a repository. Each developer should use their own token in a user-level config file (`~/.cursor/mcp.json`, etc.). One setup works in every project; pick the app at query time with `list_applications` or the `application` argument.

**Avoid committing project-level config** (`.cursor/mcp.json`, `.vscode/mcp.json`, …) to git: it either leaks someone's personal token or forces every teammate to maintain a gitignored copy of the same file. If you keep a project-level file locally, add it to `.gitignore`.

For team repos, consider a committed **`mcp.json.example`** (token placeholder + link to this page) and document which RoRvsWild application name matches the project in your README or agent rules.

### Cursor

File: `~/.cursor/mcp.json` (recommended), or `.cursor/mcp.json` locally if you prefer project scope (do not commit)

```json
{
  "mcpServers": {
    "rorvswild": {
      "url": "https://www.rorvswild.com/mcp",
      "transport": "streamableHttp",
      "headers": {
        "Authorization": "Bearer <rvw_mcp_token>"
      }
    }
  }
}
```

Then enable the **rorvswild** server: **Settings → Cursor Settings → Customize → MCP** → toggle *rorvswild* on.

### Claude Code

File: `~/.claude.json` (recommended, all projects), or `.mcp.json` at the project root (do not commit). `~/.claude.json` already exists — add the `rorvswild` entry under `mcpServers`; do not replace the whole file.

```json
{
  "mcpServers": {
    "rorvswild": {
      "type": "http",
      "url": "https://www.rorvswild.com/mcp",
      "headers": {
        "Authorization": "Bearer <rvw_mcp_token>"
      }
    }
  }
}
```

Start a new Claude Code session, then run `/mcp` and confirm *rorvswild* is listed.

### VS Code

User-level MCP settings (recommended), or `.vscode/mcp.json` locally (do not commit)

```json
{
  "servers": {
    "rorvswild": {
      "type": "http",
      "url": "https://www.rorvswild.com/mcp",
      "headers": {
        "Authorization": "Bearer <rvw_mcp_token>"
      }
    }
  }
}
```

The server is auto-loaded from the config file; check the MCP panel in VS Code to confirm *rorvswild* is active.

### Windsurf

File: `~/.codeium/windsurf/mcp_config.json` (global only)

```json
{
  "mcpServers": {
    "rorvswild": {
      "serverUrl": "https://www.rorvswild.com/mcp",
      "headers": {
        "Authorization": "Bearer <rvw_mcp_token>"
      }
    }
  }
}
```

The server is auto-loaded from the config file; check the MCP panel in Windsurf to confirm *rorvswild* is active.

### Zed

```json
{
  "context_servers": {
    "rorvswild": {
      "url": "https://www.rorvswild.com/mcp",
      "headers": { "Authorization": "Bearer <rvw_mcp_token>" }
    }
  }
}
```

The server is auto-loaded from the config file; check the Context Servers panel in Zed to confirm *rorvswild* is active.

### Multiple applications

One MCP connection covers **all applications** your account can access. You do **not** need a separate config entry per app, and you do **not** need a different config file per repository.

Use your **global personal config**, then let the assistant pick the app via `list_applications` or the `application` argument. When working in a given codebase, name the app explicitly (“check **My App Production**”, “use application id 42”). Teammates with access to the same RoRvsWild app use the same application name, each with their own token.

## Time ranges (`range`)

Most tools accept a **`range`** string:

| Examples | Meaning |
|---------|---------|
| `15m`, `30m`, `1h`, `3h`, `6h`, `12h`, `24h`, `1d` | Last N minutes/hours/days ending **now** (RoRvsWild subtracts small processing delays where needed). |
| `7d`, `30d`, `31d`, `90d` | Last N **days** ending now. |
| `2025-05-01T00:00:00+02:00..2025-05-06T23:59:59+02:00` | Custom window: **start..end** in a format Ruby can parse. The end is capped to “now” if it lies in the future. |

If a tool does not receive `range`, it uses a sensible default depending on the tool (see below).

**Range limits:** request and job tools accept a **maximum window of 1 day** to keep queries fast. Ranges longer than 24 hours will return an error for those tools; use `24h` or a narrower window instead. Error, deployment, and server tools have no such restriction.

## Tool reference

The assistant calls **tools** on your behalf. Each tool returns **Markdown** text (tables, headings, links) you can read in the chat or open in RoRvsWild for the full UI.

Unless noted, data tools accept an optional **`application`** argument (id or name). Omit it only when you have exactly one MCP-enabled app.

### Applications

| Tool | What it does | Main arguments |
|------|----------------|----------------|
| **`list_applications`** | Lists every application you can access, with MCP enabled, operational, and throughput columns. | *(none)* |

### Overview

| Tool | What it does | Main arguments |
|------|----------------|----------------|
| **`get_application`** | One combined report: requests, jobs, errors, and deployments for the period, like the in-app report view. | `application`, `range` (default **7d**). |

### Requests

| Tool | What it does | Main arguments |
|------|----------------|----------------|
| **`list_requests`** | Top **request groups** (e.g. `UsersController#index`) for the window, ranked by impact. | `application`, `range` (default **1h**, max **24h**), `order` (`total_runtime`, `throughput`, `p95`, `error_rate`), `limit` (1–100, default **5**). |
| **`get_request`** | Deep dive for **one** named request group: volume, time spent, slow sections. | `application`, `name` (required, e.g. controller#action), `range` (default **1h**, max **24h**). |
| **`get_slowest_requests`** | Individual **slow request samples** in the window (not only grouped). | `application`, `range` (default **1h**, max **24h**), optional `name` to filter one group, `limit` (1–50, default **10**). |
| **`get_request_execution`** | Full detail for **one stored request** execution (sections, SQL breakdowns, etc.). | `application`, `id` (numeric id from the app or from list/slowest tools). |

**`order` in plain language:** **`total_runtime`** ≈ “where we spent the most CPU time overall”; **`throughput`** ≈ “most hits”; **`p95`** ≈ “worst tail latency”; **`error_rate`** ≈ “most failures.”

### Background jobs

| Tool | What it does | Main arguments |
|------|----------------|----------------|
| **`list_jobs`** | Top **job classes** for the window (Sidekiq-style names), ranked by impact. | `application`, `range` (default **1h**, max **24h**), same `order` options as requests, `limit` (1–100, default **5**). |
| **`get_job`** | Deep dive for **one** job name. | `application`, `name` (required), `range` (default **1h**, max **24h**). |
| **`get_slowest_jobs`** | Individual **slow job runs**. | `application`, `range` (default **1h**, max **24h**), optional `name`, `limit` (1–50, default **10**). |
| **`get_job_execution`** | Full detail for **one stored job** execution. | `application`, `id` (numeric id). |

### Errors

| Tool | What it does | Main arguments |
|------|----------------|----------------|
| **`list_errors`** | Grouped **similar errors** for the window (like the Errors index). | `application`, `range` (default **24h**), `order` (`times`, `last_occurrence`), `limit` (1–200, default **50**). |
| **`get_error`** | Full detail for **one error** (message, backtrace context, occurrences). | `application`, `id` (numeric id). |

### Deployments

| Tool | What it does | Main arguments |
|------|----------------|----------------|
| **`list_deployments`** | Deployments RoRvsWild recorded in the window. | `application`, `range` (default **30d**), `limit` (1–200, default **50**). |
| **`get_deployment`** | Requests / jobs / errors summary **around one deploy**. | `application`, `id` (deployment id). |

### Servers

| Tool | What it does | Main arguments |
|------|----------------|----------------|
| **`list_servers`** | Overview of monitored **servers** and their metrics for the window. | `application`, `range` (default **24h**). |
| **`get_server`** | Detail for **one server**: load, RAM, disk, etc. | `application`, `id` (server id), `range` (default **24h**). |

### Finding IDs

Numeric **`id`** values for requests, jobs, errors, deployments, and servers appear in RoRvsWild URLs when you drill into an item from the UI, or you can discover them via the corresponding `list_` tools first.

## Tips for good answers

- If you have **multiple apps**, start with **`list_applications`** or name the **`application`** explicitly.
- Name the **time range** (“last hour”, “since deploy”, “past 7 days”) so the assistant picks a matching `range`.
- Ask for **lists first**, then drill in with `get_*` tools using `id` or `name`.