Replaces node_console (which handed a URL + ticket to the client for a bash websocat chain) with a tool that runs the whole session server-side: spawn `timeout N websocat -t --no-close <console-ws-url>`, feed the command lines through stdin (paced, CRLF), read stdout until the timeout kills websocat, return the collected output as plain text. - plain text replies: "output: ..." or bare error text — no JSON envelope, no status field (the server cannot judge command success) - raw output: UTF-8 decode with replacement only, no telnet/ANSI stripping; control keys are real characters (description teaches \u0003, no \x03 translation) - output funnel: grep=<python regex> filter; <=50 lines return as-is; beyond that a 10-line sample plus hints — regrep=true re-filters the node's cached capture (no re-run), full=true returns the last 400 lines / 64 KiB, and the full capture is written to the node's files (console-capture.txt) with a ticketed curl download URL - get_node_console_info_handler removed with its hashlib/TTL imports; the node-bound console ticket redemption path stays (comment updated, no current producer)
26 KiB
MCP (Model Context Protocol) Service
Overview
GNS3 Server provides a standard Model Context Protocol (MCP) interface, allowing AI assistants like Claude to interact with GNS3 network simulations through the Streamable HTTP transport (the SSE transport was deprecated in the MCP specification on 2025-06-18).
The MCP service exposes GNS3 project management operations as MCP tools that can be discovered and called by MCP clients.
Endpoints
| Path | Method | Description |
|---|---|---|
/v3/mcp/ |
GET | MCP service metadata |
/v3/mcp/transport |
POST | JSON-RPC requests (initialize, tools/list, tools/call, notifications) |
/v3/mcp/transport |
GET | Optional server-to-client event stream (opened after initialize) |
/v3/mcp/transport |
DELETE | Session termination |
The server assigns a session on initialize and returns it in the Mcp-Session-Id response header; subsequent requests carry it back as a request header.
Authentication
Every request to /v3/mcp/transport is authenticated. Two types of credentials are supported, passed either way.
-
Authorization header (recommended):
Authorization: Bearer <jwt_or_api_key> -
Query parameter (for clients that can't set headers, e.g. browser EventSource):
GET /v3/mcp/transport?token=<jwt_or_api_key>
Option 1: JWT Token (24h expiry)
curl -X POST http://localhost:3080/v3/access/users/authenticate \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "admin"}'
Default lifetime is 1440 minutes (24 hours). Configurable in gns3_server.conf:
jwt_access_token_expire_minutes = 1440 ; 24 hours
Option 2: API Key (permanent, revocable) — Recommended for MCP
API keys never expire and can be revoked individually. Format: gns3_<api_key_id>_<random_secret> — the embedded UUID enables O(1) lookup without scanning all keys.
Create one via the REST API:
# Create an API key (requires a JWT to authenticate)
curl -X POST http://localhost:3080/v3/access/api-keys \
-H "Authorization: Bearer <your_jwt>" \
-H "Content-Type: application/json" \
-d '{"name": "MCP Production"}'
# Response: {"api_key": "gns3_550e8400-e29b-41d4-a716-446655440000_a1b2c3d4...", ...}
# ⚠️ The key is only shown once — save it immediately.
API key management endpoints:
| Endpoint | Description |
|---|---|
POST /v3/access/api-keys |
Create a new key (returns plaintext once) |
GET /v3/access/api-keys |
List all your keys |
POST /v3/access/api-keys/{id}/revoke |
Revoke a key (can be restored) |
POST /v3/access/api-keys/{id}/restore |
Restore a revoked key |
DELETE /v3/access/api-keys/{id} |
Permanently delete a key |
Both JWT tokens and API keys work for MCP and REST API endpoints interchangeably.
Authentication Flow
When connecting with an API key:
POST initialize → Authorization: Bearer gns3_<uuid>_<secret>
↓
MCP auth wrapper extracts UUID → single DB query → 1 bcrypt (thread pool)
↓
Generates a fresh 24h JWT → stored in ContextVar for the session
↓
Tool handlers run in the session task created by that request → they use this JWT
↓
Later requests re-validate the credential (result cached ~5 min → no repeated bcrypt)
↓
Once the session's JWT ages past its 24h lifetime, tool handlers renew it
from the API key automatically — long-lived sessions keep working
Concurrency
| Setting | Value |
|---|---|
| MCP batch workers | 100 (BATCH_MAX_WORKERS) |
| MCP HTTP client timeout | 30s |
HTTP connection pool (pool_connections/pool_maxsize) |
500 / 1000 |
| REST API node/link creation pool | 100 (Pool(concurrency=100)) |
Available Tools
80 tools across 11 categories:
Project (14)
| Tool | Description |
|---|---|
project_list |
List all projects |
project_get |
Get project details |
project_create |
Create a project |
project_delete |
Delete a project |
project_open |
Open a closed project |
project_close |
Close an open project |
project_stats |
Get project statistics |
project_update |
Update project properties |
project_duplicate |
Duplicate a project |
project_readme_get |
Get project README content |
project_readme_update |
Update project README |
project_lock |
Lock project (prevent edits) |
project_unlock |
Unlock project |
project_locked |
Check if project is locked |
Node (22)
| Tool | Description |
|---|---|
node_list |
List all nodes (fields to filter columns, e.g. ["name","status"]) |
node_get |
Get node details (fields to filter columns) |
node_create |
Create node(s) — single via template_id or batch via nodes array. Supports fields to filter response. Top-level template_id applies as default in batch mode. Pass name to override template naming. Coordinates: left-handed Cartesian (origin at canvas center, X right-positive, Y down-positive). |
node_delete |
Delete a node |
node_update |
Update node properties |
node_start |
Start node(s) — node_id or node_ids array |
node_stop |
Stop node(s) — node_id or node_ids array |
node_suspend |
Suspend node(s) — node_id or node_ids array |
node_console_exec |
Run commands on a node's console (one call = one complete session) |
node_file_list |
List files in node directory |
node_file_get |
Read a file (with offset/limit) |
node_file_write |
Write a file |
node_file_delete |
Delete a file |
node_start_all |
Start all nodes |
node_stop_all |
Stop all nodes |
node_suspend_all |
Suspend all nodes |
node_duplicate |
Duplicate a node |
node_isolate |
Isolate a node (suspend links) |
node_unisolate |
Un-isolate a node (resume links) |
node_links |
List links connected to a node |
Link (9)
| Tool | Description |
|---|---|
link_list |
List all links (fields to filter columns) |
link_get |
Get link details |
link_create |
Create link(s) — single via nodes or batch via links array. Nodes support compact [id, ad, pt, id, ad, pt] format. Supports fields to filter response. |
link_delete |
Delete link(s) — link_id or link_ids array |
link_update |
Update link (suspend, filters) |
link_reset |
Reset link(s) — link_id or link_ids array |
link_capture_start |
Start capture(s) — link_id or link_ids array |
link_capture_stop |
Stop capture(s) — link_id or link_ids array |
link_capture_download |
Get PCAP download URL(s) — link_id or link_ids array |
Template (5)
| Tool | Description |
|---|---|
template_list |
List all templates. Supports fields to filter response columns. |
template_get |
Get template details |
template_create |
Create a template (Docker needs image) |
template_update |
Update a template |
template_delete |
Delete a template |
Compute (3)
| Tool | Description |
|---|---|
compute_list |
List registered remote computes |
compute_get |
Get compute details (requires UUID) |
compute_images |
List emulator images on a compute |
Snapshot (4)
| Tool | Description |
|---|---|
snapshot_list |
List snapshots |
snapshot_create |
Create a snapshot |
snapshot_delete |
Delete a snapshot |
snapshot_restore |
Restore a snapshot |
Drawing (5)
| Tool | Description |
|---|---|
drawing_list |
List drawings on canvas |
drawing_get |
Get drawing details |
drawing_create_text |
Create a text label (SVG assembled server-side, Web UI compatible) |
drawing_create_rectangle |
Create a rectangle annotation |
drawing_create_ellipse |
Create an ellipse/circle annotation |
drawing_update |
Update drawing (position, rotation, SVG) |
drawing_delete |
Delete a drawing |
Appliance (3)
| Tool | Description |
|---|---|
appliance_list |
List appliances (fields to filter, e.g. ["name","category"]) |
appliance_get |
Get appliance details |
appliance_install |
Create template from appliance (images must exist locally) |
Image (5)
| Tool | Description |
|---|---|
image_list |
List all images |
image_get |
Get image details |
image_delete |
Delete an image |
image_prune |
Remove images not referenced by any template |
image_install |
Auto-create templates from uploaded images by checksum |
Server (2)
| Tool | Description |
|---|---|
server_version |
Get GNS3 server version |
server_statistics |
Get server statistics (computes, projects, nodes) |
Device Config & Skills (5)
| Tool | Description |
|---|---|
device_config_send |
Push config commands to devices via console (Nornir + Netmiko), batch and parallel. Supports Jinja2 template + vars |
device_show_run |
Run read-only show commands on devices (whitelist-enforced). Supports Jinja2 template + vars |
vpcs_config_set |
Configure VPCS devices in batch (Nornir + Netmiko, parallel, VPCS command syntax validated) — the VPCS counterpart of device_config_send |
device_skill_get |
Read device knowledge from the GNS3-Skills repository (list → topic index → single topic; same access protocol as the copilot's device_skills tool) |
injection_skill_get |
Read fault-injection knowledge from the GNS3-Skills repository (topology context → fault category → single fault; same protocol as the copilot's injection_skills tool) |
Which tool when — the console-facing tools divide the work by shape:
| Scenario | Use |
|---|---|
| Push the same-shaped config to many network devices, one call | device_config_send (Jinja2 template + parallel fan-out) |
| Configure many VPCS PCs in one call | vpcs_config_set (parallel, VPCS syntax validated) |
| Inspect many devices read-only, one call | device_show_run (command whitelist — safe for AI) |
| Network OS console, any interaction | device_config_send / device_show_run (batch drivers manage config mode themselves) |
| Unfamiliar device: read its quirks before driving the console | device_skill_get (list first, then fetch by key) |
| Practise troubleshooting: inject a realistic fault | injection_skill_get (list with the topology's protocols, then one fault) + device_config_send |
| Any console interaction outside those drivers (incl. Docker/Linux nodes) | node_console_exec (one call = one session, plain-text output) |
The tool connects to each device's console via telnet/SSH. Nodes must be in the started state (use node_start or node_start_all). Device type is auto-detected from the node's device_type:<type> tag in GNS3.
Jinja2 Template Mode
Both device_config_send and device_show_run support an optional template parameter. When provided, each device's vars dict is rendered against the template to produce commands. Entries with the same device_name are merged into a single device session.
# Direct commands (single/batch)
device_config_send(
project_id,
device_configs=[
{"device_name": "R1", "config_commands": ["int lo0", "ip add 1.1.1.1 255.255.255.255"]},
],
)
# Jinja2 template (reduces token usage for batch)
device_config_send(
project_id,
template="interface lo{{ n }}\nip address {{ ip }} 255.255.255.255",
device_configs=[
{"device_name": "R1", "vars": {"n": 0, "ip": "1.1.1.1"}},
{"device_name": "R2", "vars": {"n": 0, "ip": "2.2.2.2"}},
],
)
# Show commands with template
device_show_run(
project_id,
template="show ip route {{ protocol }}",
device_configs=[
{"device_name": "R1", "vars": {"protocol": "ospf"}},
{"device_name": "R2", "vars": {"protocol": "bgp"}},
],
)
Best Practices
Prefer template over direct commands for batch. When ≥2 nodes share the same config structure with different values, use template+vars instead of writing config_commands per node. This reduces token usage and transcription errors.
Batch merging. Multiple entries with the same device_name are merged into a single Nornir session. The output contains all commands' results in one block. Match results by device_name, not list index.
Don't rely on status: success alone. It only means commands entered config mode. IOS errors (% Invalid input, % overlaps, % Incomplete command) appear inside output text — always scan for % lines.
Pilot before full rollout. Test template + vars on 1–2 devices first to verify rendering and syntax, then expand to all nodes.
Config backup via file operations. IOU and Dynamips nodes save startup config as a plain text file (startup-config.cfg) in the node directory after write memory. These can be backed up and restored via node_file_get/node_file_write.
# Save config on device
device_show_run(
project_id,
device_configs=[
{"device_name": "R1", "commands": ["write memory"]},
],
)
# Backup
config = node_file_get(project_id, node_id, "startup-config.cfg")
# Restore if config breaks
node_file_write(project_id, node_id, "startup-config.cfg", config)
node_stop(project_id, node_id)
node_start(project_id, node_id)
Device Skills (device_skill_get)
The GNS3-Skills repository (the same one the embedded copilot reads) carries per-device operational knowledge that the generic tools cannot know: FRR's console lands directly in vtysh (its ping has no -c, scripted config needs do prefixes), VPCS command syntax, IOS paging pitfalls, SR Linux's TUI-only CLI. device_skill_get exposes it to MCP clients with the copilot's multi-call protocol — list, then the device's topic index, then one targeted body:
device_skill_get(action="list") # 1. every loaded skill
device_skill_get(action="list", category="device") # optional category filter
device_skill_get(device_type="frr_vtysh") # 2. that device's skill + topic index
device_skill_get(device_type="frr_vtysh", topic="bgp") # 3. one targeted topic body
device_skill_get(device_type="gns3_vpcs_telnet") # single-file device: complete skill
Step 2 returns the base skill plus the topic index; topic bodies load only on an explicit topic request (step 3). The key is passed back exactly as step 1 returned it.
The repository ships two device layouts: split directories (device/frr/ = _base.yaml + one file per protocol topic) and single files (device/vpcs.yaml). Single-file skills have no topics — step 2 with the default full detail returns the complete skill and there is no step 3. On such a skill, detail="index" returns a sections list (config_commands, display_commands, notes, ...) instead of an empty body, so the caller knows there is content to fetch.
Fault Injection Skills (injection_skill_get)
The same repository carries fault-injection knowledge for troubleshooting practice: per protocol, a set of realistic faults with symptoms, injection commands and verification steps. The list step is context-filtered — it requires the protocols/services found in the topology:
injection_skill_get(action="list", context=["ospf", "bgp"]) # 1. matching fault categories
injection_skill_get(device_type="injection_ospf_issues", detail="index") # 2. fault names in that category
injection_skill_get(device_type="injection_ospf_issues",
issue="ospf_hello_dead_mismatch") # 3. one fault's full detail
context is matched case-insensitively against each skill's category, key and declared protocols, so aliases such as ebgp and ospfv3 work. Category keys are derived from the repository filenames (injection_<file>_issues) — always pass the key returned by step 1. Step 3 returns the injection commands; apply them with device_config_send and verify with device_show_run.
Device Config Workflow
sequenceDiagram
participant AI as AI Agent
participant MCP as MCP Handler
participant TM as Template Renderer
participant DP as Device Discovery
participant NR as Nornir
participant NM as Netmiko
participant D as Device Console
Note over AI: Decide: template or direct commands?
alt Direct commands
AI->>MCP: device_config_send(config_commands=[...])
else Jinja2 template
AI->>MCP: device_config_send(template + vars)
MCP->>TM: Render template per device
TM->>TM: Jinja2.render(**vars)
TM-->>MCP: device_configs with rendered commands
end
MCP->>DP: get_device_ports_from_topology()
DP-->>MCP: hosts_data (console port, device_type)
Note over MCP: Prepare Nornir inventory
MCP->>NR: InitNornir(hosts, threaded runner)
par Device 1 to N (parallel, max 10)
NR->>NM: netmiko_send_config(commands)
NM->>D: telnet/SSH console session
D-->>NM: command output
NM-->>NR: execution result
end
NR-->>MCP: aggregated results
MCP-->>AI: per-device results with output
Configuration
Claude Code (CLI)
# Option A: Using API key (recommended — never expires)
claude mcp add --transport http My_GNS3_Server \
http://localhost:3080/v3/mcp/transport \
-H "Authorization: Bearer gns3_a1b2c3d4..."
# Option B: Using JWT token (expires after 24h)
TOKEN=$(curl -s -X POST http://localhost:3080/v3/access/users/authenticate \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "admin"}' | python3 -c \
"import sys,json; print(json.load(sys.stdin)['access_token'])")
claude mcp add --transport http My_GNS3_Server \
http://localhost:3080/v3/mcp/transport \
-H "Authorization: Bearer $TOKEN"
Verify and manage the registration:
claude mcp list # health check — should show ✓ Connected
claude mcp remove My_GNS3_Server
By default the server is registered for the current directory only. Use --scope user to make it available in all projects:
claude mcp add --scope user --transport http My_GNS3_Server \
http://localhost:3080/v3/mcp/transport \
-H "Authorization: Bearer gns3_a1b2c3d4..."
Transport Security
MCP server uses the MCP SDK's DNS rebinding protection to prevent attackers from exploiting DNS resolution to access the MCP endpoint through unauthorized domains.
Default Behaviour
DNS rebinding protection is disabled by default, allowing connections from
any host. This aligns with GNS3 server's default host = 0.0.0.0 binding policy,
which is designed for VM distribution scenarios where users access the server
from various network locations.
Enabling Protection
Add to gns3_server.conf under the [Server] section:
; Enable DNS rebinding protection for MCP server
mcp_enable_dns_rebinding_protection = True
; Allowed hosts (comma-separated, "host:*" port wildcard patterns only)
mcp_allowed_hosts = 127.0.0.1:*,localhost:*,192.168.1.3:*
; Allowed origins (comma-separated)
mcp_allowed_origins = http://127.0.0.1:*,http://localhost:*,http://192.168.1.3:*
Note
: The MCP library only supports
"host:*"port wildcard patterns (e.g.,"192.168.1.3:*"). Standalone"*"wildcards are not supported.
Protection Mechanism
When protection is enabled, the MCP server validates the Host header of
incoming MCP requests:
# Verify the request's Host header matches allowed patterns
validate_request → check Host header → 421 Misdirected Request if invalid
This prevents DNS rebinding attacks:
- Attacker registers
evil.compointing to your server's IP - User's browser makes requests to
evil.com:3080 - MCP server checks Host header =
"evil.com:3080" "evil.com:3080"is not inallowed_hosts→ connection rejected
Behaviour Summary
mcp_enable_dns_rebinding_protection |
Result |
|---|---|
False (default) |
All hosts allowed |
True + correct hosts configured |
Only configured hosts allowed |
True + missing/wrong hosts |
Connections rejected with 421 |
For public-facing MCP servers, set allowed_hosts to your server's domain name.
Architecture
sequenceDiagram
participant Client as Claude Code
participant MCP as MCP Service
participant Auth as Auth
participant GNS3 as GNS3 REST API
Note over Client: 1. Initialize with API Key or JWT
Client->>MCP: POST /transport initialize (Authorization: Bearer <key>)
alt API Key (gns3_<uuid>_<secret>)
MCP->>Auth: Extract UUID → DB lookup → 1 bcrypt (thread pool)
Auth-->>MCP: Generate fresh JWT
else JWT
MCP->>Auth: Decode JWT
Auth-->>MCP: Token valid
end
MCP-->>Client: initialize result + Mcp-Session-Id header
Note over Client: 2. Call Tools (each request re-authenticated)
Client->>MCP: POST /transport tools/call (Mcp-Session-Id + Bearer)
MCP->>GNS3: HTTP request (with JWT pinned at session creation)
GNS3-->>MCP: Response
MCP-->>Client: tool result (SSE or JSON response body)
Internal Implementation
- MCPServer (official MCP SDK,
mcp.server.mcpserver—FastMCPwas renamed in SDK 2.x) is used for tool registration and the Streamable HTTP transport - The Streamable HTTP app is mounted as a Starlette sub-application at
/v3/mcp(endpoint/v3/mcp/transport) - The session manager (
mcp.session_manager.run()) is entered in the FastAPI lifespan (gns3server.core.tasks.lifespan) — Starlette does not run lifespans of mounted sub-apps - Auth: JWT validation via
auth_serviceon every request. API key (gns3_<uuid>_<secret>) extracts UUID for O(1) DB lookup, runs bcrypt in thread pool, returns a fresh JWT — resolutions are cached ~5 minutes so repeated requests cost no extra bcrypt. - Tool handlers use
Gns3Connector(fromgns3_copilot.gns3_client.connector) via the shared handler layer (gns3_copilot.gns3_client.api_handlers), keeping the MCP layer decoupled - The JWT token is stored in a
contextvars.ContextVarso it is available within tool handler threads (Python ≥ 3.9 propagates contextvars throughasyncio.to_thread). In stateful Streamable HTTP the session task inherits the context of the opening request, so handlers see the token presented atinitialize
Node Console Execution
The node_console_exec tool runs commands on a node's text console server-side. One tool call is one complete console session: the server spawns timeout N websocat -t --no-close '<console-ws-url>', feeds the command lines through stdin (one line per turn, ~0.3 s pacing, \r\n line endings), keeps reading stdout until the timeout kills websocat, and returns the collected output as plain text (output: …, or bare error text — no JSON envelope, no status field: the server cannot judge whether the command itself succeeded). Works for telnet and ssh console types on all computes (the controller proxies the WebSocket); vnc consoles have no text channel and fail with a plain message. The client never sees a URL or token — the whole websocat chain is an implementation detail.
Prerequisites: the node must be started, and the host running gns3server must have the websocat binary on its PATH (a missing binary returns a plain install hint).
Output handling (the funnel):
- Raw console bytes are decoded as UTF-8 with replacement — telnet negotiation and ANSI escapes are not stripped; stray bytes in the output are expected.
grep=<python regex>filters the captured lines (Pythonre, a superset ofgrep -E).- Up to 50 lines return as-is; beyond that a 10-line sample returns with retrieval hints.
regrep=truere-uses the node's last captured output — re-filter (grep=) or dump its tail (full=true) without re-running the command (no side effects).full=truereturns the last 400 lines / 64 KiB.- When output exceeds 50 lines, the full capture is also written to the node's files (
console-capture.txt, overwritten per session) and the hint includes acurlURL with a short-lived access ticket (10 min) bound to that exact download path — the same mechanismlink_capture_downloaduses. Tickets are short random strings (gns3t_…); they replaced long Bearer JWTs in returned URLs because LLM clients reliably corrupted those when retyping them (logging out invalidates outstanding tickets).
Node-side state persists between calls (config mode, running pings, pager position) — a new session lands where the previous one ended. Control keys are sent as real characters: an interrupt is "\u0003" as its own line in the command string; the 4-character spelling "\x03" is not translated. command="" sends a single Enter (wake an idle console / read the prompt). The session stays open the full timeout window (default 15 s, max 300 s) — set it just above the expected output time.
The console WebSocket URL is built from the server's _server_url(), which resolves the host as follows:
Server.host value |
Resolved host in URL |
|---|---|
Specific IP or hostname (e.g. 192.168.1.3) |
Used as-is |
0.0.0.0 (IPv4 any, default) |
Detected via default route interface IP |
:: (IPv6 any) |
Detected via default route interface IP |
| Detection failure | Fallback to 127.0.0.1 |
When Server.host is 0.0.0.0 (listen on all interfaces), the MCP server discovers the default route interface IP using a UDP socket connect to 8.8.8.8:80 — no network data is sent, the operating system simply selects the interface that would be used for the default route. This ensures the console URL uses a reachable address (e.g. 192.168.1.3 instead of 127.0.0.1). If the configured host is already a specific IP or hostname (not 0.0.0.0), it is used directly without modification.
Source Files
| File | Purpose |
|---|---|
gns3server/agent/mcp/__init__.py |
MCPServer, tool decorators, Streamable HTTP transport, JWT auth wrapper |
gns3server/agent/mcp/projects.py |
Project tool handlers |
gns3server/agent/mcp/nodes.py |
Node tool handlers |
gns3server/agent/mcp/links.py |
Link tool handlers |
gns3server/agent/mcp/templates.py |
Template tool handlers |
gns3server/agent/mcp/computes.py |
Compute tool handlers |
gns3server/api/server.py |
Mounts MCP routes via register_starlette_routes() |