Netbox MCP — Tool Structure Analysis & Agent Fit Report

Date: May 2026

FMCP Version: 0.6

Agent: Claude.ai (Web based)

Scanned: 2026-05-07
Scope: Full tool surface of both connected Netbox MCP servers (mcp__Netbox__* and mcp__claude_ai_Netbox__*)

1. System Inventory (What Is In This Netbox)

This is a Star Trek-themed demo environment. Everything is live and queryable.

Regions (5)

Alpha Quadrant, Beta Quadrant, Gamma Quadrant, Delta Quadrant, Klingon Empire

Sites (8)

Site Region Devices
Starbase-1 Alpha Quadrant 5
Deep Space 9 Alpha Quadrant 3
Bajor Relay Gamma Quadrant 1
Utopia Planitia Beta Quadrant 1
Qonos Prime Klingon Empire 3
Tygokor Fleet Yard Klingon Empire 1
Rura Penthe Relay Klingon Empire 1
Starfleet Border Front Klingon Empire 1

Devices (16 total)

Federation fleet: uss-enterprise-rtr01, starbase1-core-sw01, uss-defiant-rtr01, ds9-ops-core-sw01, ds9-promenade-acc-sw01, bajor-rtr01, and others.
Klingon network: iks-qonos-core-01, iks-tygokor-core-01, iks-rura-edge-01, iks-border-edge-01, iks-cloak-gw-01, iks-subspace-dns-01.

Manufacturers (5)

Daystrom Industries, Soong Technologies, Cardassian Union Fabrication, Yoyodyne Propulsion Systems, Klingon Imperial Engineering.

IPAM

  • VRFs (5): MGMT-VRF (65000:10), DATA-VRF (65000:20), HOLONET-VRF (65000:30), TRANSPORTER-VRF (65000:40), klingon-imperial-vrf (65070:1)
  • Prefixes (19): Supernets (10.10.0.0/16, 10.20.0.0/16, etc.) with site-level /24 children; Klingon /24 and /32 loopbacks in 10.70.0.0/16
  • IP Addresses (9): All assigned to device interfaces, with DNS names (e.g., uss-enterprise-rtr01.mgmt.starbase1, cloak-gw-01.klingon.empire)
  • VLANs (9): Federation (10-MGMT, 20-DATA, 30-HOLONET, 40-TRANSPORTER) + Klingon (command-bridge/701, shipyard-forge/703, prison-relay/704, border-intel/705, cloaking-transit/799)

2. MCP Tool Structure

Two Servers, Two Permission Levels

Server Permission Observation
mcp__Netbox__* Read-only token Schema loads fine; all data queries return "You do not have permission to perform this action." — token has no object permissions
mcp__claude_ai_Netbox__* Full CRUD token All list/retrieve/create/update/destroy operations work

This two-token split is intentional and correct: agents doing read-only research (audit, compliance, documentation) use the safe token. Write operations escalate to the full-CRUD token. The mismatch in this environment is that the read-only token has no data permissions at all — in production you'd want read granted to that token so it can actually serve read workloads.

Group Dispatcher Pattern

The dominant structure is a group dispatcher: a single MCP tool that represents an entire API domain, taking resource and action as parameters.

mcp__claude_ai_Netbox__dcim(resource='device', action='list', params={...})

Calling with action='help' returns the full resource/action tree for that group.

Group Dispatcher Underlying Tools Collapsed Resources
dcim 418 47
ipam 162 18
extras 177 21
circuits 101 11
users 55 7
tenancy 54 6
virtualization 64 7
vpn 90 10
wireless 27 3
Total 1,148 130

Plus ~14 standalone tools for cross-cutting concerns: datafile_list/retrieve, datasource_list/retrieve, job_list/retrieve, objectchange_list/retrieve, objecttype_list/retrieve, rqtask_list/retrieve, rqworker_list/retrieve.

Total exposed MCP tools: ~23 (9 dispatchers + 14 standalones), representing 1,148 underlying API operations.

Actions Available Per Group

Read-only server: list, retrieve, trace, paths, elevation, choices
Full-CRUD server adds: create, update, partial_update, destroy, bulk_update, bulk_partial_update, bulk_destroy, plus resource-specific specials (render_config on device, sync on datasource, enqueue/requeue/stop on rqtask)

