MCP Integration

Nefia includes a built-in MCP (Model Context Protocol) server that lets AI agents manage your infrastructure through the same policy-governed interface as the CLI. AI agents can execute commands, read and write files, and gather system facts — all within the guardrails you define.

What is MCP?

The Model Context Protocol is an open standard for connecting AI models to external tools. Instead of giving an AI agent raw SSH access, MCP provides a structured interface where every operation is:

• Named and typed — Each tool has a schema describing its inputs and outputs.
• Policy-governed — The same allow/deny rules from your Nefia policy engine apply to MCP operations.
• Audited — Every MCP call is recorded in the append-only audit log.

Starting the MCP Server

Launch the MCP server on your operator PC:

nefia mcp serve

The server communicates over stdio using JSON-RPC 2.0. AI agents connect by spawning the nefia mcp serve process and reading/writing to its stdin/stdout.

Prerequisites

Before connecting an AI agent, make sure the following are in place:

1. Log in first. The MCP server requires authentication. Run nefia login in your terminal before starting the server. If you skip this step, the server exits immediately with an error — but most MCP clients don't display stderr, so it will look like a silent connection failure.

2. Ensure nefia is in your PATH. MCP clients spawn the server process directly without loading your shell profile (.zshrc, .bashrc, etc.). If nefia was installed via go install or placed in a custom directory, the client may not find it. Use the full path to be safe:

   json

   {
     "mcpServers": {
       "nefia": {
         "command": "/usr/local/bin/nefia",
         "args": ["mcp", "serve"]
       }
     }
   }

   To find your nefia path: run which nefia on macOS/Linux, or where nefia / Get-Command nefia (PowerShell) on Windows.

3. Windows: use the cmd /c wrapper. On Windows, some MCP clients cannot execute .exe files directly. Wrap the command:

   json

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

Connecting AI Agents

Claude Desktop

Add Nefia to your Claude Desktop MCP configuration:

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

Claude Code

Add Nefia as an MCP server in your project settings:

claude mcp add nefia -- nefia mcp serve

Codex CLI (OpenAI)

Add the following to ~/.codex/config.toml:

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

OpenClaw

Add Nefia to your openclaw.json:

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

OpenClaw's always-on, autonomous nature makes it a powerful but sensitive integration. See the dedicated OpenClaw Integration guide for security hardening, approval workflows, and best practices.

Other MCP Clients

Any MCP client that supports stdio transport can connect by spawning nefia mcp serve and communicating over stdin/stdout with JSON-RPC 2.0. Once connected, the AI agent discovers all available tools automatically through the MCP handshake.

Available Tools

The MCP server exposes 207 tools (205 core plus 2 approval workflow tools), 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. The approval tools are always advertised to AI agents for discoverability, even when the approval workflow is not configured. All tools include outputSchema definitions for predictable response parsing. The server also provides 51 workflow prompts, 22 resources (20 static + 2 templates), and progressive tool discovery via nefia.tools.schema with compact mode (~3,000 tokens vs ~27,000 full).

Session Management

Each MCP client is limited to 50 concurrent sessions. Attempting to open a 51st session returns an error. nefia.session.list returns only the calling client's own sessions — one client cannot see or close sessions created by another client.

Command Execution

File Operations

Multi-Host File Operations

Host Inventory

Playbooks

System Information

Package Management

User Management

Cron Management

Service Management

Network Diagnostics

Firewall Management

System Updates

Mount Management

Container Management

VPN & Connectivity

Policy

JIT Access

Audit

Agent Management

Schedule

Queue Management

Diagnostics

Reactor

Power Management

Secrets & Compliance

Configuration & Backups

Device Security

Webhooks

Composite Tools

Discovery & Policy

Compact Tool Discovery

By default, tools/list returns tool schemas in compact mode, reducing token usage by ~90%. Compact responses include only the tool name, description, category, typical_sequence, and hints (destructive, read_only, idempotent).

