Getting started

This page takes a single host from nothing to a working MCP server and shows you what an AI client sees at each step. It uses the release binary; Installation covers installers, containers, Helm and building from source. The binary is named secronyx, or secronyx.exe on Windows.

What you need

• A Linux, macOS or Windows host. Linux builds are static (CGO_ENABLED=0, -tags=netgo); macOS and Windows builds are native and have no runtime dependencies beyond the operating system.
• Permission to run a binary. No root is required for the default configuration; some collectors return more when run with privileges, and the audit log falls back to stderr when its default path is not writable (see below).
• Nothing else. There is no configuration file to write: every setting is a command-line flag or one of a handful of SECRONYX_* environment variables, listed in the Configuration reference.

Step 1: get the binary

Download the asset for your platform from https://github.com/levantar-ai/secronyx/releases/latest or from GitHub releases. The asset names are fixed by the release workflow: secronyx-linux-amd64, secronyx-linux-arm64, secronyx-darwin-amd64, secronyx-darwin-arm64 and secronyx-windows-amd64.exe. On Linux:

curl -LO https://github.com/levantar-ai/secronyx/releases/latest/download/secronyx-linux-amd64
chmod +x secronyx-linux-amd64
sudo mv secronyx-linux-amd64 /usr/local/bin/secronyx
secronyx --version

--version prints the version, commit and build date baked in by the release build, plus the Go runtime and target:

secronyx v2.7.0
  commit: 4d14b7a...
  built:  20260917T083000Z
  go:     go1.2x.x
  os:     linux/amd64

A build from source without ldflags prints secronyx dev, commit: none and built: unknown. Installation explains how to verify a download's provenance before you trust it.

Step 2: run a query without a client

--query runs one tool directly and prints its result, bypassing MCP entirely. It is the fastest way to confirm the binary works on a host and to see what a tool returns:

secronyx --query get_uptime --json

{
  "boot_time": "2026-08-27T23:55:40.244676372+01:00",
  "uptime": 1761082070000000,
  "uptime_str": "20 days, 9 hours, 11 minutes, 22 seconds",
  "timestamp": "2026-09-17T09:07:02.31467895+01:00"
}

Without --json the same JSON is printed under a === get_uptime === heading. A tool that does not exist fails with Error: unknown query 'no_such_query' and Use --help to see available queries. Tools that take arguments read them from dedicated flags in this mode, for example --pid for get_capabilities, --lines for log tools, --limit, --hours, --days, --period, --framework, --service, --path, --image-id, and the Windows registry and IIS selectors --hive, --regpath, --max-depth, --appid, --site-name and --app-pool. The Command line page lists which flag each tool reads.

Try a few more:

secronyx --query get_cpu_info --json
secronyx --query get_processes --json
secronyx --query get_listening_ports --json
secronyx --query get_os_info --json
secronyx --query get_incident_triage_snapshot --json

Step 3: read the start-up log

Everything the server logs goes to stderr, never stdout, so it cannot corrupt the MCP stream. Running as an unprivileged user on a fresh host you will see three lines like these before any output:

WARNING: audit provider "default" could not open "/var/log/secronyx/audit.jsonl" (failed to create audit directory: mkdir /var/log/secronyx: permission denied); audit events are being written to stderr instead
Audit logging enabled: provider=stderr output=/var/log/secronyx/audit.jsonl
Scope policy: 9 tools not registered (sensitive=false, scopes="")

They mean:

• Audit logging is on by default and writes to /var/log/secronyx/audit.jsonl. When that file cannot be opened the trail continues on stderr rather than stopping silently. Point it somewhere writable with --audit-output, for example --audit-output "$HOME/.secronyx/audit.jsonl", or create the directory for the service account. See Audit logging.
• Nine tools in the sensitive scope were not registered. They are absent from tools/list and calling them returns a tool-not-found error until you start the server with --enable-sensitive. See Scopes and authorization.

Redaction is also on by default; it logs nothing unless you disable it, in which case you get WARNING: output redaction is DISABLED; secrets in system state will be returned verbatim.