3. Token Savings

At Tool Schema Load Time

When an agent connects to an MCP server, the entire tool list and its schemas are loaded into context. This is the primary token cost.

Approach Tools Loaded Approximate Schema Tokens
Raw API (one tool per endpoint) 1,148 ~400,000+
Flat MCP (one MCP tool per endpoint) 1,148 ~200,000+
Group Dispatcher (this Netbox MCP) ~23 ~3,000–5,000
frisian-mcp style (intent-based) ~15–30 ~2,000–4,000

The group dispatcher achieves roughly 50:1 schema token compression — a 1,148-tool API exposed as 23 MCP tools. This is a material win. An agent starting a conversation with a raw API server would burn most of its usable context on tool schemas before doing any work.

The key mechanism: each dispatcher schema is tiny (three fields: resource, action, params). The actual parameter schemas are discovered lazily via action='help' only when needed.

At Runtime

Each action='help' round-trip costs one tool call. For a workflow touching 3 resource types an agent hasn't seen before, that's 3 extra calls. For steady-state agents that already know the resource vocabulary, the help call is skippable entirely. This is an acceptable tradeoff.

4. Does This Tool Structure Fit What Agents Naturally Want?

What Agents Want From MCP Tooling

Agents work best with:

  1. A small, stable, predictable tool list (ideally < 30 tools)
  2. Tool names that map to intent, not API structure
  3. Operations that are atomic across related resources
  4. Idempotent calls (safe to retry)
  5. Error messages that guide the next correct action
  6. No prerequisite domain knowledge baked into parameter names

How the Netbox Group Dispatcher Scores

Criterion Score Notes
Small tool list ✅ Good 23 tools is workable
Stable vocabulary ✅ Good resource/action pattern is consistent across all groups
Intent-mapped names ⚠️ Partial mcp__Netbox__dcim(resource='device', action='list') is readable but requires knowing dcim contains devices
Atomic multi-resource ops ❌ Missing Agent must manually chain: site → device → interface → prefix → IP address for device onboarding
Idempotency ❌ Missing create fails if object exists; agent must list-check-then-create
Agent-friendly errors ⚠️ Partial Raw API errors pass through; they're readable but not prescriptive
Zero prerequisite knowledge ❌ Requires Agent must know "device" lives under "dcim", not "ipam" or "extras"

The group dispatcher is a significant improvement over flat MCP or raw API access for agents, but it still exposes the full Netbox resource taxonomy to the agent. The agent is doing API navigation, not task execution.

The Core Gap: Resource Navigation vs. Intent Execution

A Netbox-savvy agent asked to "add a new router at Starbase-1 with a management IP" must:

  1. Know that devices live under dcim
  2. Know that interfaces live under dcim
  3. Know that IP addresses live under ipam and get linked to dcim.interface
  4. Know that the prefix must exist before the IP can be assigned
  5. Know that assigned_object_type must be "dcim.interface" not "device"
  6. Handle partial failures (device created, IP assignment failed) with no rollback

That is a lot of domain knowledge that must live in the agent's system prompt — or the agent must rediscover it every session via help() and trial/error.

5. frisian-mcp vs. Netbox Group Dispatcher vs. Direct API

Direct REST API

  • Token cost: Catastrophic — full OpenAPI spec would consume entire context window
  • Agent fit: Poor — agents must construct raw HTTP calls with correct URL patterns, query parameters, and payload shapes
  • Error handling: Raw HTTP status codes, no guidance
  • Best for: Human developers with a browser and autocomplete

Flat MCP (one tool per endpoint)

  • Token cost: High — 1,148 tool schemas in context
  • Agent fit: Slightly better than raw API (tool names are self-describing) but tool selection becomes a needle-in-haystack problem at this scale. Research shows LLM tool accuracy degrades significantly above ~30 tools
  • Error handling: Same as direct API
  • Best for: Small APIs (< 30 endpoints) where the full schema fits cleanly