To retrieve full JSON Schema definitions for specific tools, use nefia.tools.schema:

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

To request full schemas for all tools at once, pass _meta_full: true in tools/list:

{
  "method": "tools/list",
  "params": { "_meta_full": true }
}

Cluster Management

SSH Certificate Authority

Mutual TLS

Team Management

Profile Management

Rate Limiting

Configure rate limits for MCP operations in your nefia.yaml:

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

When the rate limit is exceeded, the MCP server returns a JSON-RPC error with data.retry_after_ms. Well-behaved AI agents should wait for that interval before retrying.

Approval Workflow

The MCP server supports an approval workflow that pauses matching operations until a human approves or denies them. The two approval tools (nefia.approval.list and nefia.approval.respond) are always advertised to AI agents so they can discover the workflow, but they only become functional when the approval workflow is enabled in the configuration.

When mcp.approval.enabled: true, the MCP server:

• Evaluates each tool invocation against the configured approval rules
• Pauses matching operations and sends a notifications/message with type: "approval_required"
• Blocks until a human responds or the configured timeout elapses (default: 30 seconds)
• Applies default_action (default: "deny") when the timeout expires

Approval Tools

Rule Matching

Rule matching uses the first-match-wins strategy:

• tools uses exact tool-name matching
• commands and paths use prefix matching
• hosts uses exact matching
• require_approval: false acts as an explicit exemption rule

Policy Enforcement

The MCP server enforces the same policy rules as the CLI. The policy engine is configured under policy in nefia.yaml. There is no way for an AI agent to bypass a deny rule or access a restricted path.

The policy engine has three modes:

• off -- No policy evaluation; all operations are allowed.
• warn -- Violations are logged as warnings but operations proceed.
• enforce (default) -- Violations are blocked and operations are rejected.

Policy evaluation uses deny_commands, allow_commands, deny_paths, and allowed_roots. Deny rules are checked first. If an allow list is defined, the operation must match at least one allow pattern:

policy:
  mode: enforce
  deny_commands:
    - "^rm -rf /$"
    - "^mkfs\\."
  allow_commands:
    - "^systemctl (status|reload)"
    - "^cat "
    - "^ls "
  deny_paths:
    - "^/etc/shadow$"
    - "^/etc/passwd$"
  allowed_roots:
    - "^/home/"
    - "^/var/www/"

For role-based access control, define named roles with their own rule sets:

policy:
  mode: enforce
  roles:
    - name: developer
      hosts: ["^dev-"]
      allow_commands: ["^git ", "^make "]
      deny_paths: ["^/etc/"]
    - name: operator
      hosts: [".*"]
      deny_commands: ["^rm -rf /"]

roles[].hosts is matched against host IDs, and the active role comes from the target host's role field in nefia.yaml. The current implementation does not derive roles from the operator identity.

Error Handling

The MCP server classifies errors from tool execution into two categories:

• Domain errors -- The tool invocation was accepted but the operation failed (e.g., file not found, permission denied, policy blocked). These are returned as successful JSON-RPC responses with isError: true in the content. AI agents can inspect these errors and self-correct.
• Protocol errors -- The request itself is malformed (e.g., unknown tool, missing parameters). These are returned as standard JSON-RPC error responses.

All error classification is performed via sentinel error matching with errors.Is(). No string-comparison fallback is used. Each domain error includes error_code, hint, and suggested_actions to help AI agents determine the next course of action.

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\":\"file not found: config.yaml\",\"code\":-32006,\"details\":{\"error_code\":\"SFTP_FAILED\",\"hint\":\"file not found: config.yaml\",\"suggested_actions\":[\"Verify the remote path exists\",\"Check file permissions on the remote host\"]}}"
    }
  ],
  "isError": true
}

Each error response includes additional context fields to help AI agents self-recover:

• transient -- Whether the error is temporary (safe to retry) or permanent.
• retry_after_ms -- Suggested wait time before retry (present for transient errors like rate limiting or VPN timeouts).
• recovery_tool -- The MCP tool to call for recovery. For example, HOST_NOT_FOUND suggests nefia.hosts.list, and SFTP_FAILED suggests nefia.vpn.diagnose.
• host_id, path, command -- Context fields identifying the host, file path, or command involved in the error.

For a complete list of error codes, see the MCP Protocol Reference.

Audit Logging

Every MCP tool invocation is recorded in the append-only audit log. Each entry includes the tool name, parameters, target host, result status, and timestamp. This provides a complete trail of all AI agent activity for compliance and debugging.

Example: Claude Managing a Web Server

Here is a practical example of an AI agent using Nefia MCP to diagnose and fix a web server issue:

{ "tool": "nefia.hosts.list" }

{ "tool": "nefia.facts", "arguments": { "target": "host:prod-web-1" } }

{ "tool": "nefia.session.open", "arguments": { "host_id": "prod-web-1", "root": "/etc/nginx" } }

{ "tool": "nefia.fs.read", "arguments": { "session_id": "a1b2c3d4", "path": "nginx.conf" } }

{ "tool": "nefia.fs.patch", "arguments": { "session_id": "a1b2c3d4", "path": "nginx.conf", "unified_diff": "--- a/nginx.conf\n+++ b/nginx.conf\n@@ ... @@\n ..." } }

{ "tool": "nefia.exec", "arguments": { "target": "host:prod-web-1", "command": "nginx -t && systemctl reload nginx" } }

Every step in this workflow is logged in the audit trail, policy-checked, and sandboxed to the session root.

Rate Limiting Best Practices

The MCP server enforces rate limits to protect both the operator host and remote targets. Understanding and working within these limits is essential for reliable AI agent operation.

Default Limits

These defaults apply when mcp.rate_limit is not configured in nefia.yaml. Operators can customize them:

mcp:
  rate_limit:
    rate: 1.0    # more conservative: 1 request per second
    burst: 10

Handling 429 (Rate Limited) Responses

When the rate limit is exceeded, the server returns error code -32029 (RateLimited) with a retry_after_ms field:

{
  "error": {
    "code": -32029,
    "message": "rate limit exceeded",
    "data": { "retry_after_ms": 1500 }
  }
}

AI agents should wait for the specified retry_after_ms duration before retrying. Do not retry immediately -- this will only prolong the rate limiting.

Reducing Request Count

• Use batch parameters. Instead of calling nefia.exec per host, use target: "group:production" to execute on all hosts in one call.
• Use nefia.facts instead of multiple nefia.exec calls. A single nefia.facts call gathers OS, disk, memory, CPU, uptime, and network information in one SSH round-trip per host.
• Use nefia.status for quick checks. One call returns VPN status, host counts, queue depth, and session count -- avoiding multiple separate queries.
• Use sessions for multi-step operations. Opening a session avoids re-specifying host_id on every call.

Exec Extensions

The nefia.exec tool supports additional parameters for production-grade orchestration:

• env -- Inject environment variables into remote commands. Secret provider references (${provider:path}) are automatically resolved.
• dry_run -- Preview target resolution and policy checks without executing. Returns which hosts would be targeted and whether the operation is allowed.
• batch_size / batch_wait -- Rolling execution across large fleets. Execute on N hosts at a time with configurable pause between batches.
• subset -- Execute on a random subset of N hosts for canary testing.
• rerun / last_job_id -- Re-execute on hosts from a previous job. Target only failed or successful hosts.
• fail_fast -- Stop execution immediately when the first host fails. Remaining hosts are skipped.
• min_success_rate -- Minimum success rate (0.0–1.0) required to continue. If the rate drops below this threshold, remaining hosts are skipped.
• stdin -- Standard input to pipe to the command.
• working_directory -- Working directory for command execution (relative to session or host root).

For full tool reference and schemas, see the MCP Protocol Reference.

Related