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.

Authentication is standard OAuth 2.1, the same flow you have seen on hosted MCP servers: an unauthenticated request gets a 401, your client shows the server as "needs authentication", and approving it opens your browser on a NexoralDNS sign-in page. You type your dashboard credentials there — never into the chat — and the client receives a token it attaches to every later request.

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 need no account permissions of their own, 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>

From then on, use your new credentials on the sign-in page the OAuth flow opens.

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

Verify with claude mcp get nexoraldns. A fresh install shows Status: ⚠ needs authentication — that is the expected first state. Run /mcp inside Claude Code, pick nexoraldns, and choose Authenticate.

The client will report the server as needing authentication. Approve it and your browser opens the NexoralDNS sign-in page — sign in there once, and the client stores the token and refreshes it on its own from then on.

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

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

The client will report the server as needing authentication. Approve it and your browser opens the NexoralDNS sign-in page — sign in there once, and the client stores the token and refreshes it on its own from then on.

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:

The client will report the server as needing authentication. Approve it and your browser opens the NexoralDNS sign-in page — sign in there once, and the client stores the token and refreshes it on its own from then on.

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:

The client will report the server as needing authentication. Approve it and your browser opens the NexoralDNS sign-in page — sign in there once, and the client stores the token and refreshes it on its own from then on.

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

Confirm with /mcp inside a session:

The client will report the server as needing authentication. Approve it and your browser opens the NexoralDNS sign-in page — sign in there once, and the client stores the token and refreshes it on its own from then on.

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

If it connects, signing in works the same way:

The client will report the server as needing authentication. Approve it and your browser opens the NexoralDNS sign-in page — sign in there once, and the client stores the token and refreshes it on its own from then on.

If it supports the Streamable HTTP transport and the MCP authorization spec (both current standards), the same URL works the same way — the sign-in flow is plain OAuth 2.1 with Dynamic Client Registration and PKCE, so nothing is client-specific.