MCP Server

Control NexoralDNS from any AI agent on your local network — Claude Code, Codex, Copilot, Antigravity, and more — through the same login and permissions as the dashboard.

The MCP tool server (`tools/`) is a fifth, independent NexoralDNS process that speaks the Model Context Protocol (MCP) — the open standard that lets an LLM call external tools. It is a thin protocol translator: every tool call becomes a real HTTP request against the same authenticated REST API the dashboard uses, so no new authorization model exists anywhere. Whatever role and permissions your dashboard account has are exactly what your AI agent can do — nothing more.

The MCP tool server ships as part of the standard Docker install, alongside the DNS engine, dashboard, and DHCP server — the install script already starts it for you as a 5th managed process (ecosystem.config.js / PM2). There's nothing to install or run separately.

Connecting to the MCP server does not authenticate you — that only happens when the login tool is explicitly called with a dashboard username and password, exactly like the dashboard's own login form. Every other tool checks for an active session first and refuses with "Not logged in — call the login tool first" until you do.

Every tool call checks GET /api/health first (cached ~3s to stay cheap). If MongoDB, Redis, RabbitMQ, or the API itself is down, you get a clear "server is not healthy" error instead of a confusing connection failure. check_server_health and get_server_info work without logging in at all, so they double as a first diagnostic step.

claude mcp add --transport http nexoraldns http://<your-server-LAN-IP>:4774/mcp

Use the change_password tool: current password admin, new password <your new password>

Then swap your new username and password into every "say this" prompt below.

$ claude mcp add --transport http nexoraldns http://localhost:4774/mcp

Verify with claude mcp get nexoraldns — should show Status: ✔ Connected. Then open Claude Code and type:

Login to the nexoraldns MCP server with username admin and password admin

$ codex mcp add nexoraldns --url http://localhost:4774/mcp

Real CLI add command, config stored in ~/.codex/config.toml. Then open Codex and type:

Login to the nexoraldns MCP server with username admin and password admin

No documented single-line flag command — use one of these two instead.

/mcp add

Fill the form: Name = nexoraldns, Type = HTTP, URL = http://localhost:4774/mcp. Or edit the config file directly:

{
  "mcpServers": {
    "nexoraldns": {
      "type": "http",
      "url": "http://localhost:4774/mcp"
    }
  }
}

Then open Copilot CLI and type:

Login to the nexoraldns MCP server with username admin and password admin

Settings → Customizations tab → "Open MCP Config". Note the key is serverUrl, not url — different from every other client here.

{
  "mcpServers": {
    "nexoraldns": {
      "serverUrl": "http://localhost:4774/mcp"
    }
  }
}

Save, hit refresh in the Installed MCP Servers panel, then open a chat and type:

Login to the nexoraldns MCP server with username admin and password admin

Same serverUrl format, shared or CLI-specific config file (no add command):

Confirm with /mcp inside a session, then type:

Login to the nexoraldns MCP server with username admin and password admin

{
  "mcp": {
    "nexoraldns": {
      "type": "remote",
      "url": "http://localhost:4774/mcp"
    }
  }
}

If it connects, the same prompt logs you in:

Login to the nexoraldns MCP server with username admin and password admin

If it supports the Streamable HTTP transport (the current MCP spec standard), the same URL works the same way — including the login flow, since that's implemented once in tools/'s own tool logic, not per-client.