Syslog MCP Server

cortex

Rust syslog receiver and MCP server for homelab log intelligence. Ingests syslog over UDP and TCP, stores it in SQLite with FTS5 full-text indexing, and exposes action-based log search, inventory, correlation, status, and analysis tools through MCP, REST, and CLI adapters backed by the shared service layer.

cortex also maintains derived projection tables for future investigation graph features. Those graph tables connect source IPs, claimed hosts, apps, services, containers, AI projects/sessions, and error signatures with evidence, but raw logs, heartbeats, inventory, signatures, and session rows remain the source of truth. The graph projection is rebuildable and intentionally has no ingest triggers. Graph rebuilds use staging tables plus a short serialized swap and record explicit projection status, source watermarks, row counts, runtime metrics, and degraded failure state.

Overview

                    ┌─────────────────────────────────┐
  rsyslog/syslog-ng ─▶  UDP :1514 / TCP :1514          │
  network devices   ─▶  ┌──────────────────────────┐   │
                    │   │  parse → batch writer     │   │
                    │   │  SQLite + FTS5 (WAL mode) │   │
                    │   └──────────────────────────┘   │
  Claude / MCP ◀──── ▶  RMCP HTTP :3100/mcp             │
  local MCP client ◀──▶  syslog mcp query process       │
                    └─────────────────────────────────┘

The daemon listens on a single port for both UDP and TCP syslog (default 1514). All inbound messages are parsed, batched, and written to SQLite with full-text indexing. The MCP HTTP server runs on a separate port (default 3100) and uses RMCP Streamable HTTP in stateless JSON-response mode. Local stdio-only MCP clients can launch cortex mcp, a query-only MCP process that reads the same SQLite database without starting syslog listeners or the HTTP server.

MCP is an exposure surface, not the owner of log-intelligence business policy. Shared defaults, limits, validation, audit identity, correlation behavior, and safety gates should live in SyslogService or service-owned operation models so MCP, REST, and CLI remain consistent.

---

Tools

One MCP tool, cortex, is exposed. Use the required action argument to run search, filter, tail, errors, hosts, map, sessions, search_sessions, abuse, abuse_incidents, abuse_investigate, ai_correlate, usage_blocks, project_context, list_ai_tools, list_ai_projects, correlate, stats, status, apps, source_ips, timeline, patterns, context, get, ingest_rate, silent_hosts, clock_skew, anomalies, compare, compose_status, compose_doctor, unaddressed_errors, ack_error, unack_error, notifications_recent, notifications_test, similar_incidents, ask_history, incident_context, graph, or help.

For the complete action-specific parameter reference, see docs/mcp/SCHEMA.md. For correlation behavior and AI/non-AI inclusion rules, see docs/mcp/CORRELATION.md.

Homelab Inventory

cortex inventory refresh --json collects native Rust inventory into ~/.cortex/inventory and writes:

• normalized/homelab.json — typed cortex.homelab_inventory.v1 cache
• collection-state.json — per-collector status, warnings, timings, and artifact refs
• raw/<run_id>/*.txt — raw-but-redacted Compose and reverse proxy artifacts

cortex inventory status --json reports cache freshness and warnings without opening SQLite. The MCP map action is read-only: it reads the normalized cache and overlays bounded live Cortex host/heartbeat data, but never triggers refresh or returns raw artifact bodies.

map defaults to the inventory snapshot. Graph-backed modes add a typed graph_answer envelope with answer_status, bounded topology rows, safe evidence samples, map follow-up queries, and graph proof queries:

{"action":"map","mode":"host_services","host":"squirts"}
{"action":"map","mode":"domain_routes","domain":"adguard.tootie.tv"}
{"action":"map","mode":"service_dependencies","host":"squirts","service":"swag"}
{"action":"map","mode":"findings","finding_types":["potential_public_route","risky_mounts","collector_health"]}

mode=findings returns bounded topology risk and hygiene findings derived from the graph plus normalized inventory/cache state. Findings include severity, confidence, reason code, affected entities, safe evidence IDs/excerpts, and remediation hints. They deliberately avoid raw config contents, raw artifact or cache paths, credential-bearing upstream URLs, and raw collector warning text; potential_public_route means configured reverse-proxy routing, not proof of unauthenticated public internet exposure.

When the server is running, inventory refresh also projects topology evidence into the investigation graph. The baseline refresh interval is 5 minutes, with local Compose/proxy config watchers as lower-latency refresh triggers. Remote Docker events streams over SSH are opt-in via CORTEX_INVENTORY_REMOTE_DOCKER_EVENTS=true.

On first run, before normalized/homelab.json exists, map and cortex inventory status --json report cache_status: "missing". Run cortex inventory refresh --json to seed ~/.cortex/inventory and clear that missing-cache state.

Prompts

The MCP server also exposes reusable prompts for common infrastructure debugging workflows: infra.incident-triage, infra.host-health, infra.service-outage, infra.security-auth-review, infra.noise-reduction, and infra.agent-change-correlation.

For the prompt catalog and argument reference, see docs/mcp/PROMPTS.md.

MCP Apps query widget

cortex ships one interactive UI surface as progressive enhancement: a simple log-search widget for MCP hosts that support MCP Apps / MCP-UI (_meta.ui.resourceUri). It is a single self-contained HTML resource — no browser build step, no external dependencies, no new server routes.

• Resource URI: ui://cortex/query-widget
• MIME type: text/html;profile=mcp-app
• The cortex tool advertises it via _meta.ui.resourceUri; the widget calls the same cortex tool with action=search over the host bridge and renders the rows in a compact table.
• It is a simple search UI, not a dashboard — query (FTS5) plus hostname, severity, and limit filters.

Non-UI hosts are unaffected. Plain MCP clients keep reading the normal text/JSON tool results; only hosts that detect _meta.ui.resourceUri fetch and render the ui:// resource.

Confirm the wire contract with raw JSON-RPC (no UI host required):

# Widget resource is listed
curl -s -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"resources/list","params":{}}'

# Widget HTML is served with the MCP Apps MIME type
curl -s -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":"ui://cortex/query-widget"}}'

# Search returns both structuredContent (for UI rows) and text (for plain clients)
curl -s -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"cortex","arguments":{"action":"search","query":"error","limit":5}}}'

If CORTEX_TOKEN is set, add -H "Authorization: Bearer $CORTEX_TOKEN". scripts/smoke-test.sh runs these same checks automatically. For the wire-format details see docs/mcp/MCPUI.md.

cortex search

Full-text search across all syslog messages with optional filters. Uses SQLite FTS5 with porter stemming.

Parameters

Response

{
  "count": 3,
  "logs": [
    {
      "id": 12345,
      "timestamp": "2025-01-15T14:30:00Z",
      "hostname": "router",
      "facility": "kern",
      "severity": "err",
      "app_name": "kernel",
      "process_id": null,
      "message": "kernel panic: unable to mount root",
      "received_at": "2025-01-15T14:30:01.123Z",
      "source_ip": "10.0.0.1:51234"
    }
  ]
}

FTS5 examples

query: "kernel panic"           # implicit AND: both terms must appear
query: "OOM AND killer"        # explicit AND
query: "sshd OR pam"           # boolean OR
query: "failed NOT sudo"       # boolean NOT
query: '"connection refused"'  # exact phrase (bypasses stemming)
query: "error*"                # prefix wildcard
query: "restart*"              # matches restart, restarted, restarting

cortex filter

Structured filter-only retrieval for correlation workflows. This action rejects query; use search for FTS5 message-body search.

Common filters match search: host, source, severity, app, facility, exclude_facility, process_id, since, until, received_since, received_until, and limit.

Correlation aliases include source_kind (docker-stream, docker-event, agent-command, shell-history, transcript, claude, codex, gemini), plus tool, project, session_id, container, docker_host, stream, and event_action. source_kind=file-tail filters managed file-tail rows (source_ip prefix file-tail://).

---

cortex tail

Return the N most recent log entries. Equivalent to tail -f across all hosts.

Parameters

Response

Same structure as cortex search: { "count": N, "logs": [...] }.

---

cortex errors

Summarize warnings and errors across all hosts in a time window. Groups by hostname and severity, showing counts. Use this for quick health assessments.

Parameters

Severities included: emerg, alert, crit, err, warning.

Response

{
  "summary": [
    { "hostname": "router",  "severity": "err",     "count": 42 },
    { "hostname": "router",  "severity": "warning",  "count": 17 },
    { "hostname": "storage", "severity": "crit",     "count":  3 }
  ]
}

---

cortex hosts

List all hosts that have sent syslog messages, with first/last seen timestamps and total log counts.

Parameters: none

Response

{
  "hosts": [
    {
      "hostname": "router",
      "first_seen": "2025-01-01T00:00:00.000Z",
      "last_seen":  "2025-01-15T14:30:00.000Z",
      "log_count":  18432
    }
  ]
}

---

cortex sessions

List AI transcript sessions grouped by project, tool, session, and host.

Parameters

Response

{
  "count": 1,
  "sessions": [
    {
      "project": "/home/jmagar/workspace/cortex",
      "tool": "codex",
      "session_id": "019e1506-dc81-7881-9926-4d6d4efda1ac",
      "hostname": "dookie",
      "first_seen": "2026-05-11T03:13:51.745Z",
      "last_seen": "2026-05-11T04:10:00.000Z",
      "event_count": 42
    }
  ]
}

---

cortex correlate

Search for related events across multiple hosts within a ±N minute window around a reference timestamp. Useful for debugging cascading failures. Results are grouped by host and ordered by time.

Parameters

Response

{
  "reference_time": "2025-01-15T14:30:00Z",
  "window_minutes": 5,
  "window_from": "2025-01-15T14:25:00+00:00",
  "window_to":   "2025-01-15T14:35:00+00:00",
  "severity_min": "warning",
  "total_events": 12,
  "truncated": false,
  "hosts_count": 3,
  "hosts": [
    {
      "hostname": "router",
      "event_count": 7,
      "events": [...]
    }
  ]
}

Note on clock skew: cortex correlate uses the timestamp field from the syslog message, which reflects the sending device's clock. If a device clock is skewed, events may fall outside the correlation window. See Time synchronization.

---

cortex stats

Return database statistics including total logs, total hosts, time range covered, logical and physical DB size, free disk, configured thresholds, current write-block status, and runtime ingest observability.

Parameters: none

Response

{
  "total_logs": 284917,
  "total_hosts": 12,
  "oldest_log": "2024-10-15T00:00:01Z",
  "newest_log": "2025-01-15T14:30:00Z",
  "logical_db_size_mb": "312.45",
  "physical_db_size_mb": "328.00",
  "free_disk_mb": "14200.00",
  "max_db_size_mb": 1024,
  "min_free_disk_mb": 0,
  "write_blocked": false,
  "runtime_observability": {
    "syslog_udp_packets_received": 280000,
    "syslog_tcp_connections_active": 3,
    "ingest_entries_enqueued": 284917,
    "ingest_queue_depth": 0,
    "ingest_queue_capacity": 10000,
    "ingest_queue_utilization_pct": "0.00",
    "writer_batches_flushed": 2850,
    "writer_logs_written": 284917,
    "writer_flush_failures": 0,
    "writer_logs_retained": 0,
    "writer_logs_discarded": 0,
    "writer_storage_blocked": false,
    "last_ingest_at": "2025-01-15T14:30:05.123Z",
    "last_write_at": "2025-01-15T14:30:05.400Z",
    "last_error_at": null
  },
  "otlp": {
    "logs_received": 42,
    "decode_errors": 0
  }
}

write_blocked: true means the storage budget is exceeded and new log ingestion is paused. See Storage budget enforcement.

---

cortex status

Return lightweight runtime status without the heavier DB statistics query. Use this for dashboards and doctor checks that need current queue depth, backpressure, writer failure/drop state, listener counters, and last activity timestamps.

Parameters: none

---

cortex help

Return markdown documentation for all tools in this toolset.

Parameters: none

---

The sections above document only the most common actions in detail. For the full 45-action surface with per-action parameters, see docs/mcp/SCHEMA.md or call action=help against a running server.

---

FTS5 Query Syntax

The cortex search and cortex correlate actions use SQLite FTS5 with porter stemming (tokenize='porter unicode61'). Valid query forms:

Limits: max 512 characters, max 16 whitespace-separated terms.

Porter stemming means connect, connected, connecting, and connection all match the query connect. Phrase queries ("...") bypass stemming and require exact token order.

---

Log Schema

Each stored log entry has these fields:

AI transcript indexing

cortex ai index scans the default local transcript roots ~/.claude/projects, ~/.codex/sessions, and ~/.gemini/tmp; cortex ai index --path PATH can scan a known transcript directory or one explicit supported transcript file, and cortex ai add --file FILE imports one file. Recursive scans are limited to ~/.claude/projects, ~/.codex/sessions, ~/.gemini/tmp, or their children; broad roots such as /, $HOME, and the current repo root are rejected before walking. The scanner skips symlinks, counts unsupported files without parsing them, and streams JSONL transcript files line-by-line in bounded SQLite chunks. Gemini chat files are imported from ~/.gemini/tmp/*/chats/session-*.json; when a Gemini file has only projectHash, Cortex stores the project as gemini://project/<hash> so session inventory remains queryable. Use --force to reimport a transcript path from scratch after parser changes, --since RFC3339 to scan only recently modified files, and cortex ai checkpoints --errors plus cortex ai errors to inspect structured scanner failures.