Group Dispatcher (this Netbox MCP)

  • Token cost: Low — 23 tool schemas, lazy help() for params
  • Agent fit: Good for agents that already have Netbox domain expertise embedded in their system prompt or training. Poor for zero-shot agents
  • Atomic workflows: None — all cross-resource workflows must be orchestrated by the agent
  • Error handling: Raw API errors passed through
  • Best for: Netbox-expert agents doing discrete, scoped operations (audit a prefix, retrieve a device config, update a site description)

frisian-mcp Style (intent-based, business-logic layer)

  • Token cost: Low — same dispatcher compression ratio, but tools are named and scoped by intent
  • Agent fit: Excellent — tools match what the agent is trying to accomplish, not what the API supports
  • Atomic workflows: Yes — a single tool call can span multiple Netbox resources with internal rollback
  • Idempotency: Built in — tools check for existing state before creating
  • Error handling: Domain-aware — "Device already exists at this site; did you mean to update it?" instead of "400 Bad Request"
  • Business rules: Enforced — can't assign a Klingon VLAN to a Federation device
  • Best for: Every agent use case involving real network changes

Comparison Summary

Tool Fit for Agents (High = Better)

Direct API         ████░░░░░░  Low
Flat MCP           ██████░░░░  Medium
Group Dispatcher   ████████░░  Good
frisian-mcp style   ██████████  Excellent

The group dispatcher is the right architectural direction. frisian-mcp takes the same pattern one level higher: instead of grouping by API domain (dcim, ipam), it groups by operator intent (provision device, audit IP space, document site topology).

6. Observations Useful for the frisian-mcp Demo

1. The Two-Server Split Is a Demo-Ready Feature

Show the read-only server (mcp__Netbox__) alongside the full-CRUD server. This demonstrates that frisian-mcp can vend different capability levels to different consumers — an audit agent gets read tools, a provisioning agent gets write tools — without changing the tool names the agent knows.

2. The Data Is Already Rich Enough to Demo Cross-Resource Queries

"Give me all devices at Klingon Empire sites with their management IPs" requires joining dcim.device → dcim.site → dcim.interface → ipam.ipaddress. An agent using the raw dispatcher must make 4+ tool calls and assemble the join manually. A frisian-mcp tool named device_detail_with_ip returns it in one call. This is a concrete, demonstrable win.

3. The render_config Action Is a Strong Demo Hook

mcp__claude_ai_Netbox__dcim(resource='device', action='render_config', params={'id': N}) renders a device's Golden Config template. This is exactly the kind of operation that belongs in frisian-mcp: one tool, one intent, one result — no matter how many Netbox internals it touches.

4. Idempotency Is the Invisible Win

Show an agent calling a frisian-mcp tool twice (simulating a retry or re-run). The second call succeeds (or reports "already exists, no change") instead of raising a 400 error. This is what makes agents safe to run in automation without human supervision.

5. The objectchange Resource Is an Audit Trail

mcp__claude_ai_Netbox__objectchange_list gives the full change log with user, timestamp, before/after data. A frisian-mcp tool can wrap this as audit_recent_changes(site='Starbase-1', hours=24) — instantly useful to an agent doing incident investigation without any Netbox knowledge required.

6. The Klingon Network Is Architecturally Separate

The Klingon VRF (klingon-imperial-vrf, rd=65070:1) is completely separate from the Federation VRFs (65000:10–40). This models a real multi-tenant or multi-org network. A frisian-mcp demo can show tenant-scoped tools that enforce "a Klingon agent only sees Klingon data" — multi-tenancy as a tool design property, not an afterthought.

7. Missing Data Reveals What Netbox MCP Can't Guard Against

No custom fields are defined, no tags are in use, and several devices have no primary IP assigned. An agent using the raw dispatcher can happily create a device with no primary IP and no platform — an invalid state for automation. frisian-mcp tools can enforce required fields at the tool layer, before the API is even called.

8. Token Budget Arithmetic for Presentations

Concrete numbers to use:

  • Raw Netbox API: ~1,000+ endpoints, full OpenAPI spec ~1.5MB / ~400k tokens
  • Flat MCP: ~1,148 tools, schema payload ~150k tokens
  • Group Dispatcher: ~23 tools, schema payload ~4k tokens
  • frisian-mcp: ~20–25 intent tools, schema payload ~3k tokens
  • Token reduction from raw API to dispatcher: ~99%
  • Remaining context is available for actual work, reasoning, and data