Cortex 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.

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 syslog 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, syslog, is exposed. Use the required action argument to run search, filter, tail, errors, hosts, 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, 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.

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.

syslog 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

syslog filter

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

Common filters match search: hostname, source_ip, severity, app_name, facility, exclude_facility, process_id, from, to, received_from, received_to, 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.

---

syslog tail

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

Parameters

Response

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

---

syslog 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 }
  ]
}

---

syslog 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
    }
  ]
}

---

syslog 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
    }
  ]
}

---

syslog 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: syslog 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.

---

syslog 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": 512,
  "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.

---

syslog 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

---

syslog help

Return markdown documentation for all tools in this toolset.

Parameters: none

---

FTS5 Query Syntax

The syslog search and syslog 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

syslog ai index scans the default local transcript roots ~/.claude/projects and ~/.codex/sessions; syslog ai index --path PATH can scan a known transcript directory or one explicit .jsonl file, and syslog ai add --file FILE imports one file. Recursive scans are limited to ~/.claude/projects, ~/.codex/sessions, or their children; broad roots such as /, $HOME, and the current repo root are rejected before walking. The scanner skips symlinks, counts unsupported non-.jsonl files without parsing them, and streams transcript files line-by-line in bounded SQLite chunks. Use --force to reimport a transcript path from scratch after parser changes, --since RFC3339 to scan only recently modified files, and syslog ai checkpoints --errors plus syslog ai errors to inspect structured scanner failures.

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

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

The watcher runs outside Docker because it needs host access to ~/.claude/projects and ~/.codex/sessions. It writes to the configured live SQLite DB and delegates every stable changed .jsonl file to the same scanner path used by syslog ai add --file FILE. Installing the watcher disables the older polling timer so both helpers do not scan the same files.

The optional polling fallback is still available:

syslog setup ai-index-timer install
syslog setup ai-index-timer check
syslog 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:

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

syslog 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.

syslog 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 syslog 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 ingest entries, source_ip identifies the configured Docker ingest host/container/stream and should be trusted only as far as the configured docker-socket-proxy 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, syslog, 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 syslog binary in ~/.local/bin and then runs syslog 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 COMPOSE_PROJECT_NAME=syslog-jmagar-lab so direct docker compose commands in ~/.cortex/compose target the same canonical container as syslog compose.

Useful installer controls:

CORTEX_INSTALL_DRY_RUN=1 ./install.sh
CORTEX_INSTALL_PREFIX=/opt/cortex ./install.sh
CORTEX_VERSION=0.25.4 ./install.sh
CORTEX_INSTALL_SKIP_SETUP=1 ./install.sh

Useful setup commands:

syslog setup          # first-run or normal repair
syslog setup check    # inspect only; does not mutate files or start services
syslog setup repair   # repair env/assets and restart the Docker stack
syslog deploy preflight       # clearer alias for setup check
syslog deploy local           # clearer local Compose deploy/reconcile command
syslog deploy local --dry-run # run the deploy preflight without mutating Docker
syslog setup ai-watch-service install  # host-local real-time transcript watcher
syslog 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 syslog binary is on PATH; the installer defaults to ~/.local/bin
• Exports plugin userConfig as CORTEX_* / CORTEX_* environment values
• Runs syslog 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:

• syslog-dr — health check covering MCP, service status, syslog port, fleet drop-ins, and live log flow; tails service logs on failure
• syslog-deploy-dropins — SSH-based one-shot rsyslog drop-in deployment to every host in fleet_hosts
• syslog-redeploy — re-run plugin setup after config or plugin changes
• syslog-logs — Docker Compose service log tailing
• syslog-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 syslog setup path as the one-line installer. You can still build and run the binary locally for development, but automated deployment is Compose-only.

syslog 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
• TCP :3100 for the MCP HTTP API

Local build

Requires Rust 1.86+.

cargo build --release
./target/release/syslog 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 NO_AUTH=true only for local development on loopback binds.

