MCP Protocol

Technical reference for the Nefia MCP server protocol.

Nefia includes a built-in MCP (Model Context Protocol) server that enables AI agents to manage remote hosts through a structured tool interface. The server exposes 205 core tools for command execution, file management, host discovery, playbook management, system queries, package management, user management, cron management, service management, network diagnostics, firewall management, system updates, mount management, container management, queue management, scheduling, reactor automation, compliance, diagnostics, VPN management, device security, webhooks, backups, composite workflows, and privilege escalation over JSON-RPC 2.0 via stdio. When the approval workflow is enabled in the configuration, 2 additional approval tools are available (207 tools total). All 207 tools include outputSchema definitions so AI agents can predict response structure before calling. The server also provides 51 workflow prompts, 22 resources (20 static + 2 templates), and progressive tool discovery. Tools are organized into 18 categories: agent, audit, automation, cluster, composite, container, core, fs, infra, management, network, ops, pki, policy, security, system-mutation, system-query, and vpn.

Starting the Server

bash

nefia mcp serve

The server reads from stdin and writes to stdout using the MCP protocol (JSON-RPC 2.0, UTF-8). AI agents connect by spawning the nefia mcp serve process and communicating over its standard I/O streams.

Connection Setup

Claude Desktop / Claude Code

json

{
  "mcpServers": {
    "nefia": {
      "command": "nefia",
      "args": ["mcp", "serve"]
    }
  }
}

Or via the Claude Code CLI:

bash

claude mcp add nefia -- nefia mcp serve

Codex CLI (OpenAI)

Add to ~/.codex/config.toml:

toml

[mcp_servers.nefia]
command = "nefia"
args = ["mcp", "serve"]

The server initializes by loading nefia.yaml, establishing VPN connections, and advertising available tools. Configuration changes are hot-reloaded during the session.

Common Setup Issues

Authentication required. Run nefia login before starting the server. The MCP server is not auth-exempt, so it exits immediately without a valid session. Most MCP clients suppress stderr, making this look like a silent connection failure.
PATH resolution. MCP clients do not load shell profiles. If nefia is not in the system-wide PATH, use the absolute path (e.g., /usr/local/bin/nefia). Run which nefia to find it.
Windows. Some MCP clients require cmd /c to launch executables: "command": "cmd", "args": ["/c", "nefia", "mcp", "serve"]. Alternatively, use PowerShell: "command": "powershell", "args": ["-Command", "nefia mcp serve"].

Tool Reference

Session Tools

Sessions provide a persistent, sandboxed context for file operations on a specific host. Each MCP client is limited to 50 concurrent sessions. Attempting to open a 51st session returns an error. The server tracks session ownership per client, so nefia.session.list returns only the calling client's own sessions, and clients cannot see or interfere with other clients' sessions.

nefia.session.open -- Open a session

Creates a new session bound to a host and root directory. All subsequent file operations within the session are confined to the root. The cwd (working directory) defaults to root if not specified. Multiple sessions can be open simultaneously for different hosts (up to 50 per client).

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Target host ID as defined in the configuration (e.g., `pc-office`, `server-dev`).
`root`	string	no	Root directory on the remote host. All file paths will be resolved relative to this. Defaults to the host's configured root.
`cwd`	string	no	Initial working directory (relative to root). Defaults to root if not specified.

Returns:

Field	Type	Description
`session_id`	string	Unique session identifier for subsequent operations.
`resolved_root`	string	Effective root directory on the remote host.
`resolved_cwd`	string	Effective working directory (resolved from `cwd` parameter or defaulting to root).

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true

nefia.session.close -- Close a session

Closes an active session and releases associated resources. After closing, the session_id becomes invalid and cannot be reused. Any in-flight operations on the session will be cancelled.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	yes	Session ID returned by `nefia.session.open`.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false

Execution Tools

nefia.exec -- Execute a command

Runs a shell command on one or more remote hosts. Target selection uses either session_id (execute on the session's host in the session's working directory) or target (a selector expression), but not both.

The command is passed to the remote shell (zsh on macOS, bash on Linux, PowerShell on Windows). Note that PowerShell uses different escaping rules -- special characters like $, (, ) may need escaping with a backtick or wrapping in single quotes.

Parameters:

Parameter	Type	Required	Description
`command`	string	yes	Shell command to execute on the remote host(s).
`session_id`	string	no	Session ID (use this or `target`, not both).
`target`	string	no	Host selector: `all`, `host:<id>`, `group:<name>`, or `tag:k=v`.
`timeout_ms`	int	no	Command timeout in milliseconds. Defaults to the configured timeout (30m). Hard-capped at 2 hours (7,200,000 ms).
`concurrency`	int	no	Maximum number of hosts to execute on concurrently. Defaults to configured value (50).
`progress_interval`	string	no	Interval for progress notifications during long-running commands (e.g., `30s`, `1m`).
`env`	object	no	Environment variables to inject. Keys must match `[a-zA-Z_][a-zA-Z0-9_]*`. Secret provider references (`${provider:path}`) are resolved.
`dry_run`	boolean	no	If `true`, resolve targets and check policy without executing. Returns host list with allowed/denied status.
`batch_size`	int	no	Number of hosts per batch for rolling execution. `0` = all at once (default).
`batch_wait`	string	no	Pause between batches. Go duration format (e.g., `5s`, `30s`, `1m`).
`subset`	int	no	Execute on a random subset of N hosts from the resolved target. `0` = all hosts (default).
`rerun`	string	no	Re-execute on hosts from a previous job. `failure` = only failed hosts, `success` = only successful hosts. Requires `last_job_id`.
`last_job_id`	string	no	Job ID from a previous exec result. Required when `rerun` is set.
`fail_fast`	boolean	no	Stop execution immediately on the first host failure. Remaining hosts are skipped.
`min_success_rate`	number	no	Minimum success rate (0.0–1.0) required to continue execution. If the success rate drops below this threshold, remaining hosts are skipped.
`stdin`	string	no	Standard input to pipe to the command.
`working_directory`	string	no	Working directory for command execution (relative to session root or host root).
`uid`	string	no	Run as this user (uid or username) on the target host.

Returns (per host):

Field	Type	Description
`host_id`	string	Host identifier.
`ok`	boolean	Whether the command succeeded (exit code 0).
`stdout`	string	Standard output.
`stderr`	string	Standard error.
`exit_code`	int	Process exit code (0 = success).
`duration_ms`	integer	Command execution duration in milliseconds.
`truncated`	boolean	Whether stdout/stderr was truncated.
`error_code`	string	Structured error code (e.g., E5001) if the command failed.
`error_message`	string	Human-readable error message.
`error_hints`	string[]	Suggested actions to resolve the error.

Output buffer per host is capped at 50 MB (or max_output_bytes * 2) to prevent memory exhaustion.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.exec.sudo -- Execute with sudo

Runs a command with sudo privilege escalation on remote hosts. Requires sudo.enabled: true in configuration and NOPASSWD configured in sudoers for the SSH user on target hosts.

Parameters:

Parameter	Type	Required	Description
`command`	string	yes	Shell command to execute with sudo privileges.
`session_id`	string	no	Session ID (use this or `target`, not both).
`target`	string	no	Host selector: `all`, `host:<id>`, `group:<name>`, or `tag:k=v`.
`user`	string	no	User to run as (default: `root`). Must be a valid Unix username.
`timeout_ms`	int	no	Command timeout in milliseconds. Hard-capped at 2 hours.
`concurrency`	int	no	Maximum number of hosts to execute on concurrently (default: 50).
`progress_interval`	string	no	Interval for progress notifications during long-running commands.

Returns (per host):

Field	Type	Description
`host_id`	string	Host identifier.
`ok`	boolean	Whether the command succeeded (exit code 0).
`exit_code`	int	Process exit code.
`stdout`	string	Standard output.
`stderr`	string	Standard error.
`duration_ms`	int	Execution duration in milliseconds.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

File System Tools

File system tools accept either session_id or host_id to identify the target host. When using session_id, paths are resolved relative to the session root. When using host_id, paths are resolved relative to the host's configured root.

nefia.fs.read -- Read a file

Returns the file content as UTF-8 text. For large files (over 10 MB), use nefia.fs.stream_read instead.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	File path relative to the root directory (e.g., `src/main.go`, `config.yaml`).
`max_bytes`	int	no	Maximum bytes to read. Defaults to configured limit (10 MB).

Returns:

Field	Type	Description
`content`	string	File contents (UTF-8 or base64-encoded).
`is_base64`	boolean	Whether `content` is base64-encoded.
`truncated`	boolean	Whether output was truncated due to `max_bytes`.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.fs.write -- Write a file

Writes content to a file on a remote host. Provide either content (UTF-8 text) or content_base64 (binary data), not both. Creates the file if it does not exist; overwrites if it does.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	File path relative to the root directory.
`content`	string	no	UTF-8 text content to write.
`content_base64`	string	no	Base64-encoded binary content for non-text files (images, archives, etc.).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

nefia.fs.patch -- Patch a file

Applies a unified diff to an existing file. Supports an optional expected_sha256 for optimistic concurrency control -- the patch is rejected if the file has been modified since reading.

This is safer than nefia.fs.write for modifying existing files, as it applies only the intended changes rather than replacing the entire file.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	File path relative to the root directory.
`unified_diff`	string	yes	Unified diff to apply (standard `diff -u` format).
`expected_sha256`	string	no	SHA-256 hex digest of the current file content. Patch is rejected if the file has been modified.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true

nefia.fs.list -- List directory

Lists entries in a directory. Returns file names, sizes, permissions, and modification times. Does not recurse into subdirectories.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	Directory path relative to the root directory (e.g., `src/`, `.`).

Returns:

Field	Type	Description
`entries`	object[]	Array of `{ name, type, size, mtime }` objects.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.fs.stat -- File metadata

Returns metadata for a file or directory. Useful for checking if a file exists before reading or writing.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	File or directory path relative to the root directory.

Returns:

