Lumoz MCP Server

MCP server for Lumoz observability data and RCA resolution reporting. Connect it to Claude, Cursor, GitHub Copilot, Codex, or any other MCP-compatible client to query traces, signals, and problems, and to drive RCA generation and fix reporting directly from your AI tool.

Getting an API Key

1. Log in to the Lumoz console.
2. Go to Settings → API Keys (org admin required).
3. Click Create Key, name it (e.g. MCP - my laptop), and save it.
4. Copy the key shown as client_id:client_secret — you won't be able to see the secret again after closing the dialog.

The default scopes granted (read:telemetry, write:telemetry) are sufficient for every tool in this server, including the ones that write RCA feedback and fix reports.

Claude / Cursor / Codex / Copilot Config

Requires uv installed locally — uvx runs the server without a separate install step.

{
  "mcpServers": {
    "lumoz": {
      "command": "uvx",
      "args": ["lumoz-mcp"],
      "env": {
        "LUMOZ_API_KEY": "client_id:client_secret"
      }
    }
  }
}

Paste in the key from the step above and you're done — the server talks to Lumoz's production API by default. Add this block to your client's MCP config file (e.g. Claude Desktop's claude_desktop_config.json, or the equivalent settings file for Cursor/Copilot/Codex), then restart the client.

Tools

• Data: list_services, list_traces, search_traces, get_trace, get_trace_spans, get_span
• Signals: list_signal_definitions, list_signals, get_signal, list_traces_for_signal, list_trace_signals
• Business Tasks: list_business_tasks, list_business_task_signals
• Problems: list_problems, get_problem, list_problem_signals, generate_rca, report_fix, submit_problem_feedback
• RCA: list_rcas, get_rca, submit_rca_feedback
• Eval Suggestions: list_service_eval_suggestions, list_problem_eval_suggestions, get_problem_eval_suggestion

Inventory Discovery

Use list_services() without an environment argument to discover all service and environment combinations visible to the authenticated tenant. Omitting environment is intentional: it returns every service row across all environments.

Hosts should call this first when they need valid service_id and environment values:

{}

Each returned service row includes service_id, service_name, and environment. Pass environment only when you want to filter inventory to one environment. include_summary=true is the exception: summary metrics require a specific environment.

Trace Search

Use search_traces(service_id, query, environment) for natural-language questions about trace content — "traces where the agent refused a refund", "slow checkout flows" — that don't map to a known session/user/agent/tool/ model/Business Task value. For exact-match structured filters, use list_traces instead.

{
  "service_id": "123",
  "environment": "prod",
  "query": "agent refused a refund request",
  "vector_target": "response"
}

vector_target narrows which observed text is embedded and matched:

• all (default) — both the user's input and the agent/model's output.
• request — only the user's input text.
• response — only the agent/model's output text.

Optional exact-match filters narrow results further: agent_name, tools_called, models_used, task_name, outcome, and the boolean had_error. The API rejects unknown filter keys, so only pass the ones you've actually set.

Each result carries the same rich per-trace metadata as list_traces (first_user_input/last_assistant_output, token counts, has_error, Business Task/outcome classification, multi-service participant metrics) plus a relevance_score and keyword_match flag from the search ranking.

Signal Discovery

Use list_signals(service_id, environment) to discover valid signal_key values. Signals are backed by classifier results, but hosts should use the signal vocabulary in tool calls.

Common flows:

{
  "service_id": "123",
  "environment": "prod"
}

• list_traces_for_signal(service_id, signal_key="error_detection", environment=environment) lists traces where the error signal fired.
• list_traces_for_signal(service_id, signal_key="business_task_anomaly", environment=environment) lists traces matching the Business Task anomaly signal.
• list_trace_signals(service_id, trace_id, environment) lists all signals attached to one trace, including error_detection. Each signal's details usually already carries error_message/error_code/span_id.
• get_span(service_id, trace_id, span_id, environment) gets full detail (text fields, exception_stacktraces) for one specific span — use the span_id from a signal's details rather than scanning every span via get_trace_spans.

