NIOS WAPI MCP — read gateway

A Model Context Protocol (MCP) server that lets Claude Desktop read an on-prem Infoblox NIOS Grid through its WAPI REST API — IPAM, DNS, DHCP, and grid health, in plain language. It is read-only by design: no write tools exist in this server, so nothing it does can change your grid.

Here's the shape. You run one server — the gateway — and many people connect to it over HTTPS. Each grid is reached through its own read-only NIOS account that lives on the server, so a person connecting needs no grid login at all. One endpoint can serve several grids; the reader picks which one per conversation.

For the design reasoning and guardrail model, see docs/DESIGN.md and the decision record in docs/adr/0001-host-nios-mcp-server.md.

Read-only by construction. The gateway runs python -m nios_mcp.gateway, which never imports any write code — "read-only" is a property of the program, not a flag you could flip. Pair it with a read-only NIOS service account and the guarantee is enforced by the grid too.

---

Run it

One server on a host, TLS in front, many readers connecting over HTTPS. Pick the platform:

• Docker + Caddy (Linux): docs/setup-hosted-docker.md — the quickstart. Deep follow-along on a real Ubuntu VM: docs/deploy-ubuntu-vm.md.
• Windows Server + IIS: docs/setup-hosted-iis.md — same gateway, IIS instead of Caddy for TLS. Deep reference: docs/deploy-windows-iis.md.

Both run the identical nios_mcp package; only the run and front-door layer differs.

Configure the grids

The gateway's whole configuration is two files in deploy/gateway/:

• grids.yaml — the registry: one entry per grid (host, WAPI version, read-only account, TLS setting, default view).
• .env — the endpoint clients connect to (hostname + HTTPS port).

Write both by answering prompts, no hand-editing YAML:

python -m nios_mcp.gateway_setup_cli

It lists, adds, updates, or removes grids, sets the endpoint, and prints the deploy command plus the Claude Desktop entry to paste. To start from the examples instead, copy deploy/gateway/grids.example.yaml → grids.yaml and deploy/gateway/.env.example → .env and edit them.

Quick connectivity check

Before deploying, you can confirm an account can authenticate and read:

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # fill in WAPI_PASSWORD etc.
set -a; source .env; set +a
python smoke_test.py           # expects "Auth + read OK"

Connect Claude Desktop

Readers connect with no credentials through the mcp-remote bridge. The setup CLI prints the exact config block; nios-reader-setup.py can also write it for a reader. In Claude Desktop, ask list_grids, then use_grid("lab"), then your read. There's no silent default — until a grid is chosen, the gateway says which grids are available (a single-grid registry is selected automatically).

---

What's configuration, not code

Nothing about which grid you talk to is hardcoded. Each grid entry in grids.yaml carries:

• Connection: host, wapi_version, user, password, verify_tls
• Behavior: default_dns_view

Each account is read-only. To add or move a grid you edit the registry (or rerun the setup CLI) — never the Python.

---

Tools

You interact with these in plain language in Claude Desktop — the sample prompts below are just examples. Placeholders (example.net, 192.0.2.x) stand in for your grid's real zones and networks. Every tool reads; none of them change the grid.

Networks & IPAM

• search_networks — find networks by CIDR fragment or comment, with overall and DHCP utilization. Big grids: ask to summarize for a utilization overview. Try: "Show the networks containing 192.0.2 with their utilization."
• list_addresses — every address in a network and how it's used (DNS, DHCP, fixed, or discovered/UNMANAGED). Big subnets: ask for a summary or fewer fields. Try: "Summarize address usage in 192.0.2.0/24."
• next_available_ip — the next free address(es) in a network (doesn't reserve). Try: "What's the next available IP in 192.0.2.0/24?"
• list_network_containers — the supernets you carve subnets out of. Try: "List the network containers."
• next_available_network — a free subnet of a given size inside a container. Try: "Find a free /24 inside 10.0.0.0/16."

DNS

• search_dns_records — find A / host / CNAME (etc.) records by name. Try: "Find DNS records with 'web' in the name."
• reverse_lookup — what a given IP is used for (names, record types, MAC). Try: "What is 192.0.2.10?"
• list_dns_zones — the authoritative zones the grid serves. Try: "List the DNS zones on the grid."
• list_zone_records — every record inside a zone (big zones: ask to summarize). Try: "Show all records in the example.net zone."
• list_dns_views / list_network_views — the DNS and network view names. Try: "List the DNS views."
• list_extensible_attributes — the custom EA definitions on the grid. Try: "List the extensible attributes."
• global_search — find any object of any type by name/IP. Try: "Search the grid for anything named 'web'."
• get_object_by_ref / get_grid_info — fetch any object by its ref; grid status.

Grid infrastructure

• list_grid_members — appliances: IP, platform, HA role, and per-node model (hwtype) + serial (hwid). Lean by default; ask to include services when you need health. Try: "List the grid members with service status."
• list_licenses — installed licenses with type and expiry, tied to each member. Try: "Show the grid licenses and when they expire."

DHCP

• list_dhcp_ranges — DHCP ranges by network. Try: "List the DHCP ranges in 192.0.2.0/24."
• list_fixed_addresses — DHCP reservations (IP↔MAC). Try: "Show the fixed addresses in 192.0.2.0/24."
• list_failover_associations — DHCP failover pairs by name. Try: "List the DHCP failover associations."
• list_dhcp_leases — active DHCP leases (by network or address). Try: "What DHCP leases are active on 192.0.2.0/24?"

Workflows

• grid_health_report — one-shot health summary: utilization hotspots, member service/HA issues, and licenses expiring soon. Try: "Give me a grid health report."

Multi-grid selection

• list_grids — the grids this gateway serves. Try: "Which grids can I read?"
• use_grid — pick the grid for this conversation. Try: "Use the lab grid."