netboxlabs-platform-mcp

NetBox Labs Platform MCP サーバー

Platform MCP サーバーは、ホスト型の Model Context Protocol サーバー（NetBox Cloud 上）で、NetBox インスタンスを MCP ツールのインターフェースの背後に置き、エージェントが NetBox データを読み取り、変更できるようにします。これは、オープンソースの netboxlabs/netbox-mcp-server とは別のものです（v1.2.2、2026-10-08 — 依存関係とセキュリティの更新のみ。1.2.1 では HTTP トランスポートにオプションのベアラートークン認証を追加。__in の検索は拒否され、代わりにリスト値を使用します — これは以下と同じルールです）。プラットフォームサーバーは、Code Mode、ユーザーごとの認証、動的なプラグイン／モデル検出、ファーストパーティ製品との連携（Assurance、Discovery）を追加します。

このサーバーに関する情報は古くなっている可能性があります。 現在はパブリックプレビュー段階です。ツール一覧、ヘルパーのシグネチャ、利用可能な名前空間はデプロイごとにリアルタイムで生成され、変更されます。操作の前に、実際のインターフェースを必ず確認してください（スキーマ検索／ツール一覧）。オブジェクトの種類、エンドポイント、ヘルパーが存在すると決めつけないでください。

情報の取得元

情報源	URL／方法	用途
Platform MCP ドキュメント	https://netboxlabs.com/docs/platform-mcp/	セットアップ、クライアント設定、認証、モード、接続オプション
コミュニティ MCP サーバー	https://github.com/netboxlabs/netbox-mcp-server	オープンソースの読み取り専用代替手段
ライブサーバー	接続中の MCP サーバー自体	信頼できる情報源となるツール一覧と netbox_search_schema

接続と認証

• エンドポイント： https://<instance>.cloud.netboxapp.com/mcp
• トランスポート： ストリーミング可能な HTTP による MCP（stdio ではありません — ローカルのサブプロセスではなく、ネットワーク経由で利用するホスト型サーバーです）。
• 認証： Authorization: Bearer nbt_<token> — NetBox v2 API トークン（プレフィックスは nbt_。NetBox 4.5 以降で利用可能）。ユーザーごとの認証では、すべての呼び出しにユーザー自身のトークンの NetBox RBAC が適用されます。
• 接続オプション（エンドポイント URL のクエリパラメーター。英小文字のみ）：?mode=discrete|code|both は、その接続で使用するツールのインターフェースを選択します（すべてのプランで discrete を利用可能。code／both には Code Mode に対応するプランが必要です）。?read_only=true は、どのプランでも接続をクエリのみに制限します。いずれも省略すると、プランのデフォルトが適用されます。プランで利用できないオプションを指定すると、HTTP 400 で接続に失敗します。NetBox Labs サポートによってインスタンスを読み取り専用にロックできます（その場合、read_only=false は拒否されます）。
• お客様は NetBox Labs サポートを通じて、インスタンス上でサーバーを有効にします。

ストリーミング可能な HTTP による MCP に対応したクライアントであれば、どれでも使用できます（Claude Code/Desktop、Cursor、VS Code、ChatGPT Developer Mode）。ドキュメントページには、コピーして貼り付けられるクライアント設定があります。

最初に：モードを確認する

サーバーは3つのモードのいずれかでツールを公開します。ツール一覧を見れば、どのモードを使用しているかがわかります。

• Code Mode — ツールがちょうど3つ表示されます：netbox_search_schema、netbox_execute、rediscover_netbox。上位プランではこれがデフォルトです。最も効率的な主要インターフェースです。
• Discrete Mode — 約34個の netbox_* ツール（およびプラグイン／製品ツール）が表示されます。各操作がそれぞれ独立したツールです。
• Both — 上記すべてが表示されます。

netbox_execute が表示される場合は、Code Mode を使用してください。離散型の netbox_* ツールのみが表示される場合は、Discrete Mode に進んでください。

---

Code Mode

