> For the complete documentation index, see [llms.txt](https://docs.nimux.wiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nimux.wiki/mcp-integration.md).

# MCP Integration

nimux includes a separate MCP wrapper for AI clients that can call tools through the Model Context Protocol.

The wrapper lives outside the main binary:

```
integrations/mcp/nimux-mcp/
```

The main `nimux` binary stays independent. The MCP wrapper calls it as a subprocess, applies policy checks, redacts sensitive output by default, and returns structured JSON responses.

### Build

```bash
cd integrations/mcp/nimux-mcp
nimble build -y
```

### Run

```bash
NIMUX_BIN=/usr/local/bin/nimux \
NIMUX_MCP_POLICY=./policy.example.json \
./nimux_mcp
```

Environment variables:

```
NIMUX_BIN          Path to nimux. Defaults to nimux in PATH.
NIMUX_MCP_POLICY   JSON policy file. Optional.
NIMUX_MCP_STATE    Pivot state JSON file. Defaults to a temp file.
```

### Transport

The wrapper supports:

```
Content-Length framed JSON-RPC for MCP clients
newline-delimited JSON-RPC for local tests
```

Newline test:

```json
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
```

Framed request:

```
Content-Length: 67

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
```

### Client Config

Use the same wrapper binary for all MCP clients. The main difference is the client config file format.

#### Codex

Codex uses `config.toml`.

User-level config:

```
~/.codex/config.toml
```

Project-level config:

```
.codex/config.toml
```

Example:

```toml
[mcp_servers.nimux]
enabled = true
required = false
command = "/opt/nimux/integrations/mcp/nimux-mcp/nimux_mcp"
env = {
  NIMUX_BIN = "/usr/local/bin/nimux",
  NIMUX_MCP_POLICY = "/opt/nimux/mcp-policy.json",
  NIMUX_MCP_STATE = "/opt/nimux/nimux-mcp-state.json"
}
startup_timeout_sec = 10.0
tool_timeout_sec = 120.0
```

Restart Codex after changing the config. Then verify that the `nimux.*` tools are available in the MCP tool list.

#### Claude Desktop

Claude Desktop uses an `mcpServers` JSON object.

Example:

```json
{
  "mcpServers": {
    "nimux": {
      "command": "/opt/nimux/integrations/mcp/nimux-mcp/nimux_mcp",
      "env": {
        "NIMUX_BIN": "/usr/local/bin/nimux",
        "NIMUX_MCP_POLICY": "/opt/nimux/mcp-policy.json",
        "NIMUX_MCP_STATE": "/opt/nimux/nimux-mcp-state.json"
      }
    }
  }
}
```

Restart Claude Desktop after saving the config.

#### Cursor

Cursor MCP configuration uses the same `mcpServers` JSON shape:

```json
{
  "mcpServers": {
    "nimux": {
      "command": "/opt/nimux/integrations/mcp/nimux-mcp/nimux_mcp",
      "env": {
        "NIMUX_BIN": "/usr/local/bin/nimux",
        "NIMUX_MCP_POLICY": "/opt/nimux/mcp-policy.json",
        "NIMUX_MCP_STATE": "/opt/nimux/nimux-mcp-state.json"
      }
    }
  }
}
```

After reloading Cursor, ask it to list available MCP tools and confirm the `nimux.*` tools appear.

#### Windsurf

Windsurf also supports stdio MCP servers through an `mcpServers` style config:

```json
{
  "mcpServers": {
    "nimux": {
      "command": "/opt/nimux/integrations/mcp/nimux-mcp/nimux_mcp",
      "env": {
        "NIMUX_BIN": "/usr/local/bin/nimux",
        "NIMUX_MCP_POLICY": "/opt/nimux/mcp-policy.json",
        "NIMUX_MCP_STATE": "/opt/nimux/nimux-mcp-state.json"
      }
    }
  }
}
```

Restart or reload the Windsurf MCP configuration after saving changes.

#### Generic MCP Client

Any MCP client that supports stdio servers can run:

```
command: /opt/nimux/integrations/mcp/nimux-mcp/nimux_mcp
```

Environment:

```
NIMUX_BIN=/usr/local/bin/nimux
NIMUX_MCP_POLICY=/opt/nimux/mcp-policy.json
NIMUX_MCP_STATE=/opt/nimux/nimux-mcp-state.json
```

#### Local Development

```json
{
  "mcpServers": {
    "nimux-dev": {
      "command": "/home/katana/nim/integrations/mcp/nimux-mcp/nimux_mcp",
      "env": {
        "NIMUX_BIN": "/home/katana/nim/nimux",
        "NIMUX_MCP_POLICY": "/home/katana/nim/integrations/mcp/nimux-mcp/policy.example.json"
      }
    }
  }
}
```

For local tests without a full client, use the newline JSON-RPC mode:

```bash
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | NIMUX_BIN=/home/katana/nim/nimux \
    NIMUX_MCP_POLICY=/home/katana/nim/integrations/mcp/nimux-mcp/policy.example.json \
    /home/katana/nim/integrations/mcp/nimux-mcp/nimux_mcp
```

### Tools

Implemented tool names:

```
nimux.scan
nimux.smb_enum
nimux.ldap_query
nimux.kerberos_request
nimux.winrm_command
nimux.remote_exec
nimux.socks_deploy
nimux.socks_status
nimux.socks_cleanup
nimux.proxy_scan
nimux.gpo_dry_run
nimux.gpo_apply
nimux.file_operation
nimux.database_query
nimux.secrets
nimux.protocol_probe
nimux.report_summary
```

### Safety Policy

Example policy:

```json
{
  "scope": {
    "name": "corp-lab",
    "domains": ["corp.local"],
    "cidrs": ["10.10.10.0/24"],
    "hosts": ["dc01.corp.local"]
  },
  "defaults": {
    "redact": true,
    "require_approval": true,
    "evidence_dir": "./evidence",
    "rollback_dir": "./rollback"
  },
  "allow": {
    "read_only": true,
    "remote_execution": false,
    "secrets": false,
    "dcsync": false,
    "ldap_writes": false,
    "gpo_writes": false,
    "socks_deploy": false,
    "proxy_reuse": true
  }
}
```

By default, read-only actions are allowed and high-risk actions are blocked.

High-risk tools require `approval_id` when `require_approval` is true.

### Progress

For MCP clients that support progress notifications, pass `progress_token` in the tool arguments.

Example:

```json
{
  "target": "dc01.corp.local",
  "ports": "445,389,5985",
  "open_only": true,
  "progress_token": "scan-001"
}
```

The wrapper emits progress notifications when the command starts, while long commands continue, and when the command finishes.

### Pivoting

The MCP wrapper models `nimux socks` as a pivot lifecycle:

```
deploy pivot
store pivot metadata
reuse pivot_id in later tools
resolve pivot_id to --proxy
cleanup pivot
```

Deploy:

```json
{
  "target": "host01.corp.local",
  "username": "administrator",
  "password": "<password>",
  "domain": "corp.local",
  "listener": "10.10.14.10",
  "socks_port": 1080,
  "control_port": 1081,
  "approval_id": "approved-001"
}
```

Reuse:

```json
{
  "pivot_id": "pivot-123",
  "target": "10.20.30.0/24",
  "ports": "445,389,5985"
}
```

Cleanup:

```json
{
  "pivot_id": "pivot-123",
  "username": "administrator",
  "password": "<password>",
  "domain": "corp.local",
  "approval_id": "approved-002"
}
```

### Response Shape

Command wrappers return a text content block containing JSON:

```
exit_code
argv
stdout
stderr
duration_ms
timed_out
json
```

`json` contains parsed JSON or JSONL output when available. Sensitive keys and sensitive output lines are redacted by default.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nimux.wiki/mcp-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.