raymon

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):

raymon

2. Have the user add the MCP server to their agent harness. Example for Codex CLI:

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:

raymon --demo

Remote setup (recommended: require auth)

1. Start Raymon on the remote server (no TUI, bind to all interfaces, require token):

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:

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 uuids.
• Fetch details: raymon.get_entries
  • Use to retrieve full payloads once you have one/more uuids.

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:

{
  "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:

{
  "types": ["error", "exception"],
  "colors": ["red"]
}

types and colors may also be comma-separated strings, such as "error,exception".

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:

{ "uuids": ["<uuid>"] }

Legacy/single form may work as:

{ "uuid": "<uuid>" }

String values may also accept a comma-separated UUID list:

{ "uuids": "<uuid-1>,<uuid-2>" }

In comma-separated string form, whitespace in each UUID token is ignored.

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.