Step 4: speak MCP over stdio by hand

With no flags the binary is an MCP server on stdin and stdout: one JSON-RPC 2.0 message per line in, one per line out. You can drive it from a shell to see exactly what an agent exchanges with it. The initialize handshake:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"shell","version":"0"}}}' \
  | secronyx 2>/dev/null

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"secronyx","version":"dev"}}}

The server advertises only the tools capability. List the tools and call one in the same session:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"shell","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_uptime","arguments":{}}}' \
  | secronyx 2>/dev/null

The tools/list result is an array of {name, description, inputSchema} objects; on a default Linux build it contains 521 entries. A tools/call result wraps the tool's JSON document as text content, which is how MCP carries structured results:

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\n  \"boot_time\": \"2026-08-27T23:55:40.247107628+01:00\",\n  \"uptime\": 1761084730000000,\n  \"uptime_str\": \"20 days, 9 hours, 11 minutes, 24 seconds\",\n  \"timestamp\": \"2026-09-17T09:07:04.97711267+01:00\"\n}"}]}}

Arguments go in params.arguments, and each tool's inputSchema describes the shape it accepts and the defaults it applies; for example get_processes returns 10 processes sorted by CPU unless you pass {"name":"get_processes","arguments":{"limit":5,"sort_by":"memory"}}. The server also answers ping, accepts the initialized and notifications/cancelled notifications, and reads lines of up to 10 MiB. A single tool result is capped at 4 MiB by default (--max-result-bytes). The full method list and error codes are in JSON-RPC API.

Step 5: decide which tools exist

Registration is decided once at start-up by a scope policy; a tool outside the policy is neither listed nor callable on any transport. The scopes are core, logs, hooks, hardware, resources, state, software, triage, windows, enhanced, report, storage, security, network, analytics, alerts, compliance, consumer and sensitive.

• Default: every scope except sensitive.
• --scopes core,logs,triage (or SECRONYX_SCOPES) registers only the listed scopes.
• --enable-sensitive (or SECRONYX_ENABLE_SENSITIVE=1) additionally registers the sensitive tools: authentication logs, environment variables, process environments, user accounts, sudo and SSH configuration, MAC status, certificates and macOS TCC permissions. Listing sensitive in --scopes is not enough on its own; the explicit flag is always required.

For a first session with a local agent the default is right. Narrow it with --scopes when the agent only needs a slice, and reach for --enable-sensitive only on hosts where the audit log and the client's identity justify it.

Step 6: connect a client

Point your MCP client at the binary as a stdio server. For Claude Code that is one command:

claude mcp add --transport stdio secronyx -- /usr/local/bin/secronyx

Connect an AI client has the equivalent for Claude Desktop and other clients, how to pass flags such as --audit-output through the client, and how to reach a server on another machine.

Step 7 (optional): serve HTTP on loopback

The HTTP transport exposes the same JSON-RPC over POST /. Bound to a loopback address it may run without authentication, which is convenient for scripts and the example clients:

secronyx --transport http --listen 127.0.0.1:8080

curl -s http://127.0.0.1:8080/health
curl -s -X POST http://127.0.0.1:8080/ \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_uptime"}}'

/health returns {"status":"ok"}. It and the OAuth metadata document at /.well-known/oauth-protected-resource stay unauthenticated once authentication is configured; POST / and /metrics then answer 401. Try to bind anywhere else without credentials and the server exits before opening a socket:

Error: refusing to listen on "0.0.0.0:8080" without authentication: bind to 127.0.0.1, or configure --token/--oidc-issuer/--auth-server, or pass --allow-unauthenticated for an isolated development network

With a token but no TLS the refusal reads refusing to listen on "0.0.0.0:8080" with authentication but without TLS. A static token must be at least 32 characters. The rules, and the reverse-proxy and TLS options, are in Remote access over HTTP.

What you get without configuring anything

Next steps

• Connect an AI client to start asking questions in natural language.
• Installation for installers, Docker, Helm and running as a service.
• Security model before exposing the HTTP transport beyond the host.
• Tutorial: diagnose a slow Linux host for a worked investigation.