多数の離散型ツール（それぞれに個別のラウンドトリップが必要で、コンテキストが肥大化します）の代わりに、Code Mode では引数としてPython コードを受け取る3つのツールを公開します。注入された NetBox ヘルパーを呼び出す短いプログラムを記述し、プロセス内で独自にフィルタリング、結合、ループ処理を行って、単一の result を返します。これにより、多数のツール呼び出しを1回にまとめられます。

3 つのツール

ツール	引数	機能
netbox_search_schema(code)	事前に読み込まれた schema 変数を Python で読み取り、result に代入	探索。 メモリ上のスキーマ辞書をローカルで絞り込みます。NetBox への I/O は行いません。操作の前に、オブジェクトタイプ、エンドポイント、フィルターを確認します。
netbox_execute(code)	注入されたヘルパーを呼び出す Python を実行し、result に代入	主力ツール。 プログラムを NetBox に対して実行し、result を返します。このツールの説明には、この デプロイ環境で利用できる正確なヘルパーがリアルタイムで列挙されます。
rediscover_netbox()	なし	復旧専用。 NetBox を再プローブし、ツールの一覧とスキーマを再調整します。使用は控えめにしてください。詳しくは以下を参照してください。

黄金のループ（往復を最小限にする）

1. まずスキーマを検索し、推測しないでください。 netbox_search_schema を呼び出して、正しいオブジェクトタイプ、フィルターフィールド、または特殊なエンドポイントを確認します。オブジェクトタイプやパスを推測することが、失敗の最大の原因です。
2. 作業全体を行う netbox_execute プログラムを 1 つだけ作成します — 取得、絞り込み、結合、ループ、計算を 1 つのプログラム内で行います。ループや 1 回のリスト呼び出しで済む場合に、オブジェクトごとに netbox_execute を呼び出してはいけません。
3. 必ず result に代入してください。 代入しないと「Code ran successfully but did not assign to result」が返され、ターンを無駄にします。
4. フィールドを絞り込むには、読み取り時に fields=[...] を指定して、ペイロード（および結果サイズの上限）を小さく保ちます。
5. 生の api() より、名前付きヘルパーを優先してください — 検証機能があり、エラーも分かりやすくなります。

# netbox_search_schema — confirm the type/filters first
result = {k: v for k, v in schema['object_types'].items() if v['app'] == 'dcim'}

# 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']}

サンドボックスの規約（コードでできること）

netbox_execute / netbox_search_schema は、検証済みのサンドボックスを通じて実行されます。コードが拒否されないよう、以下を守ってください。

• import / from ... import は禁止です。 これは最もよくある失敗です。エージェントは json、re、ipaddress、math、collections を使おうとします。必要なものはすべて、すでに名前空間または許可された組み込み関数にあります。 import は決して記述しないでください。
• クラス定義、del、async / await / yield は禁止です。
• ダンダー／イントロスペクションは禁止です（eval、exec、open、getattr、globals、__class__、__subclasses__ などはブロックされます）。
• 許可されている組み込み関数のみ使用できます — よく使われるものは len、str、int、float、bool、list、dict、set、tuple、range、enumerate、zip、sorted、sum、min、max、any、all、abs、round、map、filter です。
• ループ、実時間、および結果サイズには上限があります — プログラムの処理量に上限を設け、結果の上限を超えないようフィールドを絞り込んでください。
• result に代入する必要があります。
• HTTP エラーには、フィールドごとの検証エラーを含む NetBox のレスポンス本文が表示されます — そのため、create() / update() が失敗した場合は、次のプログラムで修正して再試行できる、具体的な情報が返されます。

注入されるヘルパー

正確なヘルパーの一覧は netbox_execute の説明にリアルタイムで表示され、機能（書き込み／IPAM 割り当て／GraphQL／スクリプト／プラグイン／製品）に応じて利用可否が制御されます。オブジェクトタイプにはドット表記（'dcim.device'）を使います。パス形式（'dcim/devices'）も解決されます。全カタログは references/code-mode-helpers.md を参照してください。特定のシグネチャが必要な場合は、これを読み込んでください。主なものは以下のとおりです。

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

フィルターのルール（注意点 2 つ）