Use list_signal_definitions() to look up what a signal_key/classifier_key actually means — each row has a human-readable description, category (builtin or custom), match_type, and polarity. It returns the full catalog (built-in signals plus this tenant's custom ones), not just signals that have fired, so call it whenever a problem, RCA, or signal result references a signal_key you need to explain to a user, e.g. while writing up or acting on get_rca output. Pass service_id/environment to narrow custom signals to one service/env; built-ins are always included.

Built-in signals also break down into subtypes — the specific sub-reason a signal fired (e.g. loop_detection → exact_tool_call_loop, retry_storm_loop, reason_act_thrash), each with its own description and default_severity. subtype_source_field names which field on the signal record (primary_subtype or primary_event_key) holds the value to match against a subtype's key. When a signal record has a subtype, quote that subtype's description instead of the classifier's general one — it explains the actual mechanism, not just the category.

Business Task Discovery

Use list_business_tasks(service_id, environment) to discover a service's registered Business Tasks and their rollup stats for the range (trace_count, success/failure/pending, tokens, p50 latency, models, avg_cost_usd, signal_counts). Each row includes task_id, task_name, task_version, and task_description. Its task_id scopes three other tools to that task:

• list_traces(service_id, environment, task_id=...) — that task's traces in a time window (range) with a cap (limit). task_name is also an optional name filter; task_id disambiguates tasks with the same name.
• list_business_task_signals(service_id, task_id, environment) — signal summaries (counts, severity, scores) for that task.
• list_problems(service_id, environment, task_id=...) — problems whose signals were detected in that task.

list_service_eval_suggestions also accepts task_id. search_traces accepts task_name as an exact-match filter. Trace and problem results expose task_id and task_name; nested task details use business_task.

{
  "service_id": "123",
  "environment": "prod"
}

Problem and RCA Discovery

Problems are groups of detected trace signals sharing the same signature. Drill down progressively:

1. list_problems(service_id, environment) — paginated, newest-first, each row includes a latest_rca summary if one has been generated.
2. get_problem(service_id, problem_id, environment) — full detail, including every generated RCA (rcas) and the lifecycle/feedback audit trail (events).
3. get_rca(rca_id, service_id, environment) — the complete RCA writeup (root cause, evidence pattern, recommended fixes), plus the trace signals it covers and its own feedback/lifecycle audit trail (events).

list_rcas(service_id, environment) browses generated RCAs directly, across all problems, without going through list_problems first.

If a problem has no RCA yet, generate_rca(problem_id, service_id, environment) creates one (or returns the existing one if already generated).

Eval Suggestion Discovery

Lumoz can generate coding-agent handoff specs for evals after RCA is available. These tools are read-only: they fetch persisted suggestions but do not create or regenerate them.

Use list_service_eval_suggestions(service_id, environment) as the service-level discovery entry point. It returns compact suggestions plus suggestions_by_problem, so a coding agent can choose a problem before loading the full payload:

{
  "service_id": "123",
  "environment": "prod",
  "classifier_key": "tool_correctness",
  "readiness": "high"
}

If the caller already has a problem ID from list_problems, get_problem, generate_rca, or get_rca, use the problem-scoped tools instead:

• list_problem_eval_suggestions(service_id, problem_id, environment) — compact suggestions for one problem.
• get_problem_eval_suggestion(service_id, problem_id, eval_suggestion_id, environment) — one suggestion's full detail.

The full payload includes the eval spec, trace set, implementation prompt, target frameworks, limitations, and source signal metadata. Coding agents should adapt this payload to the repository's existing test/eval framework rather than assuming a fixed test harness.

Problem and RCA Feedback

submit_problem_feedback and submit_rca_feedback record a thumbs_up or thumbs_down vote (optionally with note/reason) against a problem or an RCA, respectively:

{
  "service_id": "123",
  "rca_id": "rca-1",
  "environment": "prod",
  "vote": "thumbs_down",
  "reason": "Recommended fix didn't address the root cause."
}

RCA Fix Reporting

report_fix marks an existing problem resolved and records the fix description. This is one-way — there is no unresolve/reopen action:

{
  "service_id": "123",
  "problem_id": "problem-1",
  "environment": "prod",
  "description": "Added timeout handling around vector search fallback."
}

Troubleshooting

• environment is required — every tool that scopes to a service needs an explicit service_id/environment on each call; there's no LUMOZ_ENVIRONMENT/LUMOZ_SERVICE_ID fallback. Call list_services() first to find a valid pair, then pass both on subsequent calls.
• Client doesn't pick up the server after editing config — most MCP clients only read their config file at startup; fully restart the client, don't just reload a window.