For real-time local Claude/Codex/Gemini transcript ingestion, install the host-local watch service:

cortex setup ai-watch-service install
cortex setup ai-watch-service check
cortex setup ai-watch-service remove

The watcher runs outside Docker because it needs host access to ~/.claude/projects, ~/.codex/sessions, and ~/.gemini/tmp. It writes to the configured live SQLite DB and delegates every stable changed supported transcript file to the same scanner path used by cortex ai add --file FILE; Gemini session-*.json chat files use the same checkpoint and duplicate-suppression path. Installing the watcher disables the older polling timer so both helpers do not scan the same files.

The optional polling fallback is still available:

cortex setup ai-index-timer install
cortex setup ai-index-timer check
cortex setup ai-index-timer remove

Both helpers are deliberately not inside the Docker container. Docker Compose owns only the server/query runtime.

Imported AI transcript messages are scrubbed for known credential/token patterns before storage and FTS indexing. The rows still live in the main logs table, so raw actions such as search, tail, context, and get can return scrubbed transcript text and local ai_transcript_path values within seconds of the transcript write. Scrubbing is best-effort, not a compliance boundary. If storage guardrails cannot recover enough space, indexing fails before committing additional chunks.

Shell and agent command history

Local command history can be correlated with system logs without introducing a separate table:

cortex shell index --path ~/.zsh_history --shell zsh
cortex setup agent-command install
export CLAUDE_CODE_SHELL_PREFIX="$HOME/.local/bin/cortex-agent-command-wrapper"
cortex agent-command ingest-spool --path ~/.local/state/cortex/agent-command.jsonl

cortex shell index imports zsh extended history lines with timestamps and durations as source_kind="shell-history" rows. Plain untimestamped history is skipped because it cannot support time-window correlation.

cortex setup agent-command install writes a small local wrapper for Claude Code's CLAUDE_CODE_SHELL_PREFIX. Claude Code invokes that prefix for spawned shell commands, including Bash tool calls, hook commands, and stdio MCP server startup commands. The wrapper preserves stdio and exit code, appends one scrubbed JSONL record under ~/.local/state/cortex/, and cortex agent-command ingest-spool imports those records as source_kind="agent-command" rows, then truncates the locked spool after a successful import so repeated runs only process new commands. The wrapper records command text, cwd, duration, exit status, agent name, PID, host/user, and CLAUDE_CODE_SESSION_ID when present. It does not capture environment variables, stdout, or stderr by default.

Both command import paths run the AI scrubber plus command-specific redaction for token flags, sensitive assignments, Authorization headers, URL userinfo, curl -u, and private-key blocks before storage. Scrubbing is best-effort, not a compliance boundary.