1. __in は決して使わないでください。 NetBox は多くのフィールドで field__in を黙って無視し、すべての行を返します。もっともらしく見えても誤った結果になります。ヘルパーはこれを拒否します。代わりに、フィールドの値として リストを渡してください。

   # 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. 複数段のトラバーサルはできません。 device__site_id のようなネストされたフィルターは拒否されます。2 段階でクエリーを実行し、まず親の ID を取得してから、子を絞り込んでください。

   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']
   

NetBox バージョンに関する落とし穴（ヘルパーは NetBox の表現をそのまま渡します）

• 選択式カスタムフィールド — NetBox 4.7+ では、obj['custom_fields']['env'] は {'value': 'prod', 'label': 'Production'} です（複数選択の場合はこれらのリストです）。4.5–4.6 では生の値です。バージョンに依存しない比較を行い（v['value'] if isinstance(v, dict) else v）、書き込む値は必ず生の値にしてください（update('dcim.device', id, {'custom_fields': {'env': 'prod'}})）。
• config_context — 4.5–4.6 ではオブジェクトごとにレンダリングされます。4.7.0–4.7.2 ではキャッシュされ、常に読み込まれます（4.7.x のすべてのバージョンで exclude は無視されます）。4.7.3+ では、フィールドセットから外すと再び DB 処理が省略されます。いずれの場合も、解決策は fields=[...] を指定することです。デバイスの行全体を取得しないでください。
• サービス — 4.7+ では port_mappings（['tcp/443', 'udp/53']）が使われます。protocol/ports は非推奨です（単一プロトコルのサービスに限り値が設定され、5.0 で削除されます）。protocol__ic ではなく、{'port': 443} / {'protocol': 'tcp'} でフィルタリングしてください。
• 一括書き込み — 4.7+ では bulk_create/bulk_update が失敗するとオブジェクトごとのエラーが返されます（errors[].index = リスト内の位置、更新の場合は errors[].id）。バッチは引き続き全件成功または全件失敗となるため、該当するエントリーを修正して再送信してください。4.5–4.6 では最初のエラーのみが報告されます。詳細はnetbox-api-integrationを参照してください。

rediscover_netbox() を使うタイミング

ツールの一覧が古くなっていると考える具体的な理由がある場合に限ります。たとえば、ユーザーがプラグインをインストールまたはアンインストールした直後、実際に存在するはずのツールが「tool not found」を返す場合、または不要になったツールがまだ表示されている場合です。プラグイン登録に失敗した後の復旧手段としても使います。操作のたびに呼び出したり、NetBox のデータを「更新」するために呼び出したり（ヘルパーは常に最新です）、セッション開始時に「念のため」呼び出したりしないでください。呼び出すたびに、ラウンドトリップと再登録のコストがかかります。

エンドツーエンドのプログラム例については、references/code-mode-workflows.mdを参照してください。

---

Discrete Mode

Code Mode を利用できない場合、各操作は型付きシグネチャと詳細な docstring を持つ個別の MCP ツールになります。Discrete mode では、より多くのコンテキスト（ツールの一覧と docstring）を直接参照できるため、調べることは少なくなりますが、操作ごとに別のラウンドトリップが発生します。主なツールは次のとおりです。

グループ	ツール
読み取り	netbox_get_objects, netbox_get_object_by_id, netbox_search_objects, netbox_get_changelogs
書き込み	netbox_create_object, netbox_update_object, netbox_delete_object, netbox_bulk_create_objects, netbox_bulk_update_objects, netbox_bulk_delete_objects
接続	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_*
自動化／イントロスペクション	netbox_render_config, netbox_run_script, netbox_graphql_query, netbox_get_object_schema, discover_models, inspect_model, rediscover_netbox

docstring ですでに適用されている Discrete mode のルール（必ず従ってください）：

