---
name: raymon
description: Use Raymon’s MCP server to search and inspect Ray-style logs. Use when you need to (1) set up Raymon as an MCP server (local or remote with auth), (2) search stored entries with filters/pagination, or (3) fetch full entry payloads by UUID for debugging/triage.
---

# Raymon MCP

Use Raymon as a lightweight, searchable log store that an agent can query via MCP (Streamable HTTP).

## Generating events (Ray integrations)

Raymon stores *Ray-style* log entries. Those entries are generated by language-specific Ray integrations: install the integration in your app, then call its `ray(...)` helper (or equivalent). The integration sends an HTTP request to the Ray ingest endpoint (default port `23517`).

If Raymon is running on `127.0.0.1:23517`, most integrations work out of the box. If Raymon is on a different host/port, configure the integration to point at Raymon instead of the Ray desktop app.

Supported integrations (install + first dump):

- **PHP** (`spatie/ray`)
  - Install: `composer require spatie/ray`
  - Emit: `ray('Hello from PHP');`

- **JavaScript & Node.js** (`permafrost-dev/node-ray`)
  - Install: `npm install node-ray` (or `yarn add node-ray`, `bun add node-ray`)
  - Emit (Node.js): `import Ray, { ray } from 'node-ray'; await Ray.initSettings(); ray('Hello from JS');`

- **Bash** (CLI wrappers)
  - Pick a CLI sender and follow its README (the Ray docs list `node-ray-cli`, `myray-cli`, `ray-cli`, and the curl-based `raybash`).
  - Aim for a “send a message” command and ensure it targets Raymon’s host/port.

- **Ruby** (`ruby-ray`)
  - Install: add `gem 'ruby-ray'` to your Gemfile and run `bundle install` (or `gem install ruby-ray`)
  - Emit: call the `ray(...)` function.

- **Rust** (`ray-dbg`)
  - Install: `cargo add ray-dbg`
  - Emit: use `ray-dbg` to send Ray-compatible dumps.

- **Python** (`ray-python`)
  - Install: `pip install ray-python`
  - Emit: use the library to send a dump to Ray/Raymon.

- **Go** (`octoper/go-ray`)
  - Install: `go get github.com/octoper/go-ray`
  - Emit: use the library to send a dump to Ray/Raymon.

- **Dart** (`ray_dart`)
  - Install: `dart pub add ray_dart` (or `dart pub global activate ray_dart`)
  - Emit: use the package to send a dump to Ray/Raymon.

Reference: Ray installation + integrations list at `https://myray.app/docs/getting-started/installation`.

## Quickstart (local)

1) Instruct the user to start Raymon locally (HTTP + MCP + TUI):
```bash
raymon
```

2) Have the user add the MCP server to their agent harness. 
Example for Codex CLI:
```bash
codex mcp add raymon --url http://127.0.0.1:23517/mcp
```

If you don’t see any logs yet, run demo mode to generate events:
```bash
raymon --demo
```

## Remote setup (recommended: require auth)

1) Start Raymon on the remote server (no TUI, bind to all interfaces, require token):
```bash
export RAYMON_AUTH_TOKEN="change-me"
RAYMON_ALLOW_REMOTE=1 RAYMON_HOST=0.0.0.0 RAYMON_NO_TUI=1 RAYMON_AUTH_TOKEN="$RAYMON_AUTH_TOKEN" raymon
```

Raymon refuses non-loopback binds without `RAYMON_AUTH_TOKEN` unless `RAYMON_ALLOW_INSECURE_REMOTE=1` is set (avoid this unless the user explicitly accepts the risk).

2) Add it to the agent harness, like in Codex CLI as MCP server:
```bash
codex mcp add raymon --url http://<host>:23517/mcp --bearer-token-env-var RAYMON_AUTH_TOKEN
```

## Tool map (what to call)

Raymon intentionally exposes a small tool surface:

- **Search/list**: `raymon.search`
  - Use to find candidate entries and get their `uuid`s.
- **Fetch details**: `raymon.get_entries`
  - Use to retrieve full payloads once you have one/more `uuid`s.

Some harnesses rename these tools (e.g., “list entries”/“get entry”). If tool names differ, map by behavior: one tool returns *summaries with pagination*; the other returns *full entries with payloads*.

## Workflow: Find the right entry (search → pick UUID)

1) Start with `raymon.search` using the tightest filters you know:
   - `screen`, `project`, `host` reduce noise significantly.
   - Keep `limit` small (e.g. 25–100). Use `offset` to paginate.

Example params:
```json
{
  "query": "Exception",
  "screen": "api",
  "limit": 50,
  "offset": 0
}
```

2) Use `query` effectively:
   - Plain text works well for file names, messages, and identifiers.
   - Regex is supported by wrapping as `/.../` (keep patterns specific to avoid slow/broad matches).

3) Use `types` and `colors` if you need to narrow further:
```json
{
  "types": ["error", "exception"],
  "colors": ["red"]
}
```

4) From results, pick the `uuid` with the right `payload_types` and context.

## Workflow: Inspect details (UUID → payloads → origin)

1) Call `raymon.get_entries` with one or more UUIDs:
```json
{ "uuids": ["<uuid>"] }
```
Legacy/single form may work as:
```json
{ "uuid": "<uuid>" }
```

2) Read the entry payloads:
   - `payloads[*].type` tells you what kind of content it is.
   - `payloads[*].content` holds the actual data.
   - `payloads[*].origin` often includes `file`, `line_number`, and `function_name` for jumping to the source.

3) If you need surrounding context, go back to `raymon.search` and paginate around the hit (`offset`) or refine filters.

## Output discipline (what to report back)

When summarizing for the user, include only the high-signal fields:
- `uuid`, `project`, `host`, `screen`, `payload_types`
- One or two key payload snippets (not the entire blob)
- If present: `origin.file:origin.line_number` and `origin.function_name`

## Guardrails

- Prefer `raymon.search` before fetching details to avoid pulling large payloads blindly.
- Don’t recommend remote exposure without auth; avoid `RAYMON_ALLOW_INSECURE_REMOTE=1`.
- If Raymon returns “invalid regex” or “query too long”, shorten/fix the query and retry with a narrower filter set.