Important: hostname is taken from the syslog message body, which any LAN device can set to an arbitrary value over UDP. For syslog entries, source_ip is the only trustworthy network identifier. For Docker log entries from the current host-local cortex agent, trust follows the deployed agent host and its local Docker socket access. For legacy central pull entries, source_ip identifies the configured Docker host/container/stream and should be trusted only as far as the explicit remote Docker Engine endpoint and network path are trusted. metadata_json preserves source-specific context for debugging and correlation, but it is not an authorization boundary. Retention cutoffs use received_at (server clock) so that devices with misconfigured clocks cannot cause premature or indefinite log retention.

Severity levels

Ordered from most to least severe:

Facilities

kern, user, mail, daemon, auth, cortex, lpr, news, uucp, cron, authpriv, ftp, ntp, audit, alert, clock, local0–local7.

---

Installation

One-line installer

curl -fsSL https://raw.githubusercontent.com/jmagar/cortex/main/install.sh | sh

The installer puts the host cortex binary in ~/.local/bin and then runs cortex setup. Setup is idempotent and owns the shared host layout:

• ~/.cortex/.env — secrets, ports, Compose interpolation, runtime values
• ~/.cortex/compose/docker-compose.yml — Docker Compose deployment assets
• ~/.cortex/data/cortex.db — SQLite database and WAL/SHM sidecars

Setup writes the compose project name used by the shared host deployment. Existing installations may still use the legacy syslog-jmagar-lab project name for container-label compatibility; prefer cortex compose ... commands because they resolve the live owner before mutating the stack.

Useful installer controls:

CORTEX_INSTALL_DRY_RUN=1 ./install.sh
CORTEX_INSTALL_PREFIX=/opt/cortex ./install.sh
CORTEX_VERSION=<version> ./install.sh
CORTEX_INSTALL_SKIP_SETUP=1 ./install.sh

Useful setup commands:

cortex setup          # first-run or normal repair
cortex setup check    # inspect only; does not mutate files or start services
cortex setup repair   # repair env/assets and restart the Docker stack
cortex deploy preflight       # clearer alias for setup check
cortex deploy local           # clearer local Compose deploy/reconcile command
cortex deploy local --dry-run # run the deploy preflight without mutating Docker
cortex setup ai-watch-service install  # host-local real-time transcript watcher
cortex doctor binary  # check host/container binary freshness

Claude Code plugin (recommended)

Install as a Claude Code plugin. The plugin handles deployment automatically — you choose between server mode (this machine hosts the syslog receiver + MCP server) and client mode (connect to a remote server).

Prompted at install time (via userConfig):

SessionStart hook automation (in server mode):

• Ensures the host cortex binary is on PATH; the installer defaults to ~/.local/bin
• Exports plugin userConfig as CORTEX_* / CORTEX_* environment values
• Runs cortex setup repair, the same setup path used by the one-line installer
• Repairs shared assets under ~/.cortex and removes stale user-level cortex.service units/drop-ins left by older plugin versions
• All idempotent — safe to run on every session

Bundled skills (all 9, from plugins/cortex/skills/):