• トークン数を最小限に抑えるため、常に fields= を渡してください（読み取り時のペイロードを 80–90% 削減できます）。limit のデフォルトは 50、最大値は 1000 です。
• __in と複数ホップのルールは code mode と同じです。リスト値を渡し、2 段階のパターンを使ってください。
• netbox_get_changelogs：action は命令形の単数形にしてください（"create"/"update"/"delete"。NetBox は "updated" を 400 で拒否します）。changed_object_type は "app.model"、changed_object_type_id は ContentType の整数 PK です。
• オブジェクトタイプには "dcim.device" と "dcim/devices" の両方を指定できます。プラグインを含むタイプ一覧の取得には discover_models() を使ってください。

製品とプラグインの名前空間

テナントに権限が付与され、インテグレーションが設定されている場合、追加のヘルパー／ツールが表示されます。

• プラグイン： ブランチ（branch_*）、変更（change_request_*、レビュー、コメント）、カスタムオブジェクト（custom_type_*／custom_object_*）。
• 製品： Assurance（assurance_*）と Discovery（discovery_*）。

これらは権限によって利用が制限されます。テナントに該当する製品／プラグインがある場合にのみ表示されます。存在すると思い込まず、検出してください。各ドメインのロジックについては、netbox-branching、netbox-changes、netbox-custom-objects、netbox-assurance、netbox-discoveryを参照してください。

アンチパターン

1. コードモードでimportを記述する → 「Forbidden operation: Import.」が発生します。最も多い失敗です。名前空間ヘルパーと許可された組み込み機能のみを使用してください。
2. 最初にスキーマを検索しない → 誤ったオブジェクトタイプや未対応のフィルターを推測することになります。実行前にnetbox_search_schemaで確認してください。
3. __inの落とし穴 → 結果が暗黙に広範になったり、拒否されたりします。フィールド値にはリストを使用してください。
4. 複数ホップのフィルター → 拒否されます。2段階のパターンを使用してください。
5. resultの代入を忘れる → ターンが無駄になります。
6. ループや一括処理のプログラムを1つ実行する代わりに、オブジェクトごとにnetbox_executeを1回呼び出す → コードモードの利点が失われます。
7. 念のためにrediscover_netboxを過剰に呼び出す → これは往復のコストであり、データの更新ではありません。
8. fields=で取得フィールドを指定しない → ペイロードが過大になり、結果上限に達し、トークンが無駄になります（どちらのモードでも）。
9. 製品／プラグインの名前空間が存在すると仮定する → 権限によって利用が制限されています。検出してください。
10. 未定義の名前（ip_network、reなど）によるNameError → 利用できるのは注入されたヘルパーと許可された組み込み機能のみです。

バージョンに関する注意

NetBox 4.7（2026-09-02）

• ドキュメントによると、サーバー独自のツール名、モード、認証に変更はありません。変わるのは、ヘルパーが返すNetBoxデータです。選択式カスタムフィールドの{value, label}、デフォルトで含まれるconfig_context（4.7.3以降では?omit=config_contextで省略）、サービスのport_mappings、オブジェクト単位の一括処理エラーについては、NetBoxのバージョンに関する落とし穴を参照してください。
• ?background=true（202 + ジョブ）は一括書き込みにおける生のRESTオプションです。ドキュメントに記載された一括処理ヘルパーは同期処理です。このオプションを渡せるのはapi()のエスケープハッチのみです（params={'background': 'true'}）。後続のプログラムでジョブ（core.job）をポーリングしてください。まずnetbox_search_schemaでサポート状況を確認し、この方法でAPIトークンを作成することは絶対に避けてください（4.7.2以降は拒否されます）。
• プラグインの名前空間（ブランチ、変更、カスタムオブジェクト）には、NetBox 4.7をサポートするプラグインのリリースが必要です。たとえば、netbox-branching 1.2.xは4.7専用です（1.1.xは4.4～4.6向け）。各バージョンの系列については、netbox-branching、netbox-changes、netbox-custom-objectsを参照してください。

参考資料

• references/code-mode-helpers.md — 機能ゲート別にまとめた、注入されるヘルパーのシグネチャ付き完全カタログです。正確なシグネチャが必要な場合に読み込んでください。
• references/code-mode-workflows.md — 読み取り、IDのリスト、2段階の結合、IPAM割り当て、変更履歴の監査など、プログラム1つで完結する例です。