Logan Mcp Server

OCI Log Analytics MCP Server

An MCP server that connects AI assistants (Claude, Codex, etc.) to OCI Log Analytics. Query, visualize, and export log data through natural language.

Quick Start

1. Install

git clone https://github.com/rishabh-ghosh24/logan-mcp-server.git
cd logan-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -e .

2. Configure

Choose your auth method:

| Method | When to use | Setup | |---|---|---| | instance_principal | Running on an OCI VM (recommended) | [Instance principal setup](#instance-principal-setup) | | config_file | Running on your laptop | Uses ~/.oci/config — OCI CLI setup guide |

# Set your auth method
export OCI_LA_AUTH_TYPE=instance_principal   # or config_file

# Run the interactive setup wizard
oci-logan-mcp --setup

The wizard will prompt for your Log Analytics namespace and default compartment.

Or set environment variables directly:

export OCI_LA_NAMESPACE=your-namespace
export OCI_LA_COMPARTMENT=ocid1.compartment.oc1..xxxxx

3. Connect your AI assistant

> Important: Always use the oci-logan-mcp entry point, not python -m oci_logan_mcp.

Local (server runs on same machine)

Works with Claude Desktop, Claude Code, or any MCP client:

{
  "mcpServers": {
    "oci-log-analytics": {
      "command": "/path/to/logan-mcp-server/venv/bin/oci-logan-mcp",
      "args": ["--user", "firstname.lastname"]
    }
  }
}

Where to put this:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Claude Code: ~/.claude.json or project .mcp.json

Remote VM via SSH

For running on an OCI VM with instance principal auth. This config goes in your local MCP client:

{
  "mcpServers": {
    "oci-log-analytics": {
      "command": "ssh",
      "args": [
        "-i", "~/.ssh/your-key",
        "-o", "StrictHostKeyChecking=no",
        "-o", "ServerAliveInterval=60",
        "-o", "ServerAliveCountMax=3",
        "opc@your-vm-ip",
        "cd /path/to/logan-mcp-server && source venv/bin/activate && oci-logan-mcp --user firstname.lastname"
      ]
    }
  }
}

> SSH keepalive: The ServerAliveInterval=60 and ServerAliveCountMax=3 options send a keepalive packet every 60 seconds and disconnect after 3 missed responses. Without these, idle SSH connections can be silently dropped by firewalls or NAT gateways, causing the MCP server to disconnect unexpectedly.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.logan-mcp]
command = "ssh"
args = ["-i", "~/.ssh/your-key", "-o", "StrictHostKeyChecking=no", "-o", "ServerAliveInterval=60", "-o", "ServerAliveCountMax=3", "opc@your-vm-ip", "cd /path/to/logan-mcp-server && source venv/bin/activate && oci-logan-mcp --user firstname.lastname"]

Codex App

For Windows teammates using Codex App, use the one-time installer in windows-setup/ first instead of manually entering SSH arguments. Package these files together:

Double-Click-to-Install.cmd
logan-mcp.ps1
logan.key
windows-setup.html

The real logan.key is not committed to this repo. Add it locally to the windows-setup/ folder before zipping and sharing the folder with a user.

Double-click Double-Click-to-Install.cmd, enter your username in firstname.lastname format, and let the installer close Codex when prompted. The installer creates a Codex MCP server named logan-mcp, copies the private key to ~/.logan-mcp/, and backs up ~/.codex/config.toml before updating it. At the end, it can close running Codex processes for you so the new MCP config is loaded on the next launch.

Manual Codex App setup is still possible for non-Windows users or advanced troubleshooting.

In the Codex app, go to MCP settings -> Connect to a custom MCP and fill in:

| Field | Value | |---|---| | Name | logan-mcp | | Type | STDIO | | Command to launch | ssh | | Argument 1 | -i | | Argument 2 | /path/to/.ssh/your-key | | Argument 3 | -o | | Argument 4 | StrictHostKeyChecking=no | | Argument 5 | -o | | Argument 6 | ServerAliveInterval=60 | | Argument 7 | -o | | Argument 8 | ServerAliveCountMax=3 | | Argument 9 | opc@your-vm-ip | | Argument 10 | cd /home/opc/logan-mcp-server && source venv/bin/activate && oci-logan-mcp --user firstname.lastname |

Click Save, then start a new Codex session to connect.

> Windows users: Prefer the one-time installer above. If the generated > ssh config connects but immediately disconnects, Windows OpenSSH may not be > handling stdio correctly in that environment. In that case, use PuTTY's > plink.exe fallback in the [Windows setup guide](windows-setup/windows-setup.html).

What You Can Do

