# Netboxlabs Platform Mcp

> >

- **Type:** Skill
- **Install:** `agentstack add skill-netboxlabs-skills-netboxlabs-platform-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [netboxlabs](https://agentstack.voostack.com/s/netboxlabs)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [netboxlabs](https://github.com/netboxlabs)
- **Source:** https://github.com/netboxlabs/skills/tree/main/skills/netboxlabs-platform-mcp

## Install

```sh
agentstack add skill-netboxlabs-skills-netboxlabs-platform-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# NetBox Labs Platform MCP Server

The **Platform MCP Server** is a hosted Model Context Protocol server (on NetBox Cloud) that puts a NetBox instance behind an MCP tool surface so an agent can read and modify NetBox data. It is distinct from the open-source [`netbox-community/netbox-mcp-server`](https://github.com/netbox-community/netbox-mcp-server): the platform server adds **Code Mode**, per-user auth, dynamic plugin/model detection, and first-party product integrations (Assurance, Discovery).

> **Your knowledge of this server may be outdated.** It is Public Preview; tool inventories, helper signatures, and available namespaces are generated live per deployment and evolve. Always discover the real surface (schema search / tool list) before acting — never assume an object type, endpoint, or helper exists.

## Retrieval Sources

| Source | URL / Method | Use for |
|--------|-------------|---------|
| Platform MCP docs | `https://netboxlabs.com/docs/cloud/platform-mcp-server` | Setup, client configs, auth, modes |
| Community MCP server | `https://github.com/netbox-community/netbox-mcp-server` | The open-source read-only alternative |
| Live server | The connected MCP server itself | The authoritative tool list + `netbox_search_schema` are the source of truth |

## Connect & Auth

- **Endpoint:** `https://.cloud.netboxapp.com/mcp`
- **Transport:** MCP over **streamable HTTP** (no stdio — it is a networked, hosted server, not a local subprocess).
- **Auth:** `Authorization: Bearer nbt_` — a **NetBox v2 API token** (prefix `nbt_`, available on NetBox 4.5+). With per-user auth, your own token's NetBox RBAC applies to every call.
- Customers enable the server on their instance via NetBox Labs support.

Any MCP-over-streamable-HTTP client works (Claude Code/Desktop, Cursor, VS Code, ChatGPT Developer Mode). The docs page has copy-paste client configs.

## FIRST: Identify Your Mode

The server exposes tools in one of three modes; **what you see in the tool list tells you which mode you're in**:

- **Code Mode** — you see exactly **three** tools: `netbox_search_schema`, `netbox_execute`, `rediscover_netbox`. Higher tiers default here. This is the primary, most efficient surface.
- **Discrete Mode** — you see ~34 `netbox_*` tools (plus plugin/product tools). Each operation is its own tool.
- **Both** — you see all of the above.

If you see `netbox_execute`, use Code Mode. If you only see discrete `netbox_*` tools, jump to [Discrete Mode](#discrete-mode).

---

## Code Mode

Instead of dozens of discrete tools (one round-trip each, bloated context), Code Mode exposes three tools whose arguments are **Python code**. You write a short program that calls injected NetBox helpers, does its own filtering/joining/looping in-process, and returns a single `result`. This collapses many tool round-trips into one.

### The three tools

| Tool | Argument | What it does |
|------|----------|--------------|
| `netbox_search_schema(code)` | Python reading a pre-loaded `schema` var, assigning `result` | **Discovery.** Local filtering of an in-memory schema dict — no NetBox I/O. Confirm object types, endpoints, filters before acting. |
| `netbox_execute(code)` | Python calling injected helpers, assigning `result` | **The workhorse.** Runs your program against NetBox and returns `result`. Its description is generated live, listing the exact helpers available in *this* deployment. |
| `rediscover_netbox()` | none | **Recovery only.** Re-probes NetBox and reconciles the tool inventory/schema. Use sparingly — see below. |

### The golden loop (minimize round trips)

1. **Search the schema first — don't guess.** Call `netbox_search_schema` to confirm the right object type, filter field, or special endpoint. Guessing object types/paths is the #1 failure mode.
2. **Write ONE `netbox_execute` program that does the whole job** — fetch, filter, join, loop, compute in a single program. Never call `netbox_execute` once per object when a loop or one list call would do.
3. **Always assign `result`.** If you never assign it you get back "Code ran successfully but did not assign to `result`" — a wasted turn.
4. **Project fields** with `fields=[...]` on reads to keep payloads (and the result-size cap) small.
5. **Prefer named helpers over raw `api()`** — they carry validation and clearer errors.

```python
# netbox_search_schema — confirm the type/filters first
result = {k: v for k, v in schema['object_types'].items() if v['app'] == 'dcim'}
```
```python
# netbox_execute — do the whole task in one program
sites = get('dcim.site', filters={'name': 'NYC-DC1'}, fields=['id', 'name'])
site_id = sites['results'][0]['id']
devs = get('dcim.device', filters={'site_id': site_id, 'status': 'active'},
           fields=['id', 'name', 'role', 'primary_ip4'], limit=1000)
result = {'site': 'NYC-DC1', 'count': devs['count'], 'devices': devs['results']}
```

### The sandbox contract (what your code may do)

`netbox_execute` / `netbox_search_schema` run through a validated sandbox. Respect these or your code is rejected:

- **NO `import` / `from ... import`.** This is the single most common failure — agents reach for `json`, `re`, `ipaddress`, `math`, `collections`. **Everything you need is already in the namespace or in allowed builtins.** Never write `import`.
- **NO class definitions, `del`, `async`/`await`/`yield`.**
- **NO dunder / introspection** (`eval`, `exec`, `open`, `getattr`, `globals`, `__class__`, `__subclasses__`, etc. are blocked).
- **Allowed builtins only** — the common ones: `len`, `str`, `int`, `float`, `bool`, `list`, `dict`, `set`, `tuple`, `range`, `enumerate`, `zip`, `sorted`, `sum`, `min`, `max`, `any`, `all`, `abs`, `round`, `map`, `filter`.
- **Loops, wall-clock time, and result size are capped** — keep programs bounded; project fields to stay under the result cap.
- **Must assign `result`.**
- **HTTP errors surface the NetBox response body**, including per-field validation errors — so a failed `create()`/`update()` returns actionable detail you can correct from and retry in the next program.

### Injected helpers

The exact set is rendered live in the `netbox_execute` description and gated by capability (write/IPAM-allocation/GraphQL/scripts/plugins/products). Object types use dot notation (`'dcim.device'`); the path form (`'dcim/devices'`) also resolves. Full catalog in [references/code-mode-helpers.md](references/code-mode-helpers.md) — load it when you need a specific signature. The essentials:

```
get(type, filters={}, fields=[], limit=50, offset=0, ordering=None) → {count, next, previous, results[]}
get_by_id(type, id, fields=[]) → object
search(query, object_types=[], limit=5) → {type: [results]}
options(type) → field schema (required fields, choices)
discover_models(app=None) / inspect_model(app, endpoint)        # enumerate types incl. plugins
create(type, data) / update(type, id, data) / delete(type, id)  # WRITE-gated
bulk_create / bulk_update / bulk_delete                          # WRITE-gated
available_prefixes / available_ips / allocate_prefix / allocate_ip ...   # IPAM-gated
graphql(query, variables=None, analyze=True)                     # GRAPHQL-gated
api(method, endpoint, params=None, data=None)                    # raw escape hatch
```

### Filter rules (two footguns)

1. **Never use `__in`.** NetBox silently ignores `field__in` on many fields and returns **all** rows — confidently wrong. The helpers reject it. Pass a **list as the field value** instead:
   ```python
   # WRONG
   get('dcim.site', filters={'id__in': [1, 2, 3]})
   # RIGHT — list value sends repeated query params, which NetBox honors
   get('dcim.site', filters={'id': [1, 2, 3]})
   ```
2. **No multi-hop traversal.** `device__site_id`-style nested filters are rejected. Use a **two-step query** — fetch the parent's ids, then filter the child:
   ```python
   racks = get('dcim.rack', filters={'site': 'nyc-dc1'}, fields=['id'])
   rack_ids = [r['id'] for r in racks['results']]
   devices = get('dcim.device', filters={'rack_id': rack_ids}, fields=['id', 'name'])
   result = devices['results']
   ```

### When to use `rediscover_netbox()`

Only when you have a **specific reason** to believe the tool inventory is stale: the user just installed/uninstalled a plugin, a tool you genuinely expected returns "tool not found," or a tool you no longer expect is still advertised. It is also the recovery path after a failed plugin registration. **Do NOT** call it before every operation, to "refresh" NetBox *data* (helpers are always live), or "just to be sure" at session start — each call costs a round-trip plus re-registration.

More end-to-end programs in [references/code-mode-workflows.md](references/code-mode-workflows.md).

---

## Discrete Mode

When Code Mode isn't available, every operation is its own MCP tool with a typed signature and a rich docstring. Discrete mode delivers more context directly (the tool list and docstrings are in front of you), so there is less to discover — but each operation is a separate round-trip. Core tools:

| Group | Tools |
|-------|-------|
| Reads | `netbox_get_objects`, `netbox_get_object_by_id`, `netbox_search_objects`, `netbox_get_changelogs` |
| Writes | `netbox_create_object`, `netbox_update_object`, `netbox_delete_object`, `netbox_bulk_create_objects`, `netbox_bulk_update_objects`, `netbox_bulk_delete_objects` |
| Connectivity | `netbox_trace_cable`, `netbox_get_cable_paths`, `netbox_get_rack_elevation`, `netbox_get_connected_device` |
| IPAM | `netbox_get_available_*` (prefixes/ips/vlans/asns), `netbox_allocate_next_*` |
| Automation/introspection | `netbox_render_config`, `netbox_run_script`, `netbox_graphql_query`, `netbox_get_object_schema`, `discover_models`, `inspect_model`, `rediscover_netbox` |

Discrete-mode rules the docstrings already enforce (follow them):
- **Always pass `fields=`** to minimize tokens (80–90% payload reduction on reads). `limit` default 50, max 1000.
- The **`__in` and multi-hop rules are identical** to code mode — pass a list value; use the two-step pattern.
- `netbox_get_changelogs`: `action` must be **imperative singular** (`"create"`/`"update"`/`"delete"` — NetBox rejects `"updated"` with 400). `changed_object_type` is `"app.model"`; `changed_object_type_id` is the integer ContentType PK.
- Object types accept both `"dcim.device"` and `"dcim/devices"`. Use `discover_models()` to enumerate types (including plugins).

## Product & Plugin Namespaces

When the tenant is entitled and the integration is configured, additional helpers/tools appear:
- **Plugins:** branching (`branch_*`), changes (`change_request_*`, reviews, comments), custom-objects (`custom_type_*`/`custom_object_*`).
- **Products:** **Assurance** (`assurance_*`) and **Discovery** (`discovery_*`).

These are **entitlement-gated** — present only when your tenant has the product/plugin. Don't assume they exist; discover them. For their domain logic, see [netbox-branching](../netbox-branching/SKILL.md), [netbox-changes](../netbox-changes/SKILL.md), [netbox-custom-objects](../netbox-custom-objects/SKILL.md), [netbox-assurance](../netbox-assurance/SKILL.md), and [netbox-discovery](../netbox-discovery/SKILL.md).

## Anti-Patterns

1. **Writing `import`** in code mode → "Forbidden operation: Import." The dominant failure. Use namespace helpers + allowed builtins only.
2. **Not searching the schema first** → guessing a wrong object type or unsupported filter. Confirm via `netbox_search_schema` before executing.
3. **The `__in` footgun** → silently-broad results / rejection. Use a list as the field value.
4. **Multi-hop filters** → rejected. Use the two-step pattern.
5. **Forgetting to assign `result`** → wasted turn.
6. **One `netbox_execute` per object** instead of a single looped/bulk program → defeats the point of code mode.
7. **Over-calling `rediscover_netbox`** as a precaution → it's a round-trip cost, not a data refresh.
8. **Not projecting `fields=`** → oversized payloads, hitting the result cap, wasted tokens (both modes).
9. **Assuming a product/plugin namespace exists** → it's entitlement-gated. Discover it.
10. **`NameError` on an undefined name** (`ip_network`, `re`, …) → only injected helpers + allowed builtins exist.

## References

- [references/code-mode-helpers.md](references/code-mode-helpers.md) — Full injected-helper catalog with signatures, grouped by capability gate. Load when you need an exact signature.
- [references/code-mode-workflows.md](references/code-mode-workflows.md) — End-to-end one-program examples (reads, list-of-ids, two-step joins, IPAM allocation, changelog audits).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [netboxlabs](https://github.com/netboxlabs)
- **Source:** [netboxlabs/skills](https://github.com/netboxlabs/skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-netboxlabs-skills-netboxlabs-platform-mcp
- Seller: https://agentstack.voostack.com/s/netboxlabs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.