Authentication Reference -- cortex

July 30, 2026 ยท View on GitHub

Overview

cortex has a single authentication boundary: MCP clients authenticating to the MCP HTTP server. There is no outbound authentication -- cortex is a self-contained syslog receiver with no upstream API dependency.

Bearer token

When CORTEX_TOKEN is set, all requests to /mcp require:

Authorization: Bearer {CORTEX_TOKEN}

Generate a token:

openssl rand -hex 32

Set it in .env:

CORTEX_TOKEN=<generated-token>

CORTEX_API_TOKEN is still accepted as a deprecated compatibility alias when CORTEX_TOKEN is unset.

Authentication middleware

The require_auth middleware in src/mcp/routes.rs validates inbound tokens:

Request -> require_auth middleware -> Route Handler
               |
               v (401)
         Missing/invalid token
  • Returns HTTP 401 with a JSON-RPC error envelope if the token is missing or incorrect:
{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"unauthorized"}}
  • Uses subtle::ConstantTimeEq for token comparison to prevent timing side-channel attacks
  • Applies to /mcp RMCP requests. /health is outside MCP auth.

Unauthenticated endpoints

EndpointMethodPurpose
/healthGETHealth check -- verifies SQLite connectivity, returns {"status": "ok"}

The health endpoint is intentionally unauthenticated so Docker HEALTHCHECK, docker-compose probes, and SWAG liveness checks can reach it without credentials.

No-auth mode

When CORTEX_TOKEN is not set (the default), the MCP endpoint passes through without authentication. This is acceptable for:

  • LAN-only deployments behind a firewall
  • Deployments behind a reverse proxy that handles its own auth (SWAG with Authelia, Cloudflare Access)

When exposed to the internet or untrusted networks, always set CORTEX_TOKEN.

Plugin userConfig integration

When installed as a Claude Code plugin, the token is managed via userConfig in .claude-plugin/plugin.json:

{
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API Token",
      "description": "Bearer token for authenticating MCP requests. Required unless no_auth is true.",
      "sensitive": true
    },
    "no_auth": {
      "type": "boolean",
      "title": "Disable MCP auth",
      "default": false
    }
  }
}

Fields marked "sensitive": true are stored encrypted by Claude Code. When "no_auth": true, token enforcement is disabled and api_token is not required on loopback binds. Non-loopback binds also require CORTEX_TRUSTED_GATEWAY_NO_AUTH=true.

Security practices

  • Token comparison is constant-time (subtle::ConstantTimeEq) to prevent timing attacks
  • Auth failure logs include HTTP method and path but never the submitted token value
  • No tokens are logged at any log level, including RUST_LOG=trace
  • Rotate credentials by updating .env and running just restart

See also