Field	Type	Description
`name`	string	File or directory name.
`type`	string	Entry type: `file`, `dir`, or `symlink`.
`size`	int	Size in bytes.
`mtime`	string	Last modification time (RFC 3339).
`mode`	string	Unix permission string (e.g., `0755`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.fs.stream_read -- Stream a file to local disk

Streams a remote file to a local file path without buffering in memory. Use this for large files (up to 3 GB) that would exceed the 10 MB inline limit of nefia.fs.read. The transfer uses approximately 32 KB of memory.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`remote_path`	string	yes	Remote file path to download.
`local_path`	string	yes	Local file path to save to.
`progress_interval`	string	no	Interval for progress notifications during transfer (e.g., `5s`, `1m`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.fs.stream_write -- Stream a local file to a remote host

Streams a local file to a remote file path without buffering in memory. Uses atomic write (temp file + rename) to prevent partial writes. Supports files up to 3 GB.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`remote_path`	string	yes	Remote file path to write to.
`local_path`	string	yes	Local file path to upload from.
`expected_sha256`	string	no	SHA-256 hex digest of the local file. If provided, the local file is hashed before upload and rejected on mismatch.
`progress_interval`	string	no	Interval for progress notifications during transfer (e.g., `5s`, `1m`).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

nefia.fs.stream_read_resumable -- Resumable download

Stream a remote file to a local path with resume support. If a previous partial download exists at local_path, the transfer continues from the last checkpoint instead of starting over.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`remote_path`	string	yes	Remote file path to download.
`local_path`	string	yes	Local file path to save to (absolute, must be under home or tmp directory).
`progress_interval`	string	no	Interval for progress notifications during transfer.

Returns:

Field	Type	Description
`ok`	boolean	Whether the transfer completed successfully.
`bytes`	int	Total bytes transferred.
`sha256`	string	SHA-256 hex digest of the transferred file.
`resumed`	boolean	Whether the transfer was resumed from a previous checkpoint.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.fs.stream_write_resumable -- Resumable upload

Stream a local file to a remote path with resume support. If a previous partial upload exists, the transfer continues from the last checkpoint instead of starting over.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`remote_path`	string	yes	Remote file path to write to.
`local_path`	string	yes	Local file path to upload from (absolute, must be under home or tmp directory).
`expected_sha256`	string	no	SHA-256 hex digest of the local file for integrity verification.
`progress_interval`	string	no	Interval for progress notifications during transfer.

Returns:

Field	Type	Description
`ok`	boolean	Whether the transfer completed successfully.
`bytes`	int	Total bytes transferred.
`sha256`	string	SHA-256 hex digest of the transferred file.
`resumed`	boolean	Whether the transfer was resumed from a previous checkpoint.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

nefia.fs.mkdir -- Create a directory

Create a directory (and any missing parents) on a remote host. If the directory already exists, the operation succeeds silently (idempotent).

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	Directory path to create (relative to root). Parent directories are created automatically.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.fs.remove -- Remove a file or directory

Remove a file or directory on a remote host. By default, only removes files or empty directories. Set recursive=true to remove directories and all their contents.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	File or directory path to remove (relative to root).
`recursive`	boolean	no	Remove directories and all contents recursively (default: false).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

nefia.fs.chmod -- Change file permissions

Change file permissions on a remote host. Supports numeric modes (e.g. 755) and symbolic modes (e.g. u+x, go-w). Not supported on Windows — use nefia.exec with icacls commands instead.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	File or directory path (relative to root).
`mode`	string	yes	Permission mode: numeric (e.g. `755`, `0644`) or symbolic (e.g. `u+x`, `go-w`, `a+r`).
`recursive`	boolean	no	Apply permissions recursively to directory contents (default: false).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

nefia.fs.chown -- Change file ownership

Change file ownership on a remote host. Specify owner as user or user:group. Not supported on Windows — use nefia.exec with icacls instead.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	File or directory path (relative to root).
`owner`	string	yes	New owner in `user` or `user:group` format (e.g. `root`, `www-data:www-data`).
`recursive`	boolean	no	Apply ownership change recursively to directory contents (default: false).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

nefia.fs.find -- Search for files

Search for files on a remote host with flexible filtering. Returns matching files with metadata (path, type, size, mtime, mode). Results are limited to max_results (default 1000, max 10000).

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	Root directory to search in (relative to root).
`name`	string	no	Glob pattern to match filenames (e.g. `.log`, `config.`).
`type`	string	no	Filter by entry type: `file`, `dir`, or `symlink`.
`max_depth`	int	no	Maximum directory depth to search (0 = unlimited).
`max_results`	int	no	Maximum number of results to return (default: 1000, max: 10000).
`modified_after`	string	no	Only include files modified after this timestamp (RFC 3339).
`modified_before`	string	no	Only include files modified before this timestamp (RFC 3339).
`size_min`	int	no	Minimum file size in bytes.
`size_max`	int	no	Maximum file size in bytes.

Returns:

Field	Type	Description
`entries`	object[]	Array of `{ path, type, size, mtime, mode }` objects.
`truncated`	boolean	Whether results were truncated due to `max_results`.
`total_scanned`	int	Total number of entries scanned.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.fs.tail -- Read last N lines of a file

Read the last N lines of a file on a remote host. Optionally filter output with a grep pattern (fixed-string match). Useful for reading log files without downloading the entire file.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	File path to read (relative to root).
`lines`	int	no	Number of lines to read from the end (default: 50, max: 5000).
`grep`	string	no	Optional fixed-string pattern to filter lines (case-sensitive).

Returns:

Field	Type	Description
`content`	string	The tail content of the file.
`line_count`	int	Number of lines returned.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.fs.move -- Move or rename a file

Move or rename a file or directory on a remote host. This tool is NOT idempotent — moving to an existing destination may overwrite it.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`src`	string	yes	Source path.
`dst`	string	yes	Destination path.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false

nefia.fs.grep -- Search for a pattern in files

Search for a pattern in remote files recursively from the given path using grep. Returns matching lines with file paths. Prefer this over nefia.exec + grep for structured output.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`pattern`	string	yes	Search pattern (grep basic regex).
`path`	string	yes	Path to search in (file or directory).
`max_results`	int	no	Maximum number of matches to return (default: 100, max: 1000).

Returns:

Field	Type	Description
`matches`	object[]	Array of `{ path, line, content }` objects.
`total_count`	int	Total number of matches found.
`truncated`	boolean	Whether results were truncated due to `max_results`.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.fs.du -- Disk usage

Get disk usage for a path on a remote host. Returns the total size in bytes and a human-readable format. Prefer this over nefia.exec + du for structured output.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	Path to check disk usage for.

Returns:

Field	Type	Description
`path`	string	Path that was checked.
`size_bytes`	int	Total size in bytes.
`human_size`	string	Human-readable size (e.g., `1.2 GB`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Discovery Tools

nefia.hosts.list -- List hosts

Returns all enrolled hosts, optionally filtered by tag. Use this to discover available hosts before opening sessions or running commands.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Optional session ID to verify the caller has an active session.
`tag`	string	no	Filter hosts by tag in `key=value` format (e.g., `env=prod`, `role=web`).

Returns:

Field	Type	Description
`hosts`	object[]	Array of host objects with `id`, `address`, `os`, `user`, `vpn_status`, `tags`, and group membership.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Playbook Tools

nefia.playbook.run -- Run a playbook

Executes a multi-step playbook on target hosts. Steps support OS filtering, template variables (Go text/template), conditional execution, output capture, and retry logic.

Parameters:

Parameter	Type	Required	Description
`target`	string	yes	Host selector: `all`, `host:<id>`, `group:<name>`, or `tag:k=v`.
`playbook`	object	yes	Playbook definition (see schema below).
`vars`	object	no	Template variable overrides (key-value strings, override playbook defaults).
`dry_run`	boolean	no	Preview execution plan without running (default: false).
`step_timeout_ms`	int	no	Default step timeout in milliseconds (applied to steps without explicit timeout).
`concurrency`	int	no	Maximum number of hosts to process in parallel (default: 50).

Playbook definition schema:

Field	Type	Required	Description
`name`	string	yes	Unique playbook name.
`description`	string	no	Human-readable description.
`version`	int	no	Schema version (1).
`vars`	object	no	Default template variables (key-value strings).
`steps`	array	yes	Array of step objects (see below).

Step schema:

Each step must have a name and exactly one action: exec (shell command string), fs_write (object with path and content fields), or fs_read (object with path field).

Field	Type	Required	Description
`name`	string	yes	Step name.
`exec`	string	no	Shell command to execute.
`fs_write`	object	no	File write operation with `path` and `content` fields.
`fs_read`	object	no	File read operation with `path` field.
`os`	string	no	OS filter: `macos`, `linux`, or `windows`. Step is skipped if host OS does not match.
`continue_on_error`	boolean	no	Continue to next step on failure (default: false).
`timeout_ms`	int	no	Step timeout in milliseconds.
`register`	string	no	Save step result under this name for use in subsequent `when` conditions and templates. Name must use `[a-zA-Z0-9_]` only (no hyphens).
`when`	string	no	Condition expression. Step is skipped if false. Supports Go templates and comparisons.
`retry`	object	no	Retry configuration with `max_attempts` (1-1000) and `interval_ms` (>= 0).

Template variables:

Variable	Description
`{{ .Host.ID }}`	Host identifier.
`{{ .Host.OS }}`	Host OS (`macos`, `linux`, `windows`).
`{{ .Host.Address }}`	Host address.
`{{ .Vars.key }}`	User-defined variable.
`{{ .Steps.<name>.Output }}`	Captured output from a registered step.
`{{ .Steps.<name>.OK }}`	Whether a registered step succeeded (bool).
`{{ .Steps.<name>.ExitCode }}`	Exit code of a registered step.
`{{ .Steps.<name>.Skipped }}`	Whether a registered step was skipped.

Returns:

Field	Type	Description
`playbook_name`	string	Name of the executed playbook.
`host_results`	object[]	Per-host results (see below).
`total_hosts`	int	Total number of targeted hosts.
`success_count`	int	Number of hosts that completed all steps successfully.
`fail_count`	int	Number of hosts with at least one failed step.
`elapsed_ms`	int	Total wall-clock duration across all hosts in milliseconds.

Each entry in host_results:

Field	Type	Description
`host_id`	string	Host identifier.
`ok`	boolean	Whether all steps succeeded on this host.
`steps`	object[]	Per-step results (see below).
`elapsed_ms`	int	Total execution time for this host in milliseconds.

Each entry in steps:

Field	Type	Description
`step_name`	string	Step name as defined in the playbook.
`step_index`	int	Zero-based index of the step.
`action`	string	Action type: `exec`, `fs_write`, `fs_read`, or `skipped`.
`ok`	boolean	Whether the step succeeded.
`output`	string	Step output (present when the step produced output).
`error`	string	Error message (present when the step failed).
`skipped`	boolean	Whether the step was skipped due to OS filter or `when` condition.
`duration_ms`	int	Step execution duration in milliseconds.
`exit_code`	int	Process exit code (for `exec` steps).
`attempts`	int	Number of attempts (present when retry was configured).

In dry-run mode, returns { ok: boolean, dry_run: true } instead.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

System Information Tools

nefia.facts -- Gather host facts

Gathers structured system information from target hosts in a single SSH round-trip per host. More efficient than running multiple nefia.exec calls. Supports macOS, Linux, and Windows.

Parameters:

Parameter	Type	Required	Description
`target`	string	yes	Host selector: `all`, `host:<id>`, `group:<name>`, or `tag:k=v`.
`categories`	string	no	Comma-separated list of categories to collect (default: all). Options: `os`, `disk`, `memory`, `cpu`, `uptime`, `network`.
`concurrency`	int	no	Maximum number of hosts to query in parallel (default: configured value).

Returns:

Field	Type	Description
`results`	object[]	Per-host results (see below).
`summary`	object	Summary with `total_hosts`, `success_count`, and `fail_count`.

Each entry in results:

Field	Type	Description
`host_id`	string	Host identifier.
`ok`	boolean	Whether fact gathering succeeded for this host.
`facts`	object	Gathered facts (present when `ok` is true). Contains `os`, `disk`, `memory`, `cpu`, `uptime`, and `network` objects depending on requested categories.
`error`	string	Error message (present when `ok` is false).
`elapsed_ms`	int	Gathering duration in milliseconds.

The facts object contains only the requested categories. Each category structure:

os -- { name, version, kernel, arch }
disk -- { mounts: [{ path, total_bytes, used_bytes, usage_percent }] }
memory -- { total_bytes, used_bytes, available_bytes }
cpu -- { count, model, load_avg }
uptime -- { seconds, boot_time }
network -- { interfaces: [{ name, ipv4, ipv6 }] }

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.session.summary -- Session activity summary

Generate an AI-consumable summary of a session's activity. Returns structured data including commands executed, files read/written, error count, duration, and a markdown-formatted narrative. The summary is also persisted to disk for later retrieval.

Use this to understand what happened during a session without reading raw audit logs.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	yes	Session ID to summarize.

Returns:

Field	Type	Description
`session_id`	string	The session ID.
`host_id`	string	The host this session is connected to.
`duration`	string	Session duration (e.g., `5m23s`).
`command_count`	int	Number of commands executed.
`commands`	string[]	List of command strings executed.
`files_read`	string[]	List of file paths read.
`files_written`	string[]	List of file paths written.
`error_count`	int	Number of errors encountered.
`markdown`	string	Markdown-formatted narrative summary of session activity.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

System Query Tools

System query tools provide structured access to host system information without running raw commands. All tools support macOS, Linux, and Windows.

nefia.sys.processes -- List running processes

List running processes on a remote host with CPU and memory usage. Returns process list sorted by the specified field (default: CPU).

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`filter`	string	no	Filter processes by name (case-insensitive substring match).
`sort_by`	string	no	Sort field: `cpu`, `memory`, or `pid` (default: `cpu`).
`limit`	int	no	Maximum number of processes to return (default: 50, max: 500).

Returns:

Field	Type	Description
`processes`	object[]	Array of `{ pid, user, name, cpu_percent, memory_percent, memory_rss_bytes, command, state }` objects.
`total_count`	int	Total number of running processes on the host.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.services -- List system services

List system services on a remote host. Uses systemctl on Linux, launchctl on macOS, and Get-Service on Windows.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`filter`	string	no	Filter services by name (case-insensitive substring match).
`status`	string	no	Filter by status: `running`, `stopped`, `failed`, or `all` (default: `all`).

Returns:

Field	Type	Description
`services`	object[]	Array of `{ name, display_name, status, enabled, pid, type }` objects.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.ports -- List network connections

List network connections and listening ports on a remote host. Uses ss on Linux, lsof on macOS, and Get-NetTCPConnection on Windows.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`state`	string	no	Filter by connection state: `listen`, `established`, or `all` (default: `all`).

Returns:

Field	Type	Description
`connections`	object[]	Array of `{ protocol, local_addr, local_port, remote_addr, remote_port, state, pid, process }` objects.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.users -- List user accounts

List system user accounts on a remote host. Uses getent passwd on Linux, dscl on macOS, and Get-LocalUser on Windows.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`include_system`	boolean	no	Include system accounts with UID < 1000 (default: false).

Returns:

Field	Type	Description
`users`	object[]	Array of `{ username, uid, gid, home, shell, groups, is_system }` objects.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.logs -- Query system logs

Query system logs on a remote host. Uses journalctl on Linux, log show on macOS, and Get-EventLog on Windows.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`source`	string	no	Log source: `syslog`, `journal`, `auth`, `kern`, or a systemd unit name (Linux) / event log name (Windows).
`lines`	int	no	Maximum number of log entries to return (default: 100, max: 5000).
`since`	string	no	Start time: RFC 3339 timestamp or relative duration (e.g. `1h`, `30m`, `2d`).
`until`	string	no	End time: RFC 3339 timestamp or relative duration.
`grep`	string	no	Pattern to filter log messages (case-insensitive on macOS/Linux).
`priority`	string	no	Minimum priority level: `emerg`, `err`, `warning`, or `info`.

Returns:

Field	Type	Description
`entries`	object[]	Array of `{ timestamp, source, priority, message }` objects.
`truncated`	boolean	Whether results were truncated due to `lines` limit.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.service.control -- Control a system service

Start, stop, restart, enable, or disable a system service on a remote host. On Linux/macOS, non-status actions require sudo privileges (the command is automatically wrapped with sudo when enabled). Uses systemctl on Linux, launchctl on macOS, and *-Service cmdlets on Windows.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`service`	string	yes	Service name (e.g. `nginx`, `sshd`, `com.apple.sshd`, `wuauserv`).
`action`	string	yes	Action: `start`, `stop`, `restart`, `enable`, `disable`, or `status`.

Returns:

Field	Type	Description
`ok`	boolean	Whether the action completed successfully.
`service`	string	Service name.
`previous_status`	string	Service status before the action.
`current_status`	string	Service status after the action.
`message`	string	Status or error message.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

Approval Tools

When the approval workflow is enabled in the configuration (approval.enabled: true), 2 additional tools are advertised. These tools allow AI agents to list pending approval requests and (attempt to) respond to them.

nefia.approval.list -- List pending approvals

Lists all pending approval requests. Returns details about operations that are waiting for human approval.

Parameters: None.

Returns:

Field	Type	Description
`pending`	object[]	Array of pending approval requests. Each entry contains `id`, `tool`, `command`, `path`, `host_id`, and `created_at`. Empty array when no requests are pending.
`enabled`	boolean	Whether the approval workflow is currently enabled.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.approval.respond -- Respond to an approval request

Responds to one or more pending approval requests. Supports both single and bulk approval.

Security: This tool is deliberately blocked in MCP mode to prevent self-approval attacks where an AI agent approves its own requests. Calling this tool always returns an AccessDenied error (-32013). Approvals must be handled via the TUI dashboard or CLI (nefia approval respond), where operators can review and approve or deny pending requests.

Parameters:

Parameter	Type	Required	Description
`request_id`	string	no	The approval request ID to respond to (use this or `request_ids`, not both).
`request_ids`	string[]	no	Multiple approval request IDs to respond to with the same decision (use this or `request_id`, not both).
`approved`	boolean	yes	`true` to approve, `false` to deny.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false

VPN & Connectivity Tools

nefia.vpn.status -- VPN tunnel status

Returns whether the WireGuard tunnel is ready, the local VPN address, and detailed status for each peer including transport type (direct/derp/turn), last handshake time, and transfer statistics.

Parameters: None.

Returns:

Field	Type	Description
`ready`	boolean	Whether the VPN tunnel is active.
`local_addr`	string	Local VPN address.
`peers`	object[]	Array of `{ host_id, public_key, endpoint, vpn_addr, transport, healthy, last_handshake, transfer_rx, transfer_tx }` objects.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.vpn.diagnose -- VPN diagnostics

Run VPN diagnostics and return issues with recommendations. Checks tunnel readiness, DERP relay connectivity, multipath status, and peer health. Use this when VPN connectivity problems are suspected before attempting SSH operations.

Parameters: None.

Returns:

Field	Type	Description
`tunnel_ready`	boolean	Whether the tunnel is up.
`local_addr`	string	Local VPN address.
`derp_connected`	boolean	Whether the DERP relay is connected.
`multipath_active`	boolean	Whether multipath is active.
`peer_count`	int	Total number of peers.
`healthy_peers`	int	Number of healthy peers.
`issues`	string[]	Detected issues.
`recommendations`	string[]	Actionable recommendations.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.vpn.ping -- Test VPN connectivity

Test VPN connectivity to a specific host by attempting a TCP dial. Measures round-trip latency through the VPN tunnel and reports the transport path used (direct, DERP relay, or TURN).

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to ping.

Returns:

Field	Type	Description
`host_id`	string	Host identifier.
`vpn_addr`	string	VPN address of the host.
`reachable`	boolean	Whether the host is reachable.
`latency_ms`	int	Round-trip latency in milliseconds.
`transport`	string	Transport path used (direct, derp, turn).
`error`	string	Error message if unreachable.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

Policy & Intelligence Tools

nefia.policy.test -- Pre-check policy

Pre-check whether a command, path, or operation would be allowed by the policy engine. Use this before executing operations to avoid POLICY_DENIED errors. At least one of command, path, or operation must be provided.

Parameters:

Parameter	Type	Required	Description
`command`	string	no	Shell command to test (e.g., `rm -rf /tmp/*`).
`path`	string	no	File path to test (e.g., `/etc/shadow`).
`host_id`	string	no	Host ID for role-based evaluation. If omitted, global rules are checked.
`operation`	string	no	MCP operation type (e.g., `exec`, `fs.write`).

Returns:

Field	Type	Description
`allowed`	boolean	Whether the operation would be allowed.
`reason`	string	Denial reason (present when denied).
`denial_type`	string	Type of denial rule that matched.
`rule_matched`	string	The specific rule that triggered.
`jit_available`	boolean	Whether JIT temporary access is available.
`mode`	string	Current policy mode (`enforce`, `warn`, `off`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.policy.test_batch -- Batch policy test

Test multiple commands, paths, or operations against the policy engine in a single call. Accepts up to 50 tests and returns per-test results plus a summary. Use this instead of calling nefia.policy.test in a loop.

Parameters:

Parameter	Type	Required	Description
`tests`	object[]	yes	Array of policy test items (max 50). Each must have at least one of `command`, `path`, or `operation`.

Each test object:

Field	Type	Required	Description
`command`	string	no	Command to test.
`path`	string	no	File path to test.
`host_id`	string	no	Host context for the test.
`operation`	string	no	Operation type to test (e.g., `exec`, `fs_read`, `fs_write`).

Returns:

Field	Type	Description
`results`	object[]	Per-test results with `allowed`, `reason`, `denial_type`, `rule_matched` fields.
`all_allowed`	boolean	Whether all tests passed.
`summary`	object	Summary with `total`, `allowed`, and `denied` counts.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Host Inventory Tools

nefia.hosts.show -- Host details

Get detailed information about a specific host. Returns all host configuration including ID, address, user, OS, shell, root directory, role, tags, group membership, and VPN status with transport type.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to look up.

Returns:

Field	Type	Description
`id`	string	Host identifier.
`address`	string	Host address.
`user`	string	SSH user.
`os`	string	Operating system.
`shell`	string	Default shell.
`root`	string	Root directory.
`role`	string	Assigned role.
`tags`	object	Key-value tags.
`groups`	string[]	Group memberships.
`vpn`	object	VPN status with `status`, `vpn_addr`, and `transport` fields.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.hosts.update -- Update host metadata

Update host metadata (tags or role). Changes are persisted to the config file and hot-reloaded immediately.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to update.
`tags`	object	no	Replace all tags with these key-value pairs.
`set_tags`	object	no	Merge these tags into existing tags (add or overwrite keys).
`remove_tags`	string[]	no	Remove these tag keys.
`role`	string	no	Set the host's role.

Returns:

Field	Type	Description
`host_id`	string	Host identifier.
`tags`	object	Updated tags.
`groups`	string[]	Updated group memberships.
`role`	string	Updated role.
`updated`	boolean	Whether any changes were made.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false

JIT Access Tools

nefia.jit.request -- Request temporary access

Request temporary elevated access via the Just-In-Time access system. Creates a pending access request that must be approved by an operator. Requires JIT to be enabled in the configuration.

Parameters:

Parameter	Type	Required	Description
`role`	string	yes	Role to request access for (must match a policy-defined role).
`host_patterns`	string[]	yes	Host ID patterns (e.g., `["web-*", "db-prod"]`).
`duration`	string	yes	Requested duration (e.g., `1h`, `30m`, `4h`).
`reason`	string	yes	Business justification for the request.

Returns:

Field	Type	Description
`request_id`	string	Unique request identifier.
`status`	string	Request status (e.g., `pending`).

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false

nefia.jit.list -- List JIT requests

List JIT access requests and active grants. Use this to check if you have an active grant before running privileged operations.

Parameters:

Parameter	Type	Required	Description
`status`	string	no	Filter by status: `pending`, `approved`, `denied`, `expired`, `revoked`, or `all` (default: `all`).

Returns:

Field	Type	Description
`requests`	object[]	Array of `{ id, requester_id, role, host_patterns, duration, reason, status, created_at }` objects.
`grants`	object[]	Array of `{ request_id, role, host_patterns, expires_at }` objects.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Audit Tools

nefia.audit.search -- Search audit logs

Search the append-only audit log by date range, job ID, session ID, host ID, or operation type. At least one filter must be provided.

Parameters:

Parameter	Type	Required	Description
`start_date`	string	no	Start date inclusive (YYYY-MM-DD).
`end_date`	string	no	End date inclusive (YYYY-MM-DD).
`job_id`	string	no	Filter by job ID.
`session_id`	string	no	Filter by session ID.
`host_id`	string	no	Filter by host ID.
`op_kind`	string	no	Filter by operation kind (e.g., `exec`, `fs_write`).
`limit`	int	no	Maximum records to return (default: 100, max: 1000).

Returns:

Field	Type	Description
`records`	object[]	Array of `{ seq, timestamp, job_id, session_id, host_id, op_kind, user }` objects.
`total`	int	Total matching records.
`truncated`	boolean	Whether results were truncated.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.audit.export -- Export audit logs

Export audit records for the specified date range in JSONL or CSV format. Useful for compliance reporting and external analysis.

Parameters:

Parameter	Type	Required	Description
`start_date`	string	no	Start date in YYYY-MM-DD format.
`end_date`	string	no	End date in YYYY-MM-DD format.
`format`	string	no	Export format: `jsonl` or `csv` (default: `jsonl`).

Returns:

Field	Type	Description
`content`	string	Exported audit data.
`record_count`	int	Number of exported records.
`format`	string	Export format used.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Agent Management Tools

nefia.agent.status -- Agent status

Get the status of a nefia-agent running on a target host. Queries the agent for its version, OS, architecture, and uptime.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to query.

Returns:

Field	Type	Description
`host_id`	string	Host identifier.
`version`	string	Agent version.
`os`	string	Operating system.
`arch`	string	Architecture (amd64, arm64).
`uptime`	string	Agent uptime.
`status`	string	Agent status.
`error`	string	Error message if query failed.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.agent.upgrade -- Upgrade agent

Upgrade the nefia-agent on a target host. Pushes the new agent binary and restarts the service. If version is omitted, upgrades to the current operator CLI version.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to upgrade.
`version`	string	no	Target version (e.g., `1.2.3`). Defaults to current CLI version.

Returns:

Field	Type	Description
`host_id`	string	Host identifier.
`previous_version`	string	Version before upgrade.
`new_version`	string	Version after upgrade.
`restarted`	boolean	Whether the agent was restarted.
`status`	string	Upgrade status.
`error`	string	Error message if upgrade failed.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

Schedule Tools

nefia.schedule.list -- List schedules

List all scheduled playbook executions with their runtime state.

Parameters: None.

Returns:

Field	Type	Description
`schedules`	object[]	Array of `{ id, name, description, cron_expr, timezone, playbook_ref, target, enabled, last_run_at, last_run_ok, next_run_at }` objects.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.schedule.create -- Create a schedule

Create a new scheduled playbook execution. Defines a recurring schedule using a cron expression.

Parameters:

Parameter	Type	Required	Description
`name`	string	yes	Unique schedule name.
`cron_expr`	string	yes	Cron expression (5-field: `min hour dom mon dow`).
`playbook_ref`	string	yes	Playbook file path or name.
`target`	string	yes	Host selector.
`description`	string	no	Human-readable description.
`timezone`	string	no	IANA timezone (default: `UTC`).
`vars`	object	no	Template variable overrides.
`enabled`	boolean	no	Whether the schedule is active (default: `true`).
`overlap_policy`	string	no	Behavior if previous run is active: `skip`, `cancel_running`, or `allow` (default: `skip`).
`max_retries`	int	no	Maximum retry attempts on failure (default: `0`).
`missed_run_policy`	string	no	Behavior for missed runs: `skip` or `run_once` (default: `skip`).
`concurrency`	int	no	Maximum concurrent hosts.
`step_timeout_ms`	int	no	Default step timeout in milliseconds.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false

nefia.schedule.delete -- Delete a schedule

Delete a scheduled playbook execution. Removes the schedule definition and its runtime state. This cannot be undone.

Parameters:

Parameter	Type	Required	Description
`id`	string	yes	Schedule ID or name.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false

nefia.schedule.show -- Show schedule details

Show detailed information about a specific schedule including the definition, next run time, and last run status.

Parameters:

Parameter	Type	Required	Description
`id`	string	yes	Schedule ID or name.

Returns:

Field	Type	Description
`id`	string	Schedule identifier.
`name`	string	Schedule name.
`cron_expr`	string	Cron expression.
`timezone`	string	IANA timezone.
`playbook_ref`	string	Playbook reference.
`target`	string	Host selector.
`enabled`	boolean	Whether the schedule is active.
`last_run_at`	string	Last run timestamp.
`last_run_ok`	boolean	Whether the last run succeeded.
`next_run_at`	string	Next scheduled run time.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.schedule.update -- Update a schedule

Partially update a schedule definition. Only provided fields are changed; omitted fields remain unchanged.

Parameters:

Parameter	Type	Required	Description
`id`	string	yes	Schedule ID or name.
`name`	string	no	New schedule name.
`description`	string	no	New description.
`cron_expr`	string	no	New cron expression (5-field format).
`timezone`	string	no	IANA timezone (e.g., `America/New_York`).
`target`	string	no	Host selector expression.
`vars`	object	no	Playbook variables to set.
`overlap_policy`	string	no	Behavior if previous run is active: `skip`, `queue`, or `allow`.
`missed_run_policy`	string	no	Behavior for missed runs: `skip` or `run_once`.
`concurrency`	int	no	Maximum concurrent hosts.
`step_timeout_ms`	int	no	Per-step timeout in milliseconds.
`max_retries`	int	no	Maximum retry attempts on failure.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.schedule.enable -- Enable a schedule

Re-enable a previously disabled schedule so it will run on its cron expression again. Idempotent — enabling an already-enabled schedule is a no-op.

Parameters:

Parameter	Type	Required	Description
`id`	string	yes	Schedule ID or name.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.schedule.disable -- Disable a schedule

Disable a schedule without deleting it. Prevents the schedule from running until re-enabled with nefia.schedule.enable. The schedule definition is preserved. Idempotent.

Parameters:

Parameter	Type	Required	Description
`id`	string	yes	Schedule ID or name.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.schedule.history -- Schedule execution history

Show recent execution records for a schedule including run time, success/failure, and host counts.

Parameters:

Parameter	Type	Required	Description
`id`	string	yes	Schedule ID or name.
`limit`	int	no	Maximum entries to return (default: 20, max: 100).

Returns:

Field	Type	Description
`schedule_id`	string	Schedule identifier.
`schedule_name`	string	Schedule name.
`entries`	object[]	Array of `{ run_at, ok, elapsed, hosts_total, hosts_ok, hosts_fail, error }` objects.
`total`	int	Total number of history entries.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

File Copy Tool

nefia.fs.copy -- Copy a file on remote host

Copy a file from src to dst on the same remote host. Both paths are resolved relative to the session's or host's root directory.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`src`	string	yes	Source file path (relative to root).
`dst`	string	yes	Destination file path (relative to root).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

Playbook Discovery Tools

nefia.playbook.list -- List playbooks

List all available playbooks. Discovers playbooks from standard search directories (./playbooks/ and config directory). Returns name, path, description, and step count for each playbook.

Parameters: None.

Returns:

Field	Type	Description
`playbooks`	object[]	Array of `{ name, path, description, step_count }` objects.
`warnings`	string[]	Any warnings encountered during discovery.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.playbook.show -- Show playbook details

Show full details of a playbook. Resolves by name or file path and returns the full definition including all steps, variables, and metadata.

Parameters:

Parameter	Type	Required	Description
`name_or_path`	string	yes	Playbook name (e.g., `deploy`) or file path (e.g., `./playbooks/deploy.yaml`).

Returns:

Field	Type	Description
`name`	string	Playbook name.
`path`	string	Resolved file path.
`description`	string	Playbook description.
`steps`	object[]	Full step definitions.
`vars`	object	Default template variables.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.playbook.validate -- Validate a playbook

Validate a playbook without executing it. Checks structure, step definitions, and template syntax.

Parameters:

Parameter	Type	Required	Description
`name_or_path`	string	yes	Playbook name or file path to validate.

Returns:

Field	Type	Description
`valid`	boolean	Whether the playbook is valid.
`errors`	string[]	Validation errors.
`warnings`	string[]	Validation warnings.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Queue Tools

Queue tools manage offline command queuing. When a command targets a host that is offline, it can be queued for later execution when the host comes online.

nefia.queue.list -- List queue entries

List queued offline commands, optionally filtered by status.

Parameters:

Parameter	Type	Required	Description
`status`	string	no	Filter by status: `pending`, `running`, `completed`, `failed`, `expired`, or `cancelled`.

Returns:

Field	Type	Description
`entries`	object[]	Array of `{ id, host_id, command, status, created_at, expires_at }` objects.
`total`	int	Total number of entries.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.queue.show -- Show queue entry details

Show details of a single queue entry.

Parameters:

Parameter	Type	Required	Description
`entry_id`	string	yes	Queue entry ID.

Returns:

Field	Type	Description
`id`	string	Entry identifier.
`host_id`	string	Target host.
`command`	string	Queued command.
`status`	string	Entry status.
`created_at`	string	Creation timestamp.
`expires_at`	string	Expiration timestamp.
`error`	string	Error message (if failed).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.queue.cancel -- Cancel a queue entry

Cancel a pending queue entry. Only entries with status pending can be cancelled.

Parameters:

Parameter	Type	Required	Description
`entry_id`	string	yes	Queue entry ID to cancel.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false

nefia.queue.retry -- Retry a queue entry

Retry a failed or expired queue entry. Creates a new pending entry with the same command and host. The original entry is preserved.

Parameters:

Parameter	Type	Required	Description
`entry_id`	string	yes	Queue entry ID to retry.
`ttl`	string	no	Time-to-live for the new entry (default: `1h`).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false

Multi-Host File Operations

nefia.push -- Push file to multiple hosts

Distribute a file to all hosts matching the target selector. Supports batch execution for staged rollouts.

Parameters:

Parameter	Type	Required	Description
`target`	string	yes	Host selector.
`remote_path`	string	yes	Destination file path on remote hosts.
`content`	string	no	File content as UTF-8 text (mutually exclusive with `content_base64`).
`content_base64`	string	no	File content as base64 (mutually exclusive with `content`).
`batch_size`	int	no	Number of hosts per batch (`0` = all at once).
`batch_wait`	string	no	Pause between batches (Go duration format).
`subset`	int	no	Deploy to a random subset of N hosts.
`dry_run`	boolean	no	Resolve targets without writing files.
`no_recurse`	boolean	no	Do not recurse into subdirectories when pushing directories.
`force`	boolean	no	Overwrite existing files without confirmation.
`exclude`	string[]	no	Host IDs to exclude from the push operation.
`mode`	string	no	File permissions to set (e.g., `0644`).
`owner`	string	no	File ownership (`user:group`).
`backup_existing`	boolean	no	Back up existing files before overwriting.

Returns:

Field	Type	Description
`hosts`	object[]	Per-host results with `host_id`, `ok`, and `error` fields.
`success_count`	int	Number of successful hosts.
`fail_count`	int	Number of failed hosts.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.sync -- Sync directory to multiple hosts

Synchronize files from a local directory to a remote directory on all matching hosts. Only changed files are transferred (by modification time or checksum). Optionally deletes remote files not present locally.

Parameters:

Parameter	Type	Required	Description
`local_dir`	string	yes	Local directory path on the operator machine.
`remote_dir`	string	yes	Destination directory on remote hosts.
`target`	string	yes	Host selector.
`checksum`	boolean	no	Use checksums instead of modification time for change detection.
`delete`	boolean	no	Delete remote files not present in local directory.
`dry_run`	boolean	no	Preview changes without transferring files.
`exclude`	string[]	no	Glob patterns to exclude (e.g., `["*.log", ".git"]`).
`batch_size`	int	no	Number of hosts per batch.
`batch_wait`	string	no	Pause between batches.
`subset`	int	no	Sync to a random subset of N hosts.
`preserve`	boolean	no	Preserve file permissions and ownership during sync.
`conflict_resolution`	string	no	Strategy for handling conflicts: `overwrite`, `skip`, or `newer` (default: `overwrite`).

Returns:

Field	Type	Description
`hosts`	object[]	Per-host results with `host_id`, `ok`, `transferred`, `deleted`, `skipped`, `total_bytes`, `duration_ms`, and `error` fields.
`success_count`	int	Number of successful hosts.
`fail_count`	int	Number of failed hosts.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

Diagnostics Tools

nefia.status -- System-wide status

Get a system-wide status overview in a single call. Returns VPN tunnel status, host counts, queue depth, active session count, and configuration summary.

Parameters: None.

Returns:

Field	Type	Description
`vpn`	object	VPN status with `ready`, `peer_count`, and `healthy_peers` fields.
`hosts`	object	Host counts with `total`, `online`, and `offline` fields.
`queue`	object	Queue depth with `pending`, `running`, `completed`, and `failed` fields.
`sessions`	object	Session info with `active` count.
`config`	object	Configuration summary with `policy_mode` and `vpn_enabled` fields.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.doctor -- Health checks

Run comprehensive health checks. Validates configuration, VPN connectivity, audit logging, and optionally tests connectivity to a specific host.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	no	Test connectivity to a specific host.
`strict`	boolean	no	If `true`, treat warnings as failures.

Returns:

Field	Type	Description
`checks`	object[]	Array of `{ name, status, message }` objects. Status is `pass`, `warn`, or `fail`.
`summary`	object	Summary with `total`, `pass`, `warn`, and `fail` counts.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.session.list -- List active sessions

List the calling client's active MCP sessions. Each client sees only its own sessions; sessions opened by other clients are not included.

Parameters: None.

Returns:

Field	Type	Description
`sessions`	object[]	Array of `{ session_id, host_id, root_dir, created_at }` objects (scoped to the calling client).
`count`	int	Number of active sessions for this client.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.explain -- Explain an error code

Get detailed explanation and remediation for an error code. Provides suggested actions, diagnostics commands, and example tool calls. Use error codes from previous tool responses (e.g., HOST_NOT_FOUND, SSH_AUTH_FAILED).

Parameters:

Parameter	Type	Required	Description
`error_code`	string	yes	Error code string from a previous tool response.

Returns:

Field	Type	Description
`error_code`	string	The error code queried.
`known`	boolean	Whether the error code is recognized.
`suggested_actions`	string[]	Recommended actions to resolve the error.
`diagnostics`	string[]	Diagnostic tool calls to run.
`example`	object	Example tool call to try.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.recording.list -- List recordings

List session recordings. Returns metadata for stored session recordings (asciicast format) for audit and replay.

Parameters:

Parameter	Type	Required	Description
`limit`	int	no	Maximum recordings to return (default: 50).

Returns:

Field	Type	Description
`recordings`	object[]	Array of `{ session_id, host_id, started_at, duration, size }` objects.
`total`	int	Total number of recordings.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.recording.show -- Show recording details

Show metadata for a specific session recording.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	yes	Session ID of the recording.

Returns:

Field	Type	Description
`session_id`	string	Session identifier.
`host_id`	string	Host identifier.
`started_at`	string	Recording start time.
`duration`	string	Recording duration.
`size`	int	Recording file size in bytes.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.recording.delete -- Delete a recording

Permanently delete the recording for the given session. Idempotent — deleting a non-existent recording is a no-op.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	yes	Session ID of the recording to delete.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false

Reactor Tools

nefia.reactor.status -- Reactor engine status

Show reactor engine status including whether the reactor is running, total number of rules, and per-rule status with hit counts.

Parameters: None.

Returns:

Field	Type	Description
`running`	boolean	Whether the reactor engine is active.
`total_rules`	int	Total number of configured rules.
`rules`	object[]	Array of `{ name, event_pattern, host_pattern, action_type, hit_count }` objects.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.reactor.events -- Recent reactor events

List recent events processed by the reactor engine. Useful for debugging event-driven automation.

Parameters:

Parameter	Type	Required	Description
`limit`	int	no	Maximum events to return (default: 50, max: 200).

Returns:

Field	Type	Description
`events`	object[]	Array of `{ event_type, host_id, matched_rule, action_taken, processed_at, error }` objects.
`total`	int	Total number of events.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Compliance Tools

nefia.compliance.report -- Generate compliance report

Generate a compliance report for a security framework. Evaluates the current configuration and audit evidence against the specified framework's controls. Returns control-level pass/fail status, gaps, and recommendations.

Parameters:

Parameter	Type	Required	Description
`framework`	string	yes	Compliance framework: `soc2`, `iso27001`, or `hipaa`.
`period`	string	no	Reporting period. Go duration (e.g., `720h`) or Nd format (e.g., `30d`, `90d`). Default: `30d`.

Returns:

Field	Type	Description
`framework`	string	Framework evaluated.
`generated_at`	string	Report generation timestamp.
`period_start`	string	Reporting period start.
`period_end`	string	Reporting period end.
`summary`	object	Summary with `total_controls`, `pass_count`, `fail_count`, `partial_count`, and `compliance_score`.
`controls`	object[]	Per-control results.
`gaps`	string[]	Identified compliance gaps.
`disclaimer`	string	Report disclaimer.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Security & Reliability Tools

nefia.cancel -- Cancel a running job

Cancel a running exec or playbook job. Sends a cancellation signal to the job. The job will stop as soon as the current in-flight commands complete.

Parameters:

Parameter	Type	Required	Description
`job_id`	string	yes	Job ID from a previous exec or playbook result summary.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false

nefia.power.wake -- Wake-on-LAN

Send a Wake-on-LAN magic packet to wake a host. Optionally waits for the host to come online after waking.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to wake (must have a MAC address configured).
`proxy_host_id`	string	no	Send WoL via this proxy host (must be on same LAN).
`wait`	boolean	no	Wait for the host to come online after waking.
`timeout`	string	no	How long to wait (default: `60s`). Only used when `wait=true`.

Returns:

Field	Type	Description
`host_id`	string	Host identifier.
`mac_addr`	string	MAC address used.
`proxy_host`	string	Proxy host used (if any).
`sent`	boolean	Whether the packet was sent.
`online`	boolean	Whether the host came online (when `wait=true`).
`error`	string	Error message if failed.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.secrets.list -- List secret providers

List configured secret providers. Returns names and types of configured providers (e.g., env, file, vault). No secret values are returned.

Parameters: None.

Returns:

Field	Type	Description
`providers`	object[]	Array of `{ name, type }` objects.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.secrets.test -- Test secret provider connectivity

Attempt a test connection to a named secret provider to verify it is reachable and configured correctly. No secret values are read or returned.

Parameters:

Parameter	Type	Required	Description
`provider`	string	yes	Provider name (from `nefia.secrets.list`).

Returns:

Field	Type	Description
`provider`	string	Provider name.
`ok`	boolean	Whether the provider is reachable.
`error`	string	Error message if unreachable.
`latency`	string	Connection latency.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

Infrastructure & Configuration Tools

nefia.config.show -- Show configuration

Show the current Nefia configuration with sensitive fields masked. Useful for verifying configuration without shell access. Fields matching key, secret, password, or token are replaced with ***.

Parameters: None.

Returns:

Field	Type	Description
`fields`	object	Flattened configuration as key→value pairs with sensitive values masked.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.vpn.revoke -- Revoke VPN access

Revoke VPN access for a specific host or all hosts. Revoked hosts must re-enroll via nefia vpn invite to regain connectivity. One of host_id or all must be provided.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	no	Host ID to revoke (use this or `all`).
`all`	boolean	no	Revoke all hosts (`true`). Use with caution.

Returns:

Field	Type	Description
`revoked`	string[]	List of host IDs whose VPN access was revoked.
`all`	boolean	Whether all hosts were revoked.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false

nefia.netcheck -- Network diagnostics

Run network connectivity diagnostics. Detects NAT type, tests STUN/DERP/TURN reachability, and reports the public address. Use this as an alternative to nefia.vpn.diagnose for network-level analysis.

Parameters: None.

Returns:

Field	Type	Description
`nat`	string	NAT type: `full-cone`, `restricted`, `port-restricted`, `symmetric`, or `unknown`.
`stun_reachable`	boolean	Whether STUN servers are reachable.
`derp_reachable`	boolean	Whether the DERP relay is reachable.
`turn_reachable`	boolean	Whether TURN servers are reachable.
`public_addr`	string	Detected public IP address and port.
`issues`	string[]	Detected issues.
`recommendations`	string[]	Actionable recommendations.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

Device Security Tools

nefia.device_lock.status -- Device lock status

Check the Ed25519-based device-lock status for a host. Returns whether device verification is enabled, whether the device is verified, and the device key fingerprint.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to check.

Returns:

Field	Type	Description
`host_id`	string	Host identifier.
`enabled`	boolean	Whether device-lock is enabled.
`verified`	boolean	Whether the device is verified.
`device_key`	string	Public key fingerprint (if registered).
`registered_at`	string	Registration timestamp (RFC 3339).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.device_lock.verify -- Verify device lock

Perform cryptographic challenge verification against a host's registered Ed25519 device key. This is a read-only, idempotent operation — no state is modified.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to verify.

Returns:

Field	Type	Description
`host_id`	string	Host identifier.
`valid`	boolean	Whether the device key verification passed.
`message`	string	Status or error message.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.posture.check -- Device posture check

Evaluate device posture compliance for a host. Checks firewall status, disk encryption, OS version, and other posture rules defined in the configuration. Returns pass/fail with violations and remediation hints.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to check.

Returns:

Field	Type	Description
`host_id`	string	Host identifier.
`passed`	boolean	Whether all posture checks passed.
`mode`	string	Posture mode: `off`, `warn`, or `enforce`.
`violations`	string[]	List of failed posture checks.
`hints`	string[]	Remediation hints for violations.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Webhook Tools

nefia.webhook.list -- List webhooks

List configured webhooks with masked URLs. Returns webhook names, event subscriptions, and active status.

Parameters: None.

Returns:

Field	Type	Description
`webhooks`	object[]	Array of `{ name, url, events, active }` objects. URLs are masked for security.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.webhook.test -- Test webhook delivery

Send a test event to a named webhook and verify delivery. Returns the HTTP status code, success status, and response latency.

Parameters:

Parameter	Type	Required	Description
`name`	string	yes	Webhook name (from `nefia.webhook.list`).

Returns:

Field	Type	Description
`name`	string	Webhook name.
`status_code`	int	HTTP response status code.
`ok`	boolean	Whether the test delivery succeeded.
`error`	string	Error message if delivery failed.
`latency`	string	Round-trip delivery latency.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true

Backup Tools

nefia.backup.list -- List configuration backups

List available configuration backups with metadata. Restore operations are available via the CLI only (nefia backup restore).

Parameters: None.

Returns:

Field	Type	Description
`backups`	object[]	Array of `{ label, path, size, created_at }` objects.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.backup.create -- Create a configuration backup

Create a backup of the current Nefia configuration and state. The backup includes nefia.yaml and related state files. Labels must match [A-Za-z0-9][A-Za-z0-9._-]{0,63}.

Parameters:

Parameter	Type	Required	Description
`label`	string	no	Optional label for the backup. Must match `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`.

Returns:

Field	Type	Description
`label`	string	Backup label.
`path`	string	Backup file path.
`size`	int	Backup file size in bytes.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false

Power Management Tools

nefia.power.reboot -- Reboot a remote host

Reboot a remote host. Requires sudo privileges. Optionally waits for the host to come back online.

Parameters:

Parameter	Type	Required	Description
`target`	string	yes	Host selector expression.
`force`	boolean	no	Force immediate reboot without graceful shutdown.
`delay_ms`	integer	no	Delay in milliseconds before rebooting (default: 0).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.power.shutdown -- Shut down a remote host

Shut down a remote host. Requires sudo privileges. This is a destructive, non-reversible operation.

Parameters:

Parameter	Type	Required	Description
`target`	string	yes	Host selector expression.
`force`	boolean	no	Force immediate shutdown.
`delay_ms`	integer	no	Delay in milliseconds before shutting down (default: 0).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

Package Management Tools

nefia.sys.package.list -- List installed packages

List installed packages on a remote host. Detects the package manager automatically (apt, yum, dnf, brew, choco).

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`query`	string	no	Filter packages by name substring.
`limit`	int	no	Maximum number of packages to return (default: 200, max: 5000).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.package.install -- Install a package

Install a package on a remote host. Requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`packages`	string[]	yes	Package names to install (max 50).
`version`	string	no	Specific version to install.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.sys.package.remove -- Remove a package

Remove a package from a remote host. Requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`packages`	string[]	yes	Package names to remove (max 50).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

User Management Tools

nefia.sys.user.create -- Create a user account

Create a user account on a remote host. Requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`username`	string	yes	Username to create.
`uid`	int	no	User ID.
`home_dir`	string	no	Home directory path.
`create_home`	boolean	no	Create the home directory (default: false).
`shell`	string	no	Login shell (e.g., `/bin/bash`).
`groups`	string[]	no	Additional group memberships.
`system`	boolean	no	Create a system account (UID below 1000).
`expiry_date`	string	no	Account expiry date (YYYY-MM-DD).
`comment`	string	no	User comment (GECOS field).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.sys.user.modify -- Modify a user account

Modify an existing user account on a remote host. Requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`username`	string	yes	Username to modify.
`shell`	string	no	New login shell.
`groups`	string[]	no	New group memberships (replaces existing).
`append_groups`	string[]	no	Groups to add (preserves existing).
`home`	string	no	New home directory.
`lock`	boolean	no	Lock the account.
`unlock`	boolean	no	Unlock the account.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.sys.user.delete -- Delete a user account

Delete a user account from a remote host. Requires sudo privileges. Protected system accounts (root, sshd, nobody, etc.) cannot be deleted.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`username`	string	yes	Username to delete.
`remove_home`	boolean	no	Remove the user's home directory (default: false).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

Process Management Tools

nefia.sys.kill -- Send signal to a process

Send a signal to a process on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`pid`	int	yes	Process ID to signal.
`signal`	string	no	Signal to send: `SIGTERM`, `SIGKILL`, `SIGHUP`, `SIGINT`, `SIGUSR1`, `SIGUSR2` (default: `SIGTERM`).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

Cron Management Tools

nefia.sys.cron.list -- List cron jobs

List cron jobs on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`user`	string	no	Filter by user.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.cron.create -- Create a cron job

Create a cron job on a remote host. Requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`schedule`	string	yes	Cron schedule expression (5-field: `min hour dom mon dow`).
`command`	string	yes	Command to execute.
`user`	string	no	User to run the cron job as.
`comment`	string	no	Comment describing the cron job.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true

nefia.sys.cron.delete -- Delete a cron job

Delete a cron job from a remote host. Requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`id`	string	yes	Cron job ID or comment identifier.
`user`	string	no	User who owns the cron job.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

System Information Tools (Extended)

nefia.sys.network -- Network interface information

Get network interface information from a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.disk -- Disk usage information

Get disk usage and partition information from a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.env -- Environment variables

Get environment variables from a remote host. Sensitive values matching *_KEY, *_SECRET, *_TOKEN, *_PASSWORD, *_CREDENTIAL are automatically masked.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`filter`	string	no	Filter by name (case-insensitive substring match).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.group.list -- List system groups

List system groups on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.logs.search -- Search system logs

Search system logs with keywords, service, and severity filtering. More structured than nefia.sys.logs for targeted log investigation.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`keywords`	string[]	yes	Keywords to search for (all must match).
`services`	string[]	no	Filter by service/unit names.
`severity`	string	no	Minimum severity: `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, `debug`.
`since`	string	no	Start time (RFC 3339 or relative duration).
`until`	string	no	End time (RFC 3339 or relative duration).
`correlate`	boolean	no	Merge and sort entries from all sources by timestamp.
`limit`	int	no	Maximum results (default: 500, max: 5000).
`target`	string	no	Host selector for fleet-wide log search (e.g., `"all"`, `"group:prod"`). Mutually exclusive with `session_id`/`host_id`.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

Extended File System Tools

nefia.fs.symlink -- Create a symbolic link

Create a symbolic link on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`target`	string	yes	Link target path.
`path`	string	yes	Path where the symlink will be created.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.fs.readlink -- Read symbolic link target

Read the target of a symbolic link on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path`	string	yes	Symbolic link path.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.fs.archive.create -- Create an archive

Create a tar.gz or zip archive on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`paths`	string[]	yes	Paths to include in the archive.
`output_path`	string	yes	Output archive path.
`format`	string	no	Archive format: `tar.gz` or `zip` (default: `tar.gz`).

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true

nefia.fs.archive.extract -- Extract an archive

Extract a tar.gz or zip archive on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`archive`	string	yes	Archive file path.
`output_path`	string	yes	Output directory for extracted files.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.fs.diff -- Compare two files

Compare two files on a remote host and return a unified diff.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`path_a`	string	yes	First file path.
`path_b`	string	yes	Second file path.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

Host Group Tools

nefia.hosts.groups -- List host groups

List all host groups with member counts.

Parameters: None.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Service Management Tools

nefia.sys.service.enable -- Enable a service

Enable a service to start on boot.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`service`	string	yes	Service name.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.service.disable -- Disable a service

Disable a service from starting on boot.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`service`	string	yes	Service name.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.service.reload -- Reload a service

Reload a service's configuration without restarting it.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`service`	string	yes	Service name.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.service.logs -- Get service logs

Get logs for a specific service.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`service`	string	yes	Service name.
`lines`	int	no	Number of lines to return (default: 100).
`since`	string	no	Start time (RFC 3339 or relative duration).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.service.show -- Show service details

Show detailed status and configuration for a specific service.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`service`	string	yes	Service name.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

Network Diagnostics Tools

nefia.net.ping -- Ping a target

Ping a target from a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`target`	string	yes	Hostname or IP to ping.
`count`	int	no	Number of pings (default: 4).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.net.traceroute -- Trace route to a target

Trace the network route to a target from a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`target`	string	yes	Hostname or IP to trace.
`max_hops`	int	no	Maximum hops (default: 30).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.net.dns -- DNS lookup

Perform a DNS lookup from a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`name`	string	yes	Domain name to look up.
`record_type`	string	no	Record type: `A`, `AAAA`, `CNAME`, `MX`, `NS`, `TXT`, `SRV`, `PTR`, `SOA` (default: `A`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.net.connections -- List network connections

List network connections on a remote host, optionally filtered by state.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`state`	string	no	Filter by state: `established`, `listen`, `time_wait`, `close_wait`, `all` (default: `all`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.net.listen -- List listening ports

List all listening ports on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

Firewall Management Tools

nefia.net.firewall.list -- List firewall rules

List firewall rules on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.net.firewall.add -- Add a firewall rule

Add a firewall rule on a remote host. Requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`action`	string	yes	Rule action: `allow`, `deny`, or `reject`.
`direction`	string	yes	Traffic direction: `in` or `out`.
`protocol`	string	no	Protocol: `tcp`, `udp`, `icmp`, or `any` (default: `any`).
`port`	int	no	Port number.
`port_range`	string	no	Port range (e.g., `8000-9000`).
`source`	string	no	Source address or CIDR.
`destination`	string	no	Destination address or CIDR.
`rule`	string	no	Raw firewall rule string (backend-specific).
`comment`	string	no	Rule description.
`priority`	int	no	Rule priority.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.net.firewall.remove -- Remove a firewall rule

Remove a firewall rule from a remote host. Requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`rule_id`	string	yes	Rule ID or name to remove.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

nefia.net.firewall.status -- Firewall status

Check firewall status on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

System Update Tools

nefia.sys.update.check -- Check for updates

Check for available system updates on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`security_only`	boolean	no	Only check for security updates (default: false).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.update.apply -- Apply system updates

Apply system updates on a remote host. Requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`packages`	string[]	no	Specific packages to update (max 50). If omitted, updates all.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.sys.hostname -- Get or set hostname

Get or set the system hostname on a remote host. Setting requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`new_hostname`	string	no	New hostname to set. If omitted, returns the current hostname.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.time -- System time information

Get time information, set timezone, or trigger NTP sync on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`set_timezone`	string	no	IANA timezone to set (e.g., `America/New_York`).
`ntp_sync`	boolean	no	Trigger NTP time synchronization.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.sysctl.list -- List sysctl parameters

List kernel sysctl parameters on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`pattern`	string	no	Filter by pattern (e.g., `net.ipv4`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.sysctl.set -- Set a sysctl parameter

Set a kernel sysctl parameter on a remote host. Requires sudo privileges. Values are validated against a regex whitelist.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`key`	string	yes	Sysctl parameter name (e.g., `net.ipv4.ip_forward`).
`value`	string	yes	Parameter value.
`persist`	boolean	no	Persist across reboots (default: false).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

Mount Management Tools

nefia.sys.mount.list -- List mount points

List mount points on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.sys.mount -- Mount a device

Mount a device on a remote host. Requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`device`	string	yes	Device path (e.g., `/dev/sdb1`).
`mount_point`	string	yes	Mount point path.
`fs_type`	string	no	Filesystem type (e.g., `ext4`, `xfs`, `nfs`).
`options`	string	no	Mount options (e.g., `ro,noexec`).
`readonly`	boolean	no	Mount as read-only.
`persistent`	boolean	no	Add to fstab for persistence across reboots.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.sys.umount -- Unmount a device

Unmount a mount point on a remote host. Requires sudo privileges.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`mount_point`	string	yes	Mount point to unmount.
`force`	boolean	no	Force unmount (default: false).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

Container Management Tools

nefia.container.list -- List containers

List containers (Docker or Podman) on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`all`	boolean	no	Include stopped containers (default: false).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.container.logs -- Get container logs

Get logs from a container on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`container_id`	string	yes	Container name or ID.
`tail`	int	no	Number of lines from the end (default: 100).
`since`	string	no	Start time (RFC 3339 or relative duration).
`until`	string	no	End time (RFC 3339 or relative duration).
`timestamps`	boolean	no	Include timestamps in output.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.container.start -- Start a container

Start a stopped container on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`container_id`	string	yes	Container name or ID.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.container.stop -- Stop a container

Stop a running container on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`container_id`	string	yes	Container name or ID.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

nefia.container.restart -- Restart a container

Restart a container on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`container_id`	string	yes	Container name or ID.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.container.inspect -- Inspect a container

Get detailed information about a container on a remote host.

Parameters:

Parameter	Type	Required	Description
`session_id`	string	no	Session ID (use this or `host_id`).
`host_id`	string	no	Host ID (use this or `session_id`).
`container_id`	string	yes	Container name or ID.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

VPN Extended Tools

nefia.vpn.key.rotate -- Rotate VPN keys

Rotate VPN WireGuard keys for a host. The host will need to reconnect after key rotation.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to rotate keys for.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.conn.health -- Connection health check

Check connection health for a specific host or all hosts. Tests VPN tunnel, SSH connectivity, and SFTP subsystem.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	no	Host ID to check (omit for all hosts).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

Composite Tools

Composite tools combine multiple operations into a single, higher-level workflow for common patterns.

nefia.run -- One-shot command execution

Execute a command on a host without opening a session. Simpler alternative to session.open + exec + session.close for one-off commands.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Target host ID.
`command`	string	yes	Command to execute.
`timeout_ms`	int	no	Timeout in milliseconds (max: 7,200,000 / 2 hours). Uses configured default when omitted.
`env`	object	no	Environment variables to inject (env var blacklist enforced).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.investigate -- Comprehensive host investigation

Run a comprehensive investigation of a host, gathering facts, processes, services, ports, disk, and network information in a single call.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to investigate.
`sections`	string[]	no	Sections to include: `facts`, `processes`, `services`, `ports`, `disk`, `network` (default: all).
`timeout_ms`	int	no	Timeout in milliseconds (max: 600,000 / 10 min). Uses configured default when omitted.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.file.deploy -- Deploy a file with verification

Deploy a file to a remote host with optional mode, ownership, backup, and verification.

Parameters:

Parameter	Type	Required	Description
`target`	string	yes	Host selector expression.
`remote_path`	string	yes	Destination file path.
`content`	string	no	File content (UTF-8).
`content_base64`	string	no	File content (base64-encoded).
`mode`	string	no	File permissions (e.g., `0644`).
`owner`	string	no	File ownership (`user:group`).
`backup_existing`	boolean	no	Back up existing file before overwriting.
`verify_command`	string	no	Command to verify deployment.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true

nefia.service.deploy -- Atomic service deployment

Atomically deploy a service with config push, verification, and rollback on failure.

Parameters:

Parameter	Type	Required	Description
`target`	string	yes	Host selector expression.
`service_name`	string	yes	Service name.
`config_path`	string	yes	Remote config file path.
`config_content`	string	yes	Config file content.
`verify_command`	string	no	Command to verify the config (e.g., `nginx -t`).
`health_command`	string	no	Command to check service health after restart.
`health_timeout_ms`	int	no	Timeout for health check.
`rollback_on_failure`	boolean	no	Rollback config and restart on failure (default: true).

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.config.apply -- Atomic config update

Atomically update a config file with validation and optional service reload.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Target host ID.
`config_path`	string	yes	Config file path.
`content`	string	yes	New config content.
`validate_command`	string	no	Command to validate config (e.g., `nginx -t`).
`reload_service`	string	no	Service to reload after update.
`verify_command`	string	no	Command to verify after reload.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

nefia.system.baseline -- Capture system state snapshot

Capture a system state snapshot for drift detection. Returns packages, services, ports, disk usage, users, and network configuration.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to snapshot.
`sections`	string[]	no	Sections to include: `packages`, `services`, `ports`, `disk`, `users`, `network` (default: all).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

nefia.system.health -- Comprehensive health check

Run comprehensive health checks on a host, including VPN, services, disk, load, ports, and memory.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to check.
`checks`	string[]	no	Checks to run: `vpn`, `services`, `disk`, `load`, `ports`, `memory` (default: all).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

Discovery & Policy Tools

nefia.tools.schema -- Get tool schema

Get the full JSON schema for a specific tool. Useful for progressive discovery — when the compact tool listing does not include enough detail, call this tool to get the complete parameter schema.

Parameters:

Parameter	Type	Required	Description
`tool_name`	string	yes	Tool name (e.g., `nefia.exec`, `nefia.fs.read`).

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.policy.capabilities -- Policy capabilities for a host

Read the effective policy capabilities for a specific host. Returns which operations are allowed and denied.

Parameters:

Parameter	Type	Required	Description
`host_id`	string	yes	Host ID to check.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

nefia.approval.check -- Check if approval is required

Check if a specific tool call would require approval before execution.

Parameters:

Parameter	Type	Required	Description
`tool_name`	string	yes	Tool name to check.
`host_id`	string	no	Host context for the check.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Tool Summary

The current nefia mcp serve command exposes 205 core tools, plus 2 conditional approval tools (207 total when approval is enabled):

#	Tool	Category	Read-Only	Destructive
1	`nefia.session.open`	Session	no	no
2	`nefia.session.close`	Session	no	yes
3	`nefia.session.summary`	Session	yes	no
4	`nefia.session.list`	Session	yes	no
5	`nefia.exec`	Execution	no	yes
6	`nefia.exec.sudo`	Execution	no	yes
7	`nefia.cancel`	Execution	no	yes
8	`nefia.fs.read`	File System	yes	no
9	`nefia.fs.write`	File System	no	yes
10	`nefia.fs.patch`	File System	no	no
11	`nefia.fs.list`	File System	yes	no
12	`nefia.fs.stat`	File System	yes	no
13	`nefia.fs.copy`	File System	no	yes
14	`nefia.fs.move`	File System	no	yes
15	`nefia.fs.grep`	File System	yes	no
16	`nefia.fs.du`	File System	yes	no
17	`nefia.fs.stream_read`	File System	yes	no
18	`nefia.fs.stream_write`	File System	no	yes
19	`nefia.fs.stream_read_resumable`	File System	yes	no
20	`nefia.fs.stream_write_resumable`	File System	no	yes
21	`nefia.fs.mkdir`	File System	no	no
22	`nefia.fs.remove`	File System	no	yes
23	`nefia.fs.chmod`	File System	no	yes
24	`nefia.fs.chown`	File System	no	yes
25	`nefia.fs.find`	File System	yes	no
26	`nefia.fs.tail`	File System	yes	no
27	`nefia.fs.symlink`	File System	no	no
28	`nefia.fs.readlink`	File System	yes	no
29	`nefia.fs.archive.create`	File System	no	no
30	`nefia.fs.archive.extract`	File System	no	yes
31	`nefia.fs.diff`	File System	yes	no
32	`nefia.push`	Multi-Host File	no	yes
33	`nefia.sync`	Multi-Host File	no	yes
34	`nefia.hosts.list`	Discovery	yes	no
35	`nefia.hosts.show`	Discovery	yes	no
36	`nefia.hosts.update`	Discovery	no	no
37	`nefia.hosts.groups`	Discovery	yes	no
38	`nefia.playbook.run`	Playbook	no	yes
39	`nefia.playbook.list`	Playbook	yes	no
40	`nefia.playbook.show`	Playbook	yes	no
41	`nefia.playbook.validate`	Playbook	yes	no
42	`nefia.facts`	System Info	yes	no
43	`nefia.sys.processes`	System Query	yes	no
44	`nefia.sys.services`	System Query	yes	no
45	`nefia.sys.ports`	System Query	yes	no
46	`nefia.sys.users`	System Query	yes	no
47	`nefia.sys.logs`	System Query	yes	no
48	`nefia.sys.logs.search`	System Query	yes	no
49	`nefia.sys.service.control`	System Query	no	yes
50	`nefia.sys.network`	System Query	yes	no
51	`nefia.sys.disk`	System Query	yes	no
52	`nefia.sys.env`	System Query	yes	no
53	`nefia.sys.kill`	System Query	no	yes
54	`nefia.sys.group.list`	System Query	yes	no
55	`nefia.sys.package.list`	Package	yes	no
56	`nefia.sys.package.install`	Package	no	yes
57	`nefia.sys.package.remove`	Package	no	yes
58	`nefia.sys.user.create`	User Mgmt	no	yes
59	`nefia.sys.user.modify`	User Mgmt	no	yes
60	`nefia.sys.user.delete`	User Mgmt	no	yes
61	`nefia.sys.cron.list`	Cron	yes	no
62	`nefia.sys.cron.create`	Cron	no	no
63	`nefia.sys.cron.delete`	Cron	no	yes
64	`nefia.sys.service.enable`	Service	no	no
65	`nefia.sys.service.disable`	Service	no	no
66	`nefia.sys.service.reload`	Service	no	no
67	`nefia.sys.service.logs`	Service	yes	no
68	`nefia.sys.service.show`	Service	yes	no
69	`nefia.net.ping`	Network	yes	no
70	`nefia.net.traceroute`	Network	yes	no
71	`nefia.net.dns`	Network	yes	no
72	`nefia.net.connections`	Network	yes	no
73	`nefia.net.listen`	Network	yes	no
74	`nefia.net.firewall.list`	Firewall	yes	no
75	`nefia.net.firewall.add`	Firewall	no	yes
76	`nefia.net.firewall.remove`	Firewall	no	yes
77	`nefia.net.firewall.status`	Firewall	yes	no
78	`nefia.sys.update.check`	System Update	yes	no
79	`nefia.sys.update.apply`	System Update	no	yes
80	`nefia.sys.hostname`	System Update	no	no
81	`nefia.sys.time`	System Update	no	no
82	`nefia.sys.sysctl.list`	System Update	yes	no
83	`nefia.sys.sysctl.set`	System Update	no	yes
84	`nefia.sys.mount.list`	Mount	yes	no
85	`nefia.sys.mount`	Mount	no	yes
86	`nefia.sys.umount`	Mount	no	yes
87	`nefia.container.list`	Container	yes	no
88	`nefia.container.logs`	Container	yes	no
89	`nefia.container.start`	Container	no	no
90	`nefia.container.stop`	Container	no	yes
91	`nefia.container.restart`	Container	no	yes
92	`nefia.container.inspect`	Container	yes	no
93	`nefia.vpn.status`	VPN	yes	no
94	`nefia.vpn.diagnose`	VPN	yes	no
95	`nefia.vpn.ping`	VPN	yes	no
96	`nefia.vpn.revoke`	VPN	no	yes
97	`nefia.vpn.key.rotate`	VPN	no	yes
98	`nefia.netcheck`	VPN	yes	no
99	`nefia.conn.health`	VPN	yes	no
100	`nefia.policy.test`	Policy	yes	no
101	`nefia.policy.test_batch`	Policy	yes	no
102	`nefia.policy.capabilities`	Policy	yes	no
103	`nefia.jit.request`	JIT Access	no	no
104	`nefia.jit.list`	JIT Access	yes	no
105	`nefia.audit.search`	Audit	yes	no
106	`nefia.audit.export`	Audit	yes	no
107	`nefia.agent.status`	Agent	yes	no
108	`nefia.agent.upgrade`	Agent	no	yes
109	`nefia.schedule.list`	Schedule	yes	no
110	`nefia.schedule.show`	Schedule	yes	no
111	`nefia.schedule.create`	Schedule	no	no
112	`nefia.schedule.update`	Schedule	no	no
113	`nefia.schedule.delete`	Schedule	no	yes
114	`nefia.schedule.enable`	Schedule	no	no
115	`nefia.schedule.disable`	Schedule	no	no
116	`nefia.schedule.history`	Schedule	yes	no
117	`nefia.queue.list`	Queue	yes	no
118	`nefia.queue.show`	Queue	yes	no
119	`nefia.queue.cancel`	Queue	no	yes
120	`nefia.queue.retry`	Queue	no	yes
121	`nefia.status`	Diagnostics	yes	no
122	`nefia.doctor`	Diagnostics	yes	no
123	`nefia.explain`	Diagnostics	yes	no
124	`nefia.recording.list`	Diagnostics	yes	no
125	`nefia.recording.show`	Diagnostics	yes	no
126	`nefia.recording.delete`	Diagnostics	no	yes
127	`nefia.reactor.status`	Reactor	yes	no
128	`nefia.reactor.events`	Reactor	yes	no
129	`nefia.compliance.report`	Compliance	yes	no
130	`nefia.power.wake`	Power	no	yes
131	`nefia.power.reboot`	Power	no	yes
132	`nefia.power.shutdown`	Power	no	yes
133	`nefia.secrets.list`	Security	yes	no
134	`nefia.secrets.test`	Security	yes	no
135	`nefia.config.show`	Configuration	yes	no
136	`nefia.device_lock.status`	Security	yes	no
137	`nefia.device_lock.verify`	Security	yes	no
138	`nefia.posture.check`	Security	yes	no
139	`nefia.webhook.list`	Webhook	yes	no
140	`nefia.webhook.test`	Webhook	yes	no
141	`nefia.backup.list`	Backup	yes	no
142	`nefia.backup.create`	Backup	no	no
143	`nefia.run`	Composite	no	yes
144	`nefia.investigate`	Composite	yes	no
145	`nefia.file.deploy`	Composite	no	yes
146	`nefia.service.deploy`	Composite	no	yes
147	`nefia.config.apply`	Composite	no	yes
148	`nefia.system.baseline`	Composite	yes	no
149	`nefia.system.health`	Composite	yes	no
150	`nefia.tools.schema`	Discovery	yes	no
151	`nefia.approval.check`	Discovery	yes	no
152	`nefia.cluster.init`	Cluster	no	yes
153	`nefia.cluster.status`	Cluster	yes	no
154	`nefia.cluster.members`	Cluster	yes	no
155	`nefia.cluster.add_peer`	Cluster	no	yes
156	`nefia.cluster.remove_peer`	Cluster	no	yes
157	`nefia.sshca.init`	SSH CA	no	yes
158	`nefia.sshca.sign_user`	SSH CA	no	yes
159	`nefia.sshca.sign_host`	SSH CA	no	yes
160	`nefia.sshca.status`	SSH CA	yes	no
161	`nefia.sshca.trust`	SSH CA	no	yes
162	`nefia.sshca.server_snippet`	SSH CA	yes	no
163	`nefia.mtls.init`	mTLS	no	yes
164	`nefia.mtls.issue_client`	mTLS	no	yes
165	`nefia.mtls.status`	mTLS	yes	no
166	`nefia.mtls.revoke`	mTLS	no	yes
167	`nefia.team.current`	Team	yes	no
168	`nefia.team.list`	Team	yes	no
169	`nefia.team.use`	Team	no	no
170	`nefia.team.create`	Team	no	yes
171	`nefia.team.invite`	Team	no	yes
172	`nefia.team.join`	Team	no	no
173	`nefia.team.members`	Team	yes	no
174	`nefia.team.leave`	Team	no	yes
175	`nefia.team.role`	Team	no	yes
176	`nefia.profile.list`	Profile	yes	no
177	`nefia.profile.show`	Profile	yes	no
178	`nefia.profile.create`	Profile	no	no
179	`nefia.profile.delete`	Profile	no	yes
180	`nefia.profile.set_default`	Profile	no	no
181	`nefia.backup.restore`	Backup	no	yes
182	`nefia.backup.verify`	Backup	yes	no
183	`nefia.webhook.create`	Webhook	no	yes
184	`nefia.webhook.delete`	Webhook	no	yes
185	`nefia.webhook.update`	Webhook	no	no
186	`nefia.reactor.rule.create`	Reactor	no	yes
187	`nefia.reactor.rule.delete`	Reactor	no	yes
188	`nefia.reactor.rule.enable`	Reactor	no	no
189	`nefia.hosts.import`	Discovery	no	yes
190	`nefia.hosts.remove`	Discovery	no	yes
191	`nefia.hosts.refresh`	Discovery	no	no
192	`nefia.vpn.config`	VPN	yes	no
193	`nefia.vpn.enroll_status`	VPN	yes	no
194	`nefia.vpn.invite`	VPN	no	yes
195	`nefia.vpn.invite_list`	VPN	yes	no
196	`nefia.vpn.invite_revoke`	VPN	no	yes
197	`nefia.vpn.peer.stats`	VPN	yes	no
198	`nefia.device_lock.init`	Security	no	yes
199	`nefia.device_lock.revoke`	Security	no	yes
200	`nefia.device_lock.sign`	Security	no	no
201	`nefia.audit.verify`	Audit	yes	no
202	`nefia.recording.export`	Audit	yes	no
203	`nefia.schedule.trigger`	Schedule	no	yes
204	`nefia.agent.pin`	Agent	no	no
205	`nefia.validate`	Diagnostics	yes	no
206	`nefia.approval.list`	Approval	yes	no
207	`nefia.approval.respond`	Approval	no	no

Tool Annotations

Every tool declares annotations that inform the AI agent about the tool's behavior:

Annotation	Description
`readOnlyHint`	`true` if the tool only reads data and makes no changes.
`destructiveHint`	`true` if the tool can modify or delete data on the target.
`idempotentHint`	`true` if calling the tool multiple times with the same parameters produces the same result.
`openWorldHint`	`true` if the tool interacts with external systems beyond Nefia's control.

AI agents can use these annotations to make safer decisions about when to invoke destructive tools and when to request user confirmation.

Progressive Discovery & Compact Mode

The MCP server supports progressive tool discovery to minimize token usage. By default, tools/list returns tools in compact mode (~3,000 tokens) instead of full schemas (~27,000 tokens).

Compact Mode

In compact mode, each tool includes:

Field	Description
`name`	Tool name (e.g., `nefia.exec`).
`title`	Human-readable title (MCP spec 2025-06-18).
`description`	First line of the full description.
`category`	Tool category (one of 18 categories).
`typical_sequence`	Cross-references to related tools for workflow planning.
`required_params`	Count of required parameters.
`hints`	Flags: `destructive`, `read_only`, `idempotent`.
`related_tools`	Semantically related tools for cross-reference.
`enum`	Enum values for constrained parameters.

Control Parameters

Parameter	Type	Description
`_meta_compact`	boolean	Force compact mode (default: `true`).
`_meta_full`	boolean	Force full schema mode.
`_meta_categories`	string[]	Filter tools by category.

Precedence: _meta_compact takes priority over _meta_full.

On-Demand Schema Fetch

Use nefia.tools.schema to fetch the full schema for a specific tool:

json

{ "method": "tools/call", "params": { "name": "nefia.tools.schema", "arguments": { "tool": "nefia.exec" } } }

outputSchema

All 207 tools include outputSchema definitions that describe the structure of their response. AI agents can predict the response shape before calling a tool, enabling more reliable parsing and error handling.

All 205 core tools include related_tools in _meta for bidirectional semantic cross-references. This enables AI agents to discover related tools without fetching full schemas. For example, nefia.exec references nefia.sys.processes, nefia.sys.services, and nefia.sys.ports.

Resources

The MCP server exposes 22 read-only resources (20 static + 2 templates) that AI agents can query for context. Resources are accessed via the resources/read method with a uri parameter.

Static Resources

URI	Name	Description
`nefia://hosts`	Host List	All configured hosts with VPN status, tags, and OS information. Sensitive VPN fields (`InviteNonce`, `InviteExpires`) are redacted; only `status`, `vpn_addr`, `hostname`, and `os_name` are exposed.
`nefia://sessions`	Active Sessions	Currently active MCP sessions.
`nefia://policy/rules`	Policy Rules	Current policy configuration summary (non-sensitive).
`nefia://audit/recent`	Recent Audit Logs	Last 50 audit log entries.
`nefia://audit/stats`	Audit Statistics	Audit log statistics and summary metrics.
`nefia://config/summary`	Configuration Summary	Server configuration overview (non-sensitive).
`nefia://tools/categories`	Tool Categories	Tool categorization with descriptions.
`nefia://error-codes`	Error Codes	All domain error codes with descriptions and recovery tools.
`nefia://workflows`	Workflows	Available workflow prompts with descriptions.
`nefia://vpn/status`	VPN Status	Current VPN tunnel status and peer information.
`nefia://cluster/status`	Cluster Status	Raft cluster status (leader, followers, term).
`nefia://agent/fleet`	Agent Fleet	Agent status across all enrolled hosts.
`nefia://tools/graph`	Tool Graph	Tool dependency and relationship graph.
`nefia://quick-start`	Quick Start	Getting started guide for AI agents.
`nefia://hosts/health`	Host Health	Health status for all hosts.
`nefia://queue/state`	Queue State	Current queue state and pending entries.
`nefia://permissions/matrix`	Permissions Matrix	Permission matrix for tools and hosts.
`nefia://tools/approval-map`	Approval Map	Which tools require approval and under what conditions.
`nefia://vpn/invites`	VPN Invitations	Active VPN enrollment invitations. Returns structured fields: `host_id`, `os`, `expires_at`, `max_uses`, `used_count`, and `fleet`.
`nefia://device-lock/status`	Device Lock Status	Device-lock authority status, public key fingerprint, and signed host count.

Resource Templates

URI Template	Name	Description
`nefia://hosts/{id}`	Host Detail	Detailed information for a specific host.
`nefia://hosts/{id}/capabilities`	Host Capabilities	Policy capabilities and allowed operations for a host.

All resources return application/json content. The subscribe/unsubscribe methods exist, but the current CLI server does not emit automatic notifications/resources/updated events for these resources.

Prompts

The MCP server provides 51 pre-built prompt templates that guide AI agents through common workflows. Prompts are accessed via the prompts/get method with a name and arguments.

Core Workflows

health-check -- Verify target connectivity

Guides the agent through checking host connectivity and reporting status.

Argument	Required	Description
`target`	no	Host selector (e.g., `all`, `host:pc-office`, `tag:env=prod`). Defaults to `all`.

deploy-file -- Deploy file to multiple hosts

Guides the agent through deploying a file to target hosts with verification.

Argument	Required	Description
`target`	yes	Host selector for deployment targets.
`source_path`	yes	Path of the file to deploy on the remote host.
`dest_path`	yes	Destination path on the remote hosts.

diagnose-connectivity -- Troubleshoot host connectivity

Guides the agent through diagnosing connectivity issues with a specific host, including VPN status checks, basic command tests, and audit log review.

Argument	Required	Description
`host_id`	yes	ID of the host to diagnose.

security-audit -- Run security audit

Guides the agent through a security audit of target hosts, checking users, ports, updates, and firewall status.

Argument	Required	Description
`target`	yes	Host selector for audit targets.
`checks`	no	Comma-separated checks to run: `users`, `ports`, `updates`, `firewall`. Defaults to all.

bulk-exec -- Execute on multiple hosts with risk assessment

Guides the agent through executing a command across multiple hosts with safety checks and rollback guidance.

Argument	Required	Description
`target`	yes	Host selector for execution targets.
`command`	yes	Command to execute.
`dry_run`	no	If `true`, only preview without executing.

Policy & Access Workflows

policy-check-and-exec -- Check policy before executing

Pre-checks policy before execution, handling denials and JIT access requests.

Argument	Required	Description
`target`	yes	Host selector.
`command`	yes	Command to execute.

jit-elevated-exec -- Execute with JIT elevated access

Requests JIT elevated access and executes a command after approval.

Argument	Required	Description
`target`	yes	Host selector.
`command`	yes	Command requiring elevated access.
`role`	yes	Role to request.
`reason`	yes	Business justification.

File & Config Workflows

file-edit-workflow -- Safe file editing workflow

Guides through reading, editing, and verifying file changes with backup.

Argument	Required	Description
`host_id`	yes	Target host.
`path`	yes	File path to edit.

System Management Workflows

system-setup -- New system setup

Guides through initial system setup including user creation, package installation, and service configuration.

Argument	Required	Description
`host_id`	yes	Target host to set up.

incident-response -- Incident response workflow

Structured incident response: gather facts, check logs, identify issues, and remediate.

Argument	Required	Description
`host_id`	yes	Affected host.
`description`	yes	Incident description.

batch-rollout -- Staged batch rollout

Guides through rolling out changes across a fleet in stages with verification.

Argument	Required	Description
`target`	yes	Host selector.
`command`	yes	Command to roll out.

error-recovery -- Error recovery workflow

Guides through diagnosing and recovering from a specific error code.

Argument	Required	Description
`error_code`	yes	Error code to recover from.

Operations Workflows

software-upgrade -- Software upgrade workflow

Guides through safely upgrading software packages with pre/post checks.

Argument	Required	Description
`target`	yes	Host selector.
`package`	yes	Package to upgrade.

config-sync -- Configuration synchronization

Synchronize configuration files across multiple hosts.

Argument	Required	Description
`target`	yes	Host selector.
`config_path`	yes	Configuration file path.

log-analysis -- Log analysis workflow

Structured log analysis: search, correlate, and identify patterns.

Argument	Required	Description
`host_id`	yes	Target host.
`keywords`	yes	Keywords to search for.

secret-rotation -- Secret rotation workflow

Guides through rotating secrets and updating dependent services.

Argument	Required	Description
`provider`	yes	Secret provider name.

compliance-audit -- Compliance audit workflow

Comprehensive compliance audit against a security framework.

Argument	Required	Description
`framework`	yes	Framework: `soc2`, `iso27001`, or `hipaa`.

network-diagnostics -- Network diagnostics workflow

Comprehensive network diagnostics including ping, traceroute, DNS, and firewall checks.

Argument	Required	Description
`host_id`	yes	Target host.
`target_host`	no	Remote target to diagnose connectivity to.

Operations Workflows

verify-and-rollback -- Verify changes and rollback if needed

Guides through verifying deployed changes and rolling back on failure.

Argument	Required	Description
`host_id`	yes	Target host.
`service`	yes	Service to verify.

service-management -- Service lifecycle management

Manage service lifecycle: enable, start, monitor, and troubleshoot.

Argument	Required	Description
`host_id`	yes	Target host.
`service`	yes	Service name.

container-operations -- Container management workflow

Manage container lifecycle: list, inspect, logs, restart.

Argument	Required	Description
`host_id`	yes	Target host.

firewall-management -- Firewall rule management

Review, add, and verify firewall rules.

Argument	Required	Description
`host_id`	yes	Target host.

system-update -- System update workflow

Safely check, apply, and verify system updates.

Argument	Required	Description
`target`	yes	Host selector.

host-investigation -- Comprehensive host investigation

Deep investigation of a host's state, performance, and configuration.

Argument	Required	Description
`host_id`	yes	Target host.

disk-cleanup -- Disk cleanup workflow

Identify and clean up disk space on a host.

Argument	Required	Description
`host_id`	yes	Target host.

Security Workflows

ssh-hardening -- SSH hardening workflow

Harden SSH configuration on target hosts.

Argument	Required	Description
`host_id`	yes	Target host.

package-upgrade-safe -- Safe package upgrade workflow

Safely upgrade packages with backup, verification, and rollback.

Argument	Required	Description
`target`	yes	Host selector.
`package`	yes	Package to upgrade.

database-backup-verify -- Database backup and verify

Create and verify database backups.

Argument	Required	Description
`host_id`	yes	Database host.

log-investigation -- Log investigation workflow

Deep log investigation with correlation across services.

Argument	Required	Description
`host_id`	yes	Target host.
`timeframe`	no	Time range to investigate (e.g., `1h`, `24h`).

user-onboarding -- User onboarding workflow

Set up a new user account with proper access and configuration.

Argument	Required	Description
`host_id`	yes	Target host.
`username`	yes	Username to create.

Infrastructure Workflows

cluster-management -- Initialize and manage a Raft cluster

Guides the agent through initializing a Raft cluster, adding peers, monitoring status, and performing failover.

Argument	Required	Description
`action`	no	Cluster action: `init`, `status`, `add-peer`, or `failover`. Defaults to `status`.

sshca-setup -- Initialize SSH CA and manage certificates

Guides the agent through initializing the SSH Certificate Authority, signing user and host certificates, and configuring trust.

Argument	Required	Description
`action`	no	SSH CA action: `init`, `sign-user`, `sign-host`, or `trust`. Defaults to `init`.

mtls-gateway-setup -- Configure mTLS gateway for AI agents

Guides the agent through initializing the mTLS CA, issuing client certificates, and verifying mTLS status.

Argument	Required	Description
`client_name`	no	Name for the client certificate to issue.

team-onboarding -- Create a team and invite members

Guides the agent through creating a team workspace, inviting members, and assigning roles.

Argument	Required	Description
`team_name`	no	Name for the new team.

backup-and-restore -- Create, verify, and restore backups

Guides the agent through creating a backup, verifying its integrity, and restoring from a backup archive.

Argument	Required	Description
`action`	no	Backup action: `create`, `verify`, or `restore`. Defaults to `create`.

webhook-reactor-setup -- Configure event-driven automation

Guides the agent through creating webhooks, setting up reactor rules, and testing the event pipeline.

Argument	Required	Description
`action`	no	Setup action: `webhook`, `reactor`, or `test`. Defaults to `webhook`.

vpn-troubleshooting -- Diagnose and resolve VPN issues

Guides the agent through diagnosing VPN connectivity problems, checking peer status, and rebuilding tunnels.

Argument	Required	Description
`target`	no	Host selector for VPN diagnostics. Defaults to `all`.

device-verification -- Initialize and manage device verification

Guides the agent through initializing device-lock, signing devices, and verifying authorization.

Argument	Required	Description
`action`	no	Device lock action: `init`, `sign`, or `verify`. Defaults to `init`.

cluster-failover -- Detect and recover from cluster failures

Guides the agent through detecting cluster leader failures and performing safe failover recovery.

Argument	Required	Description
`target_node`	no	Node ID to promote as new leader.

host-onboarding -- End-to-end host onboarding workflow

Guides the agent through importing hosts, generating VPN invitations, enrolling agents, and verifying connectivity.

Argument	Required	Description
`source`	no	Import source: `ssh-config`, `ansible`, `csv`, or `manual`. Defaults to `manual`.

agent-fleet-management -- Manage agent versions and health

Guides the agent through checking agent versions, upgrading fleet-wide, pinning versions, and monitoring health.

Argument	Required	Description
`target`	no	Host selector for agent management. Defaults to `all`.

Advanced Workflows

performance-troubleshoot -- Performance troubleshooting workflow

Guides through diagnosing performance issues: CPU, memory, disk I/O, network, and process analysis.

Argument	Required	Description
`host_id`	yes	Target host to investigate.

canary-deploy -- Canary deployment workflow

Guides through canary deployment: deploy to a subset, monitor metrics, and promote or rollback.

Argument	Required	Description
`target`	yes	Host selector for canary targets.
`service`	yes	Service to deploy.

config-audit -- Configuration audit workflow

Audit configuration consistency across hosts and detect drift.

Argument	Required	Description
`target`	yes	Host selector for audit targets.

Resilience Workflows

database-restore -- Database restore workflow

Guides through database restore from backup with verification and rollback.

Argument	Required	Description
`host_id`	yes	Database host.
`backup_path`	yes	Path to the backup archive.

cascading-error-handling -- Cascading error handling workflow

Guides through handling cascading failures across dependent services.

Argument	Required	Description
`host_id`	yes	Starting host.
`service`	yes	Service experiencing failures.

multi-host-coordination -- Multi-host coordination workflow

Coordinate operations across multiple hosts with dependency ordering and rollback.

Argument	Required	Description
`target`	yes	Host selector.
`operation`	yes	Operation to coordinate.

performance-baseline -- Performance baseline workflow

Establish and compare performance baselines for hosts.

Argument	Required	Description
`host_id`	yes	Target host.

ssl-cert-renewal -- SSL certificate renewal workflow

Guides through SSL/TLS certificate renewal, validation, and service restart.

Argument	Required	Description
`host_id`	yes	Target host.
`cert_path`	no	Path to the certificate file.

capacity-planning -- Capacity planning workflow

Analyze resource usage trends and plan capacity requirements.

Argument	Required	Description
`target`	yes	Host selector for analysis targets.

maintenance-window -- Maintenance window workflow

Coordinate a maintenance window: pre-checks, execution, verification, and sign-off.

Argument	Required	Description
`target`	yes	Host selector for maintenance targets.
`description`	yes	Description of the maintenance activity.

Error Handling

The MCP server uses two error categories:

Domain errors (tool execution failures) are returned as successful JSON-RPC responses with isError: true in the content. These indicate that the tool was invoked but the operation failed (e.g., file not found, permission denied, policy blocked).
Protocol errors (invalid params, unknown tool) are returned as standard JSON-RPC error responses. These indicate that the request itself was malformed.

All domain errors include structured remediation data in the data field:

Field	Type	Description
`error_code`	string	Uppercase domain code (e.g., `HOST_NOT_FOUND`, `POLICY_DENIED`).
`hint`	string	Human-readable error message.
`transient`	boolean	Whether the error is transient (safe to retry).
`retry_after_ms`	int	Suggested wait time before retry (present for transient errors).
`recovery_tool`	string	MCP tool to call for recovery (e.g., `nefia.hosts.list`, `nefia.vpn.diagnose`).
`suggested_actions`	string[]	Actionable remediation steps.
`diagnostics`	string[]	Diagnostic commands to run.
`example`	object	Example tool call the agent can try.
`host_id`	string	Context: host involved in the error.
`path`	string	Context: file path involved in the error.
`command`	string	Context: command that caused the error.
`invalid_param`	string	Parameter name that failed validation (for `INVALID_PARAMS` errors).
`constraint`	string	Description of the constraint that was violated.
`example_value`	string	Example of a valid value for the invalid parameter.
`rule_name`	string	Name of the policy rule that matched (for `POLICY_DENIED` errors).
`denied_pattern`	string	The specific pattern that was denied by policy.
`failure_stage`	string	Stage where a composite operation failed (e.g., `"download"`, `"validate"`, `"rollback"`).
`rollback_status`	string	Status of the rollback operation after a composite failure (`"success"`, `"failed"`, `"skipped"`).

The transient flag indicates whether the error is temporary (e.g., network timeout, rate limit) or permanent (e.g., policy denied, host not found). AI agents should only retry operations when transient is true. The recovery_tool field suggests which MCP tool to call to resolve the error — for example, HOST_NOT_FOUND suggests calling nefia.hosts.list, and SFTP_FAILED suggests calling nefia.vpn.diagnose.

Error Classification

Error classification is performed exclusively via sentinel error matching with errors.Is(). No string-based fallback is used. All domain errors are produced using the types.Errorf(types.ErrXxx, "message") pattern and are mapped to the appropriate RPC error code through precise error-chain matching with errors.Is().

Related sentinel errors are grouped under the same RPC code. For example, ErrFileNotFound, ErrPermissionDenied, and ErrFileTooLarge all map to SFTPFailed (-32006), while ErrVPNSetupFailed, ErrDERPConnectFailed, and ErrDERPAuthFailed all map to VPNFailed (-32009).

Domain Error Codes

Code	Name	Description
`-32001`	`PolicyDenied`	The operation was blocked by the policy engine.
`-32002`	`PathDenied`	The requested path is outside the session root (sandbox escape).
`-32003`	`SSHAuthFailed`	SSH authentication failed (invalid key, no auth methods accepted).
`-32004`	`SSHConnFailed`	SSH connection failed (host unreachable, no active VPN).
`-32005`	`CmdTimeout`	The command exceeded its configured timeout.
`-32006`	`SFTPFailed`	An SFTP operation failed. This code also covers `FILE_NOT_FOUND`, `PERMISSION_DENIED`, and `FILE_TOO_LARGE` errors.
`-32007`	`SessionNotFound`	The specified session ID does not exist or has expired.
`-32008`	`HostNotFound`	The specified host ID was not found in the configuration.
`-32009`	`VPNFailed`	A VPN tunnel operation failed (tunnel down, dial error). This code also covers `VPN_SETUP_FAILED`, `DERP_CONNECT_FAILED`, and `DERP_AUTH_FAILED` errors.
`-32010`	`SessionRequired`	A session is required but was not provided.
`-32011`	`PlaybookFailed`	The playbook definition is invalid or execution failed.
`-32012`	`CommandFailed`	The remote command completed but returned a non-zero exit code.
`-32013`	`AccessDenied`	Authentication, licensing, or team permission error.
`-32014`	`Cancelled`	The operation was cancelled by the user or timed out.
`-32015`	`DeviceLockDenied`	The device failed device-lock verification (Ed25519 key mismatch).
`-32016`	`PostureDenied`	The device did not meet the required posture policy.
`-32017`	`SecretResolveFailed`	A secret reference could not be resolved.
`-32018`	`ClusterNotLeader`	This operation must be performed on the Raft cluster leader.
`-32019`	`ServerNotInitialized`	The MCP client has not sent the `initialize` handshake.
`-32020`	`SudoDisabled`	Sudo is not enabled in the configuration.
`-32021`	`SudoDenied`	The sudo command was denied by the policy engine.
`-32022`	`JITRequired`	Just-In-Time access is required for this operation.
`-32023`	`VPNNotReady`	The VPN tunnel is not yet established. Transient — retry after delay.
`-32024`	`ScheduleNotFound`	The specified schedule was not found.
`-32025`	`QueueEntryNotFound`	The specified queue entry was not found.
`-32026`	`QueueInvalidState`	The queue entry is in an invalid state for this operation.
`-32027`	`JobNotFound`	The specified job ID was not found.
`-32028`	`ConcurrencyLimit`	All concurrent dispatch slots are in use. Transient — includes `retry_after_ms`.
`-32029`	`RateLimited`	The request was rejected because the MCP rate limit was exceeded. The response includes a `retry_after_ms` field.
`-32030`	`AuthRequired`	Authentication is required for this operation (team/auth context).
`-32031`	`ServiceDeployFailed`	The `service.deploy` composite operation failed during one of its stages.
`-32032`	`ConfigApplyFailed`	The `config.apply` composite operation failed during one of its stages.
`-32033`	`BaselineDrift`	The `system.baseline` comparison detected configuration drift.
`-32034`	`MountFailed`	A filesystem mount operation failed.
`-32035`	`ContainerFailed`	A container operation failed.
`-32036`	`ClusterJoinFailed`	The node failed to join the Raft cluster. Transient — retry after delay.
`-32037`	`SSHCASigningFailed`	SSH CA certificate signing failed.
`-32038`	`StreamTimeout`	A streaming file transfer timed out. Transient — retry with `nefia.fs.stream_read_resumable`.
`-32039`	`FeatureDisabled`	The requested feature is not enabled in `nefia.yaml`. Enable it in the configuration and retry.
`-32601`	`MethodNotFound`	The requested tool or method does not exist. Use `nefia.tools.schema` to discover available tools.

Sentinel Error Grouping

Multiple sentinel errors may map to the same RPC code. AI agents should use the error_code field (e.g., SFTP_FAILED) to determine the broad category and the hint field to identify the specific cause (e.g., "file not found: /path/to/file").

RPC Code	Sentinel Errors
`-32004` (`SSHConnFailed`)	`ErrSSHConnFailed`, `ErrSSHSessionFailed`
`-32006` (`SFTPFailed`)	`ErrSFTPFailed`, `ErrFileNotFound`, `ErrPermissionDenied`, `ErrFileTooLarge`
`-32009` (`VPNFailed`)	`ErrVPNFailed`, `ErrVPNSetupFailed`, `ErrDERPConnectFailed`, `ErrDERPAuthFailed`
`-32012` (`CommandFailed`)	`ErrCmdExitNonZero`
`-32013` (`AccessDenied`)	`ErrAuthRequired`, `ErrAuthExpired`, `ErrDeviceLimitExceeded`, `ErrLicenseDenied`, `ErrTeamNotFound`, `ErrTeamAccessDenied`, `ErrTeamMemberLimit`, `ErrTeamInviteInvalid`
`-32602` (`InvalidParams`)	`ErrConfigInvalid`, `ErrSelectorInvalid`

All other domain error codes have a one-to-one mapping to their sentinel errors.

Protocol Error Codes

Code	Name	Description
`-32700`	`ParseError`	Invalid JSON was received.
`-32600`	`InvalidRequest`	The JSON sent is not a valid request object.
`-32601`	`MethodNotFound`	The method does not exist or is not available.
`-32602`	`InvalidParams`	Invalid method parameter(s).
`-32603`	`InternalError`	Internal JSON-RPC error.

The server uses a blocking dispatch semaphore (50 concurrent request slots). When all slots are in use, incoming requests wait for a slot to become available rather than being rejected immediately. If the request's context is cancelled while waiting (e.g., client disconnect or timeout), the server returns -32603 (internal error) with the message: "server is busy: all request slots are in use; retry after a short delay or reduce concurrent requests with --concurrency". Lightweight methods (such as approval responses) bypass the semaphore entirely to prevent deadlocks.

Multi-Host Response Format

When a tool targets multiple hosts, the response includes additional tracking fields:

Field	Type	Description
`operation_id`	string	Unique job ID for tracking the multi-host operation.
`partial_success`	boolean	`true` if some hosts succeeded and others failed.
`failure_summary`	object	Failures grouped by error code, each with `count`, `host_ids` (max 20), and `recovery_tool`.

Rate Limiting

The MCP server enforces rate limits configured in nefia.yaml under the mcp.rate_limit section. When the limit is exceeded, the server returns error code -32029 (RateLimited) with a retry_after_ms field indicating how long to wait.

yaml

mcp:
  rate_limit:
    rate: 1.0      # requests per second
    burst: 10

Limits & Safety

The MCP server enforces hard limits on content size and execution time to protect both the operator host and remote targets.

Content Field Limit (7 MB)

All MCP content fields (content and content_base64 in tool parameters and responses) are capped at 7 MB (7,340,032 bytes). Both text and base64-encoded content are subject to this limit. Because base64 encoding inflates data by approximately 33%, a 7 MB base64 string corresponds to roughly 5.25 MB of decoded binary data.

Requests that exceed the content limit are rejected with an InvalidParams error before any remote operation is attempted. For files larger than the content limit, use nefia.fs.stream_read and nefia.fs.stream_write, which transfer data without buffering in the MCP content field.

Exec Timeout Cap (2 Hours)

The maximum allowed timeout for nefia.exec operations is 2 hours (7,200,000 ms), regardless of the value requested by the client. If a client specifies a timeout_ms value greater than 7,200,000, it is silently clamped to the cap. The default timeout comes from the configuration (typically 30 minutes) and applies when timeout_ms is omitted.

Per-Client Session Limit (50)

Each MCP client is limited to 50 concurrent sessions. Attempting to open a 51st session returns an error. Sessions are tracked per client, so separate clients each have their own independent limit. This prevents a single client from exhausting server resources.

Log Sanitization

MCP notification logs automatically redact sensitive fields before emission:

URLs: Query parameters in URLs are replaced with ?REDACTED
Headers: Authorization and Proxy-Authorization header values are masked
Parameters: command, verify_command, path, token, secret, and password values are redacted
Bearer tokens: Strings of 12 or more alphanumeric characters matching bearer token patterns are masked

This ensures that sensitive data does not leak into MCP log notifications, even when verbose logging is enabled.

Host Resource Redaction

The nefia://hosts/inventory resource and host-related resources redact sensitive VPN fields. Only status, vpn_addr, hostname, and os_name are exposed in VPN information. Internal fields such as InviteNonce and InviteExpires are stripped from the response.

mTLS Client Identity

When mTLS is enabled, the MCP server extracts the AgentIdentity from the client certificate, including a Serial field derived from the certificate's serial number. This serial is logged in MCP client connection messages and used for multi-client identification in audit logs, enabling operators to trace which client certificate was used for each MCP session.

Approval Configuration

The mcp.approval section is active when enabled: true and nefia mcp serve is running. In the current implementation:

approval-specific MCP tools are advertised when approval is enabled; when disabled, they are still advertised with (not configured) descriptions for discoverability
tools and hosts use exact matching
commands and paths use prefix matching (e.g., command pattern rm matches rm -rf /, path pattern /etc matches /etc/passwd)
the first matching rule wins
require_approval: false acts as an explicit exemption rule
nefia.sshca.sign_user has mandatory approval that cannot be exempted by rules; it always requires human approval when the approval workflow is enabled

Error Recovery Decision Tree

AI agents should follow this decision tree when a tool call returns an error:

Extract the error code from the details.error_code field in the error response (e.g., HOST_NOT_FOUND, POLICY_DENIED, SSH_AUTH_FAILED).
Check if the error is retryable:
- RATE_LIMITED: Wait for retry_after_ms, then retry the same call.
- SSH_CONN_FAILED: Call nefia.vpn.diagnose to check connectivity, then retry after the issue is resolved.
- CMD_TIMEOUT: Increase timeout_ms or split the command into smaller operations.
- POLICY_DENIED: Do not retry. Explain to the user why the operation was blocked.
- HOST_NOT_FOUND: Call nefia.hosts.list to find the correct host ID.
- SESSION_NOT_FOUND: The session expired or was closed. Open a new session with nefia.session.open.
Call nefia.explain for remediation guidance:
json
```
{ "method": "tools/call", "params": { "name": "nefia.explain", "arguments": { "error_code": "SSH_AUTH_FAILED" } } }
```
The response includes suggested_actions, diagnostics (tool calls to run), and an example (a tool call to try).
Follow the suggested actions from nefia.explain. Run the recommended diagnostics tools and adjust your approach based on results.
If the error persists after remediation, report the error to the user with the error code, hint message, and the steps you have already taken.

Configuration

Configure MCP rate limits, policy mode, and server settings.

CLI Reference

Full reference for the nefia mcp serve command.

Sessions Guide

Learn how sessions provide sandboxed file operations for MCP tools.

Agent Patterns

Best practices for AI agents using Nefia MCP tools.