MCP (agent interface)#

MCP is rackattack’s front door for an LLM agent. The Model Context Protocol adapter is a thin secondary transport — alongside gRPC, REST, and GraphQL — that maps the same service core to agent tools. It runs over JSON-RPC on stdio, so an agent launches rackattack mcp as a subprocess and calls tools directly; no network port, no auth handshake.

Every screen-generating tool returns structured data and a rendered diagram in one reply (the diagram comes back base64-encoded under render.image), so an agent gets both the facts and the picture from a single call.

MCP is a convenience layer, not the foundation: the gRPC/REST/GraphQL APIs stand on their own. It exists so an agent can drive the infra graph conversationally.

The ten read tools#

The adapter exposes the ten read operations 1:1 with the core. All are read-only — mutations are not exposed over MCP.

Tool	What it answers
`power_blast_radius`	What goes dark if a feed/PDU trips.
`trace_cable_path`	The hop-by-hop path from a device port.
`get_rack`	A rack elevation by power/health.
`thermal_headroom`	Cooling headroom and hotspots for a scope.
`fabric_topology`	Network fabric and congestion for a scope.
`floor_plan`	A floor’s racks by health.
`search_devices`	Find devices by free-text query.
`get_device`	One device’s details.
`get_port`	One port’s details.
`render`	Render a screen (`blast-radius`/`cable-path`/`rack`/`thermal`/`fabric`) for a ref to an SVG/HTML artifact.

The prompt → tool-call mapping for each screen — which tool fires for a given question, with the example-preset refs that reproduce the narrative outcomes — lives in TOOLS.md.

Ref grammar gotcha: most tools take a typed ref (feed:, rack:, floor:, site:), but trace_cable_path takes two bare args (from_device, from_port) — no prefix.

Setup (with an agent)#

Build the binary, then register the server once, pointing it at the binary (it reads DATABASE_URL, default the local single-node CockroachDB):

claude mcp add rackattack -- "$PWD/bin/rackattack" mcp

Now just ask in natural language — the agent picks the tool, fills the args, and gets back the data plus the diagram:

“What goes dark if feed B-3 trips?” → power_blast_radius{ source_ref: "feed:B-3" }
“Show me the floor plan for dfw-02/1.” → floor_plan{ scope_ref: "floor:dfw-02/1" }
“Trace the cable from tor-12a port et-0/0/3.” → trace_cable_path{ from_device: "tor-12a", from_port: "et-0/0/3" }

See the quickstart for the full example-preset question set.

Setup (no agent — drive MCP by hand)#

MCP is just JSON-RPC frames on stdio, so you can drive it with printf + jq. Pipe an initialize frame then a tools/call, and pull the diagram out of the reply:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"power_blast_radius","arguments":{"source_ref":"feed:B-3"}}}' \
  | ./bin/rackattack mcp \
  | jq -r 'select(.id==2) | .result.content[0].text | fromjson | .render.image' \
  | base64 -d > blast-radius.svg

open blast-radius.svg   # macOS  (Linux: xdg-open)

Swap power_blast_radius for any tool (get_rack, thermal_headroom, floor_plan, …) and adjust the arguments accordingly.

MCP (agent interface)#

The ten read tools#

Setup (with an agent)#

Setup (no agent — drive MCP by hand)#

See also#