• cortex — primary log-intelligence skill: search, tail, errors, correlate, stats, and the rest of the MCP action surface
• cortex-dr — health check covering MCP, service status, syslog port, fleet drop-ins, and live log flow; tails service logs on failure
• cortex-deploy-dropins — SSH-based one-shot rsyslog drop-in deployment to every host in fleet_hosts
• cortex-frustration-assessment — analyze an abuse_investigate evidence bundle into a frustration/abuse report
• cortex-logs — Docker Compose service log tailing (the service's own stdout/stderr, not client syslog)
• cortex-redeploy — re-run plugin setup after config or plugin changes
• cortex-report — time-bounded homelab health/log-analysis markdown reports
• cortex-troubleshoot — diagnose connection failures, missing logs, unhealthy containers, and restart loops
• cortex-version-check — check whether the running Docker container matches the local Compose image; add --pull to pull first, otherwise checks only the local image cache

The plugin deploys the server with Docker Compose through the same cortex setup path as the one-line installer. You can still build and run the binary locally for development, but automated deployment is Compose-only.

cortex deploy local is the operator-facing name for the same local Compose-backed reconcile path. It exists so deploy workflows do not need to call a command named setup repair directly.

Docker

git clone https://github.com/jmagar/cortex
cd cortex
cp .env.example .env
# Edit .env — set CORTEX_TOKEN at minimum
docker compose up -d

The container binds:

• UDP :1514 and TCP :1514 for syslog ingestion (published on all interfaces — senders must reach it)
• TCP :3100 for the MCP HTTP API, published on 127.0.0.1 only by default. Set CORTEX_MCP_BIND=0.0.0.0 (plus CORTEX_TOKEN) to expose it; containers on the same Docker network (e.g. the Labby gateway) reach http://cortex:3100 either way.

Local build

Requires Rust 1.86+.

cargo build --release
./target/release/cortex serve mcp

---

Authentication

cortex supports two auth modes, selectable via CORTEX_AUTH_MODE.

Bearer-only (default) — set CORTEX_TOKEN and all /mcp requests must present that token as Authorization: Bearer <token>. No OAuth routes are mounted.

Loopback no-auth — set CORTEX_NO_AUTH=true only for local development on loopback binds.

Gateway-protected no-auth (TrustedGatewayUnscoped) — on non-loopback binds, set both CORTEX_NO_AUTH=true and CORTEX_TRUSTED_GATEWAY_NO_AUTH=true only when an upstream gateway or reverse proxy enforces auth before traffic reaches cortex. This intentionally disables service-local MCP auth and the read/admin scope gates — every caller can run the write actions ack_error, unack_error, and notifications_test. Never combine this mode with host-published ports; keep CORTEX_MCP_BIND=127.0.0.1 (the default) so only the gateway's Docker network path reaches cortex. See docs/SECURITY.md.

OAuth (Google) — set CORTEX_AUTH_MODE=oauth, the OAuth provider env vars, and an allowlisted admin email. The server issues RS256 JWTs after users authenticate via Google. Bearer tokens and OAuth JWTs can coexist (OAuth mode disables the static token by default; set CORTEX_AUTH_DISABLE_STATIC_TOKEN_WITH_OAUTH=false or disable_static_token_with_oauth = false in config.toml for break-glass access).

Both modes leave /health unauthenticated so health probes always work.

See docs/OAUTH.md for full setup instructions, architecture diagram, and operator FAQ.

---

Configuration

Configuration is loaded from three sources in priority order (highest wins):

1. Environment variables
2. config.toml (if present)
3. Built-in defaults

Environment variables

MCP server

Non-MCP API

The plain JSON API is always mounted under /api/* on the same HTTP listener and requires its own bearer token — the server fails to start (on the server path) without it. cortex setup repair generates one if missing.

Syslog listener

Docker log ingest

The current deployment path is the host-local cortex agent. Each deployed agent reads Docker logs from that host's local Docker socket (unix:///var/run/docker.sock) and forwards the normalized rows into cortex. This keeps Docker's normal local logging behavior intact, avoids daemon-level syslog drivers, and does not require exposing a Docker API endpoint on the network.

The CORTEX_DOCKER_* settings below remain as a legacy central pull compatibility mode for explicit remote Docker Engine HTTP endpoints. Use them for fixtures or transitional deployments where cortex itself should connect to a Docker-compatible API. Older deployments used docker-socket-proxy for this endpoint, but that is no longer the recommended homelab path.

Documentation truncated — see the full README on GitHub.