| Capability | Tools | Examples | |---|---|---| | Query logs | run_query, run_batch_queries, run_saved_search | Search logs, run multiple queries in parallel, execute saved searches | | Triage diffs | diff_time_windows, pivot_on_entity, ingestion_health, parser_failure_triage, investigate_incident, investigate_and_generate_report, why_did_this_fire, find_rare_events, trace_request_id, related_dashboards_and_searches | Compare a query across two time windows; pull all events for an entity across sources; probe per-source ingestion freshness; surface top parser failures; one-call first-cut investigation orchestrator; run investigation plus report generation; replay a Logan-managed alarm's historical fire window; surface low-frequency field values for a source; search common request-id / trace-id fields across sources; find existing dashboards and saved searches related to a source, entity, or field | | Investigation playbooks | record_investigation, list_playbooks, get_playbook, delete_playbook | Save the current session's audited tool calls as a named playbook, then list, fetch, or delete recorded playbooks | | Reports | generate_incident_report, get_report_delivery_options, list_notification_topics, deliver_report | Convert an investigation result into deterministic Markdown/HTML, then generate a PDF and deliver it through Telegram, ONS email-topic summary, or optional Slack summary | | Explore schema | list_log_sources, list_fields, list_entities, list_parsers, list_labels | Discover what log data is available | | Onboard sources | create_log_source_from_sample | Generate a JSON/NDJSON, CSV, or regex-text parser and source from sample logs, upload the sample workload, and verify parse failures | | Visualize | visualize | Generate pie, bar, line, area, table, tile, treemap, heatmap, histogram charts | | Dashboards | create_dashboard, add_dashboard_tile, list_dashboards, delete_dashboard | Create OCI Management Dashboards with LA widgets, grid layout, and scope filters | | Alerts | create_alert, update_alert, list_alerts, delete_alert | Create OCI-native alarms from LA queries with metric extraction and ONS notifications | | Saved searches | create_saved_search, update_saved_search, list_saved_searches, delete_saved_search | Manage LA saved searches backed by scheduled tasks | | Export | export_results | Export query results to CSV or JSON | | Manage scope | set_compartment, set_namespace, find_compartment, list_compartments | Switch compartments, query across tenancy | | Validate | validate_query, get_query_examples | Check syntax, get curated starter examples by category (included with install) | | Remember | save_learned_query, get_preferences, remember_preference | Save queries for improved future suggestions, learn field preferences and time ranges per log source | | Monitor | test_connection, get_current_context, get_log_summary | Check connectivity, see current config, view log volume |

Investigation Toolkit

ingestion_health — is ingestion even working?

Probe log-source freshness in one call. Classifies every source as healthy, stopped, or unknown based on how recently it last emitted a record. Cheapest signal-quality primitive.

{
  "tool": "ingestion_health",
  "sources": ["Linux Syslog", "Apache Access"],
  "severity_filter": "warn"
}

Returns {summary, checked_at, findings: [...]} where each finding carries status, severity, last_log_ts, age_seconds, and a human-readable message.

Configurable via ingestion_health.stoppage_threshold_seconds (default 600s) and ingestion_health.freshness_probe_window (default last_1_hour) in config.yaml.

create_log_source_from_sample — onboard JSON/NDJSON, CSV, or regex-text logs

Create a custom Log Analytics parser/source from non-sensitive JSON/NDJSON sample lines, CSV content with a header row, or line-oriented text with an explicit regex pattern and ordered capture-field keys. The tool uploads the same sample workload and verifies that upload batch with a 'Parse Failed' check plus per-field populated counts. It is guarded because it creates OCI resources and uploads log content.

{
  "tool": "create_log_source_from_sample",
  "source_name": "BlueCat Edge DNS Logs",
  "sample_logs": ["{\"eventType\":\"query-response\",\"sourceAddress\":\"192.0.2.10\"}"],
  "format": "json_ndjson",
  "log_group_id": "ocid1.loganalyticsloggroup.oc1..example",
  "acknowledge_data_review": true
}

For regex text, use format="regex_text" and provide both regex_pattern and regex_field_keys. regex_field_keys[0] maps to capture group 1, regex_field_keys[1] maps to capture group 2, and so on. v1 regex support is deliberately explicit; it does not infer arbitrary plain-text formats.

{
  "tool": "create_log_source_from_sample",
  "source_name": "App Text Logs",
  "sample_logs": [
    "INFO user=alice ip=192.0.2.10 action=login",
    "WARN user=bob ip=192.0.2.11 action=logout"
  ],
  "format": "regex_text",
  "regex_pattern": "^(\\w+) user=(\\S+) ip=(\\S+) action=(\\S+)$",
  "regex_field_keys": ["severity", "user", "sourceip", "action"],
  "log_group_id": "ocid1.loganalyticsloggroup.oc1..example",
  "acknowledge_data_review": true
}