Gateway-protected no-auth — on non-loopback binds, set both 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.

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 disabled by default. When enabled, it is mounted under /api/* on the same HTTP listener and requires a separate bearer token.

Syslog listener

Docker socket-proxy ingest

Optional pull-based Docker log ingestion keeps each remote host on its normal Docker logging driver and has cortex read container stdout/stderr through read-only docker-socket-proxy endpoints. This avoids configuring Docker's daemon-level syslog driver and does not block container startup when cortex is down.

The hosts file uses this shape:

[[hosts]]
name = "edge-host-a"
base_url = "http://edge-host-a:2375"
allow_insecure_http = true

[[hosts]]
name = "app-host-b"
base_url = "http://app-host-b:2375"
allow_insecure_http = true

The docker-socket-proxy side only needs read access to containers, events, ping, and version endpoints: CONTAINERS=1, EVENTS=1, PING=1, VERSION=1, POST=0. CONTAINERS=1 exposes the broader read-only Docker container API to anything that can reach the proxy, so bind it only on a trusted private network, firewall it to cortex, or put it behind authenticated TLS. Plain http:// endpoints require allow_insecure_http = true in the hosts file so that this trust decision is explicit.

Docker ingest is intentionally not part of the default smoke test because it needs a live docker-socket-proxy-compatible endpoint and container log stream. For integration testing, run cortex with CORTEX_DOCKER_INGEST_ENABLED=true against a disposable docker-socket-proxy or mocked Docker HTTP fixture, emit a unique line from a short-lived container, then verify it with syslog search or mcporter call ... action=search. Container stdout/stderr rows use source_ip=docker://<host>/<container>/<stream>. Container lifecycle rows for actions such as create, start, restart, die, stop, destroy, rename, oom, and health_status:* use source_ip=docker-event://<host>/<container>/<sanitized-action>, facility=docker, and preserve the raw Docker event JSON.

Storage

Container

config.toml

Place config.toml next to the binary (or in the working directory). Environment variables override values set here.

[syslog]
host = "0.0.0.0"
port = 1514
max_message_size = 8192
max_tcp_connections = 512
tcp_idle_timeout_secs = 300

[storage]
db_path = "data/cortex.db"
pool_size = 4
retention_days = 90   # 0 = keep forever
wal_mode = true
max_db_size_mb = 1024
recovery_db_size_mb = 900
min_free_disk_mb = 512
recovery_free_disk_mb = 768
cleanup_interval_secs = 60

[mcp]
host = "0.0.0.0"
port = 3100
server_name = "cortex"
# api_token = "your-secret-token"

[docker_ingest]
enabled = false
reconnect_initial_ms = 1000
reconnect_max_ms = 30000

[[docker_ingest.hosts]]
name = "edge-host-a"
base_url = "http://edge-host-a:2375"
allow_insecure_http = true

---

Security Model

Syslog ingest is unauthenticated by design

The UDP and TCP syslog listeners (port 1514) accept log frames from any reachable host with no authentication. This matches the RFC 3164/5424 syslog protocol design and is intentional for homelab deployments where the network perimeter is the trust boundary.

Consequences:

• hostname in stored records is caller-controlled for vendor formats (CEF/UniFi). Any host on the network can claim any hostname. Use source_ip for trusted origin identification.
• Log injection is possible from any host that can reach port 1514. Do not use cortex for security-critical audit trails without network-level access controls.
• Retention exemption: severity=err and above are excluded from time-based purge. A host flooding with high-severity frames can exhaust disk space.

Mitigations: Bind the syslog port to a specific interface, use a firewall rule to restrict sources, or set CORTEX_ALLOWED_SOURCE_CIDRS (comma-separated CIDR list) to allowlist sending hosts.

MCP API authentication

The MCP query API (port 3100, default loopback) supports two auth modes:

Important: Admin actions such as ack_error, unack_error, and notifications_test require syslog:admin. Static bearer tokens are read-only unless CORTEX_STATIC_TOKEN_ADMIN=true is explicitly set.

The MCP port defaults to 127.0.0.1:3100 (loopback only). To expose it on a network interface, set CORTEX_HOST=0.0.0.0 and configure a TLS-terminating reverse proxy in front of it.

---

Command modes

syslog serve mcp  # UDP/TCP syslog ingest plus HTTP MCP on /mcp
syslog mcp        # query-only MCP stdio transport
syslog setup      # install/repair shared ~/.cortex Docker Compose setup
syslog deploy preflight  # check deploy prerequisites without mutating Docker
syslog deploy local      # reconcile local Compose deployment
syslog stats      # query the SQLite DB directly from the CLI
syslog db status  # inspect SQLite maintenance state
syslog db backup  # create a WAL-safe SQLite backup
syslog compose doctor          # diagnose live Compose/listener ownership
syslog compose status --json   # inspect canonical cortex container/project

Both modes use the same config and environment variable loader. syslog mcp is for local child-process MCP clients that can read CORTEX_DB_PATH; it does not bind network ports or run retention/storage cleanup jobs.

The direct CLI uses the same shared service layer as the MCP tool, so results and validation match the MCP actions without needing an MCP client:

syslog search 'error AND nginx' --hostname proxy --limit 10
syslog tail -n 20 --app-name kernel
syslog errors --from 2026-01-01T00:00:00Z
syslog hosts
syslog correlate --reference-time 2026-01-01T12:00:00Z --window-minutes 10 --severity-min warning
syslog stats --json
syslog db integrity            # run PRAGMA integrity_check
syslog db checkpoint --mode full
syslog db vacuum --pages 1000
syslog compose pull            # pull image for resolved Compose project
syslog compose up              # run docker compose up -d for resolved service
syslog compose restart         # restart resolved service
syslog compose logs --tail 20  # bounded compose logs

_Documentation truncated — see the full README on GitHub._