Netdisco MCP
Provides tools for interacting with a Netdisco instance via its Swagger/OpenAPI specification, enabling AI agents to inspect devices, switch ports, search nodes and VLANs, run inventory reports, and optionally manage jobs through the Netdisco REST API.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Netdisco MCPfind all devices on VLAN 100 and show their switch ports"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Netdisco MCP
The complete Netdisco REST API, translated into an agent-native MCP server
81 tools · dynamic Swagger discovery · stdio + Streamable HTTP · guidance-first agent UX · bearer authentication
Netdisco MCP turns a live Netdisco swagger.json document into a complete,
searchable MCP tool surface. It does not maintain a fragile handwritten subset
of endpoints. At startup it discovers the connected Netdisco version, upgrades
Swagger 2.0 to OpenAPI 3, repairs schema incompatibilities, assigns stable tool
names, and publishes every supported operation through FastMCP.
The result is an MCP server that can answer operational questions, inspect devices and switch ports, search nodes and VLANs, run inventory reports, and— when explicitly enabled—submit or remove Netdisco jobs.
The live API is the source of truth. Tool counts can increase when Netdisco
adds endpoints. The catalog in this README is a verified snapshot of
Netdisco2.103000.
Contents
Why this project exists
Capability | What it means |
Complete API coverage | Every operation advertised by the connected Netdisco instance becomes an MCP tool. |
Upgrade-aware | A container restart reloads the live specification and discovers new endpoints. |
Agent-first guidance |
|
Capability discovery |
|
Safer exploration | Read-only mode removes POST, PUT, PATCH, and DELETE operations before tool generation. |
Context protection | Oversized responses are truncated with a clear hint to narrow the request. |
Flexible transport | Run locally over stdio or remotely over MCP Streamable HTTP. |
Remote authentication | Streamable HTTP can require a deployment-specific bearer token. |
Container hardened | The supplied Compose service uses a read-only filesystem, |
Architecture
flowchart LR
subgraph Clients["MCP clients"]
ChatGPT["ChatGPT / OpenAI"]
Codex["Codex"]
ClaudeCode["Claude Code"]
ClaudeDesktop["Claude Desktop"]
end
Proxy["TLS reverse proxy"]
subgraph Server["Netdisco MCP"]
Auth["Bearer authentication"]
Guide["Guidance gate"]
Catalog["FastMCP tool catalog"]
Limit["Response limiter"]
Adapter["Swagger 2 → OpenAPI 3 adapter"]
end
Spec["Netdisco swagger.json"]
API["Netdisco REST API"]
ChatGPT --> Proxy
Codex --> Proxy
ClaudeCode --> Proxy
ClaudeDesktop --> Proxy
Proxy --> Auth
Auth --> Guide --> Catalog --> Limit
Adapter --> Catalog
Spec --> Adapter
Catalog --> APIStartup pipeline
sequenceDiagram
participant S as Netdisco MCP
participant N as Netdisco
participant A as Swagger adapter
participant F as FastMCP
S->>N: GET /swagger.json
N-->>S: Swagger 2.0 document
S->>A: Normalize schemas and references
A->>A: Assign stable operation IDs
A->>A: Remove mutations when read-only
A-->>S: OpenAPI 3.0.3 document
S->>F: Generate and mount tools
F-->>S: MCP server readyA productive agent workflow
The server is deliberately opinionated about how an AI agent should approach a network-management task.
flowchart TD
Start["Start a Netdisco task"] --> Guidance["Call get_guidance"]
Guidance --> Known{"Know the exact tool?"}
Known -- No --> Find["Call find_capability"]
Known -- Yes --> Read["Use search or object GET"]
Find --> Read
Read --> Evidence["Inspect current state"]
Evidence --> Change{"Is a change required?"}
Change -- No --> Report["Return evidence"]
Change -- Yes --> Confirm["Confirm target and scope"]
Confirm --> Mutate["Call mutation tool"]
Mutate --> Verify["Read current state again"]
Verify --> ReportCall
get_guidanceonce at the start of the working session.Use
find_capabilitywhen the correct tool is not obvious.Prefer search and object tools before broad reports.
Inspect the current state before any mutation.
Verify the resulting state instead of interpreting a timeout as failure.
Complete tool catalog
The verified Netdisco 2.103000 surface contains:
Category | Tools |
Agent assistance | 2 |
Objects | 31 |
Reports | 34 |
Queue | 5 |
Search | 4 |
User | 2 |
General | 3 |
Total | 81 |
Seven generated API tools use POST, PUT, or DELETE and are treated as
mutations. Set NETDISCO_READ_ONLY=1 to remove those seven tools.
Netdisco exposesGET /logout, which destroys the current API key and session
despite using HTTP GET. Method-based read-only filtering cannot classify that
endpoint as a mutation. Treat get_logout as destructive.
Agent-assistance tools
Tool | Purpose |
| Returns the bundled Netdisco operating guide and can highlight a topic-specific section. |
| Searches the complete generated catalog by task, route, tag, HTTP method, or description. |
Method | Tool | Netdisco route | Purpose |
DELETE |
|
| Delete jobs and clear the skiplist for a device, optionally filtered by fields. |
GET |
|
| Return a row from the device table. |
GET |
|
| Return |
GET |
|
| Return module rows for a device. |
GET |
|
| Return layer-2 neighbor relationships for a device. |
GET |
|
| Return nodes found on a device. |
GET |
|
| Return a row from the |
GET |
|
| Return active-node rows for a port. |
GET |
|
| Return active-node rows with age data for a port. |
GET |
|
| Return the aggregation-master entry for a port. |
GET |
|
| Return the last-node entry for a port. |
GET |
|
| Return log rows for a port. |
GET |
|
| Return the neighbor entry for a port. |
GET |
|
| Return node rows for a port. |
GET |
|
| Return node rows with age data for a port. |
GET |
|
| Return |
GET |
|
| Return the power entry for a port. |
GET |
|
| Return the properties entry for a port. |
GET |
|
| Return the SSID entry for a port. |
GET |
|
| Return VLAN rows for a port. |
GET |
|
| Return the wireless entry for a port. |
GET |
|
| Return |
GET |
|
| Return port rows for a device. |
GET |
|
| Return PoE module status and aggregated port statistics. |
GET |
|
| Return powered-port rows for a device. |
GET |
|
| Return SSID rows for a device. |
GET |
|
| Return VLAN rows for a device. |
GET |
|
| Return wireless-port rows for a device. |
GET |
|
| Return nodes found in a VLAN. |
PUT |
|
| Queue a job to store ARP entries found on a device. |
PUT |
|
| Queue a job to store nodes found on a device. |
Method | Tool | Netdisco route | Report |
GET |
|
| IP addresses without DNS entries. |
GET |
|
| Inventory grouped by location. |
GET |
|
| Device name and DNS mismatches. |
GET |
|
| Device inventory. |
GET |
|
| Devices with multiple addresses. |
GET |
|
| Power over Ethernet status. |
GET |
|
| IP addresses found on multiple devices. |
GET |
|
| Devices missing model or operating-system data. |
GET |
|
| Port utilization. |
GET |
|
| Recently added devices. |
GET |
|
| Duplicate private networks. |
GET |
|
| IP inventory. |
GET |
|
| Subnet utilization. |
GET |
|
| Nodes with multiple active IP addresses. |
GET |
|
| Nodes discovered through LLDP or CDP. |
GET |
|
| Mismatched duplex settings. |
GET |
|
| Ports operating in half-duplex mode. |
GET |
|
| Administratively disabled ports. |
GET |
|
| Ports blocked by spanning tree. |
GET |
|
| Ports with multiple attached nodes. |
GET |
|
| Error-disabled ports. |
GET |
|
| Port SSID inventory. |
GET |
|
| Ports carrying the most VLANs. |
GET |
|
| Mismatched VLAN configurations. |
GET |
|
| VLAN count per device. |
GET |
|
| VLAN inventory. |
GET |
|
| VLANs with multiple names. |
GET |
|
| VLANs known but never configured. |
GET |
|
| VLANs found only on uplinks. |
GET |
|
| VLANs no longer in use. |
GET |
|
| Access-point channel distribution. |
GET |
|
| Access-point client counts. |
GET |
|
| Access-point radio channel and power. |
GET |
|
| SSID inventory. |
Method | Tool | Netdisco route | Purpose |
GET |
|
| List active Netdisco backend names. |
GET |
|
| Return queued jobs with optional filters. |
GET |
|
| Return job counts grouped by status. |
POST |
|
| Submit jobs to the Netdisco queue. |
DELETE |
|
| Delete queue jobs and skiplist entries with optional filters. |
Method | Tool | Netdisco route | Purpose |
GET |
|
| Search devices by identity, address, location, model, OS, vendor, and other attributes. |
GET |
|
| Search nodes, including active and archived observations. |
GET |
|
| Search switch ports by description and port characteristics. |
GET |
|
| Search VLANs. |
Method | Tool | Netdisco route | Purpose |
GET |
|
| List users with roles and token status. |
POST |
|
| Provision a token-only service account and issue or revoke its API token. |
Method | Tool | Netdisco route | Purpose |
GET |
|
| Return the latest Netdisco statistics row. |
GET |
|
| Destroy the current API key and session cookie; this has a destructive side effect. |
POST |
|
| Obtain a Netdisco API key. |
Quick start
Requirements
Python 3.11 or newer
A reachable Netdisco instance with
swagger.jsonA permanent Netdisco API token or supported username/password credential
Docker and Docker Compose for container deployment
Local development
git clone https://github.com/omichelbraga/netdisco-mcp.git
cd netdisco-mcp
cp .env.example .envSet the required values in .env:
NETDISCO_URL=https://netdisco.example.net
NETDISCO_API_TOKEN=replace-with-a-permanent-netdisco-tokenInstall, validate the live specification, and run:
uv sync --extra dev
uv run netdisco-mcp --check
uv run netdisco-mcpThe default transport is stdio.
Docker Compose
The supplied Compose file expects the shared external network mcp-edge and
does not publish a host port.
docker network create mcp-edge
docker compose up --build -dA reverse proxy on mcp-edge can reach the service at:
http://netdisco-mcp:8000/mcpConfiguration reference
Setting | Default | Purpose |
| required | Base URL of the Netdisco instance. |
|
| Override the live Swagger/OpenAPI URL. |
| unset | Netdisco API credential sent to the upstream API. |
|
| Authorization scheme; use |
| unset | Optional Netdisco Basic-auth username. |
| unset | Optional Netdisco Basic-auth password. |
|
| Validate the Netdisco TLS certificate. |
|
| Upstream request timeout in seconds. |
|
| Remove POST, PUT, PATCH, and DELETE tools when set to |
|
| Require guidance before normal tool use. |
|
| Guidance activity window in seconds. |
|
| Maximum tool-response size before truncation. |
|
|
|
|
| Bind address for Streamable HTTP. |
|
| Listening port inside the process or container. |
| unset | Static bearer token required by the HTTP transport when configured. |
NETDISCO_API_TOKEN authenticates the server to Netdisco.
NETDISCO_MCP_BEARER_TOKEN authenticates MCP clients to this server. They
protect different trust boundaries and should never share the same value.
Connect MCP clients
Claude Code
claude mcp add --transport http --scope user \
netdisco-mcp https://netdisco-mcp.example.net/mcp \
--header "Authorization: Bearer <mcp-bearer-token>"Verify the connection:
claude mcp get netdisco-mcpCodex
Store the MCP bearer token in NETDISCO_MCP_BEARER_TOKEN, then add this entry
to ~/.codex/config.toml:
[mcp_servers."netdisco-mcp"]
url = "https://netdisco-mcp.example.net/mcp"
bearer_token_env_var = "NETDISCO_MCP_BEARER_TOKEN"
default_tools_approval_mode = "prompt"See the official Codex MCP configuration for additional timeout, allow-list, and approval controls.
Claude Desktop
Claude Desktop can use the included authenticated stdio proxy. The proxy keeps the remote bearer token out of the MCP protocol messages sent by Desktop and adds it only when connecting upstream.
fastmcp install claude-desktop \
src/netdisco_mcp/desktop_proxy.py:mcp \
--name netdisco-mcp \
--with-editable . \
--env NETDISCO_MCP_URL=https://netdisco-mcp.example.net/mcp \
--env NETDISCO_MCP_BEARER_TOKEN=<mcp-bearer-token>Restart Claude Desktop after installation.
OpenAI Responses API
import os
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.6",
input="Call get_guidance, then summarize the Netdisco device inventory.",
tools=[
{
"type": "mcp",
"server_label": "netdisco",
"server_url": "https://netdisco-mcp.example.net/mcp",
"authorization": os.environ["NETDISCO_MCP_BEARER_TOKEN"],
"require_approval": "always",
}
],
)
print(response.output_text)The authorization field follows the official
remote MCP tool
contract. Keeping require_approval set to always is appropriate for this
server because its live catalog can include mutation tools.
Generic MCP client
{
"mcpServers": {
"netdisco-mcp": {
"type": "http",
"url": "https://netdisco-mcp.example.net/mcp",
"headers": {
"Authorization": "Bearer <mcp-bearer-token>"
}
}
}
}Security model
flowchart LR
Client["Authenticated MCP client"]
Edge["TLS reverse proxy"]
MCP["Netdisco MCP bearer verifier"]
Credential["Internal Netdisco credential"]
Netdisco["Netdisco authorization"]
Client -- "MCP bearer token" --> Edge
Edge -- "preserved Authorization header" --> MCP
MCP -- "approved tool call" --> Credential
Credential -- "separate API token" --> NetdiscoSecurity controls provided by the project:
Constant-time comparison for the configured MCP bearer token.
Separate MCP-client and Netdisco-upstream credentials.
Optional method-based read-only tool filtering.
Guidance middleware before operational tool use.
Response-size limiting to protect model context.
TLS verification for Netdisco by default.
No host port in the supplied Compose file.
Read-only container filesystem and
no-new-privileges.
Recommended production controls:
Terminate trusted TLS at the reverse proxy.
Store both credentials in a secret manager or Portainer secret environment.
Rotate credentials on a defined schedule and after accidental disclosure.
Restrict the Netdisco credential to the minimum required role.
Keep approval prompts enabled for mutation tools.
Review reverse-proxy access logs and Netdisco job history.
Use
NETDISCO_READ_ONLY=1for discovery-only deployments.
How tool generation works
Netdisco 2.103000 publishes Swagger 2.0 while FastMCP consumes OpenAPI 3.
The adapter performs the following transformations without removing supported
operations:
Rewrites Swagger references into OpenAPI
componentsreferences.Converts body and form parameters into OpenAPI request bodies.
Moves parameter type information into schemas.
Repairs Netdisco property-level
requiredflags.Normalizes boolean, integer, and array defaults.
Converts response schemas into media-type content entries.
Assigns deterministic, human-readable operation IDs.
Adds the original HTTP method and route to every tool description.
Removes write methods when read-only mode is enabled.
If two routes would receive the same friendly name, a deterministic seven-
character digest is appended. This explains names such as
get_device_port_vlans_cd8cf56 and keeps the full API surface collision-free.
Repository layout
netdisco-mcp/
├── src/netdisco_mcp/
│ ├── __main__.py # CLI and transport startup
│ ├── auth.py # MCP bearer-token verification
│ ├── config.py # Environment-driven settings
│ ├── desktop_proxy.py # Authenticated Claude Desktop proxy
│ ├── guidance.py # Guidance loading and enforcement
│ ├── server.py # FastMCP assembly and tool mounting
│ ├── spec.py # Swagger normalization and tool catalog
│ └── data/GUIDANCE.md # Operating instructions for AI agents
├── tests/ # Configuration, auth, and spec tests
├── compose.yaml # Internal-network container deployment
├── Dockerfile
└── pyproject.tomlDevelopment and testing
Run the test suite:
uv run pytestValidate the connected live API without starting a transport:
NETDISCO_URL=https://netdisco.example.net \
NETDISCO_API_TOKEN=<netdisco-api-token> \
uv run netdisco-mcp --checkThe check reports API version coverage, read/write operation counts, total MCP tools, and tags. Tests cover transport aliases, bearer verification, Swagger- to-OpenAPI conversion, stable names, request bodies, schema repair, read-only filtering, and capability discovery.
Contributing
Fork the repository and create a focused branch.
Add tests for behavioral changes.
Run the full test suite against a representative Swagger fixture.
Run
netdisco-mcp --checkagainst an authorized Netdisco instance.Open a pull request describing the user-visible behavior and verification.
Please do not commit Netdisco credentials, MCP bearer tokens, internal URLs, or captured infrastructure data.
License
Released under the MIT License.
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
SaaS intelligence for AI agents. 5 unified tools cover 1,000+ services with 91-96% token savings.
Universal AI API Orchestrator — 1,554 tools, 96 services. One install.
Domain & company intel for AI agents: RDAP, DNS, email deliverability, tech stack. No API keys.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/omichelbraga/netdisco-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server