acknowledge_data_review must be true: the caller is responsible for providing logs that are safe to upload and stripped of secrets, tokens, PII, and customer-sensitive values. Existing parser/source names return CONFLICT unless overwrite=true is explicitly supplied. Verification uses the generated/uploaded 'Upload Name' so parse-failure checks are scoped to this sample workload, not every record in the tenancy, and uses last_30_days by default to avoid false negatives from pasted samples whose event time is older than the upload time.

parser_failure_triage — which parsers are broken?

Surface the top log sources with parse failures, ranked by volume. Returns up to 20 sources, each with failure count, first/last seen timestamps, and up to 3 sample raw lines that failed to parse. Each source has one parser configured, so this tells you which parser needs fixing before investigating an incident.

{
  "tool": "parser_failure_triage",
  "time_range": "last_24_hours",
  "top_n": 10
}

Returns {failures: [...], total_failure_count: N} where each entry carries source, failure_count, first_seen, last_seen, and sample_raw_lines (up to 3).

If the session budget is exhausted between the stats and samples queries, the ranked failure list is preserved and the response adds partial: true, partial_reason: "samples_budget_exceeded" with empty sample_raw_lines on each entry — so you still see which sources are failing even when samples can't be fetched.

investigate_incident — one-call first-cut triage

The flagship. Given a seed Logan query + time range, returns a structured investigation: stopped sources (J1), parser failures (J2), topk anomalous sources vs. the prior equal-length window (A2), with per-source top error clusters (Logan cluster), top entities (host/user/requestid), and a recent-events timeline. Target: ≤20s p95 on dogfood data.

{
  "tool": "investigate_incident",
  "query": "'Event' = 'error'",
  "time_range": "last_1_hour",
  "top_k": 3
}

Returns {summary, seed, ingestion_health, parser_failures, anomalous_sources: [{source, pct_change, top_error_clusters, top_entities, timeline, errors}], cross_source_timeline, next_steps, budget, partial, partial_reasons, elapsed_seconds}.

Investigation intent routing:

• User wording such as "investigate", "investigation mode", "investigator mode", "root cause", "what happened", "likely story", "triage this incident", "troubleshoot", "find the issue(s)", "what is wrong", "diagnose", "what went wrong", "why did this happen", "RCA", and "postmortem" should start with investigate_incident.
• Supporting subagents or manual run_query calls can deepen evidence, but they do not replace investigate_incident.
• If the user expects a written artifact, call generate_incident_report after investigate_incident, or use investigate_and_generate_report to run both steps in one tool call.
• Email delivery is a separate confirmed action: ask whether the user wants OCI Notifications email delivery, resolve/reuse a topic with prepare_report_delivery, ask its final confirmation prompt, then call deliver_report with the returned delivery_confirmation_token.

P0 limitations (documented honestly, not magic):

• Only the seed's pre-pipe search clause is used for drill-down scoping. A seed like 'Event' = 'error' | where Severity = 'critical' investigates all 'Event' = 'error' rows — the where narrowing is dropped for drill-down. Fix: put all scoping in the pre-pipe filter.
• top_k is clamped to [1, 3] — matches the ~21-query budget and ≤20s latency guarantee.
• alarm_ocid seed and NL-to-query description seed are deferred (A6 will own alarm-OCID).
• J1's freshness is evaluated over its configured freshness_probe_window, which may differ from the investigation time_range; the report's ingestion_health.note explains the difference.

Partial responses. A1 never raises BudgetExceededError out of its boundary — instead, the report comes back with partial: true and specific partial_reasons:

• "budget_exceeded" — session budget ran out mid-investigation
• "timeline_omitted" — one or more per-source timeline queries errored
• "entity_discovery_partial" — one or more entity fields weren't valid for a source (InvalidParameter)
• "source_errors" — a non-budget, non-field-variance infrastructure failure occurred somewhere in a per-source branch (cluster query 5xx, unexpected ServiceError in entity discovery, transport timeout, or a whole-branch-level exception). Unlike timeline_omitted, this also covers failures in the cluster/entity sub-phases even if the rest of the branch completed — the sub-phase's empty result is accompanied by an errors entry naming the failure.

Each condition is accompanied by anomalous_sources[*].errors entries describing exactly what went wrong per source.

investigate_and_generate_report — investigation plus report

For investigation-mode requests where the user expects a report, this convenience workflow runs investigate_incident first, then feeds that result to generate_incident_report:

{
  "tool": "investigate_and_generate_report",
  "query": "'Event' = 'error'",
  "time_range": "last_24_hours",
  "top_k": 3,
  "format": "markdown"
}

Returns {status: "report_generated", investigation, report, delivery_options}. It does not send email. Use the returned delivery_options to ask whether the user wants OCI Notifications delivery and whether to reuse a saved topic.

`why_di

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rishabh-ghosh24
• Source: rishabh-ghosh24/logan-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.