Files
gns3-server/docs/features/mcp-service.md
T
YueGuobin 78199d14a4 fix(mcp): collect the console stream in websocat binary mode (-b)
websocat's text mode (-t, and also the default) appends a newline after
every received WebSocket message and turns CR/LF inside a message into
spaces. The compute ships console output as one BINARY frame per
arbitrary read(1024) burst, so text mode diced the stream at every frame
boundary — prompts split into pieces, short "narrow-column" lines, lost
carriage-return redraws (field report: Password: broken in three).

Measured against a local WS server sending known frames:
  -t:  A\nB\nC\na b\na  b\n  ("a\rb" -> "a b")
  -b:  ABCa\rba\r\nb        (byte-exact, both directions)

Binary command frames stay console data on the compute side (only a line
that is itself a JSON {cols,rows} object would be taken as a resize
frame). The regression test fails on -t and passes on -b.
2026-11-03 00:02:58 +08:00

27 KiB
Raw Blame History

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.

  1. Authorization header (recommended):

    Authorization: Bearer <jwt_or_api_key>
    
  2. 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

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
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:

  1. Attacker registers evil.com pointing to your server's IP
  2. User's browser makes requests to evil.com:3080
  3. MCP server checks Host header = "evil.com:3080"
  4. "evil.com:3080" is not in allowed_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_&lt;uuid&gt;_&lt;secret&gt;)
        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 — FastMCP was 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_service on 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 (from gns3_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.ContextVar so it is available within tool handler threads (Python ≥ 3.9 propagates contextvars through asyncio.to_thread). In stateful Streamable HTTP the session task inherits the context of the opening request, so handlers see the token presented at initialize

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 -b --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.

Binary mode (-b) is required, not cosmetic: in text mode (-t, and also the default) websocat appends a newline after every received WebSocket message and turns CR/LF inside a message into spaces. The compute ships console output as one BINARY frame per read(1024) burst, so text mode injects a newline at every arbitrary frame boundary — output comes back diced into short lines mid-word, and carriage-return redraws are lost. -b is byte-exact in both directions; binary command frames are still handled as data by the compute console handler.

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 (Python re, a superset of grep -E).
  • Up to 50 lines return as-is; beyond that a 10-line sample returns with retrieval hints.
  • regrep=true re-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=true returns 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 a curl URL with a short-lived access ticket (10 min) bound to that exact download path — the same mechanism link_capture_download uses. 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()