netdiag-mcp

A working Model Context Protocol server that exposes read-only network diagnostics as tools an AI client can call directly. This isn't a demo of the concept, it's a real server built against the official MCP Python SDK, with tests that actually run and a CI workflow that actually checks them.

All topology data is fabricated. No real hostnames, IPs, or credentials appear anywhere in this repo.

Why this exists

I run infrastructure for a real multi-site network, and the tools I use day to day (monitoring, ticketing, identity, and increasingly, MCP-connected AI clients) are only as useful as the boundary around what they're allowed to touch. This repo is that boundary made explicit and testable: five tools, all read-only, each one narrow enough to reason about on its own.

It's also a companion to two other repos:

• agentic-infra-ops-toolkit — the architecture and decision record behind building this pattern in the first place.

• network-iac-lab — the same four-layer redundancy model (circuit, power, core, access) that root_cause reasons over here, expressed as infrastructure-as-code instead of a diagnostics API.

Tools

root_cause is the one worth reading the code for: it doesn't just report what's broken, it reasons about which broken layer probably explains the others, based on the same circuit-power-core-access dependency order laid out in network-iac-lab's redundancy model.

Running it

pip install -e ".[dev]"
pytest tests/ -v

To run the server itself against an MCP client (stdio transport):

python3 -m netdiag_mcp.server

Point an MCP-compatible client (Claude Desktop, or any client using the official SDK) at this module and the five tools above become callable directly.

Design choices

• Diagnostics logic is separate from protocol wiring. Everything in diagnostics.py is plain Python with no MCP import, tested with plain pytest. server.py is a thin layer that exposes those functions as tools. If the MCP SDK's API changes, the actual logic doesn't need to.

• Every tool is read-only. None of them can change state on a real system, only report on the sample data in sample_data/topology.json. A write-capable version of this would be a deliberate, separate addition, not something that falls out of a more "helpful" read tool by accident.

• Errors are data, not exceptions that reach the client uncaught. An unknown site returns a structured error dict instead of letting an unhandled exception surface, so a calling AI client gets something it can reason about instead of a stack trace.

Tests

8 tests covering the diagnostics logic: health status aggregation, root-cause tracing across multiple failure scenarios, redundancy gap detection, and the unknown-site error path. Run in CI on every push via .github/workflows/test.yml.