# MCP (Model Context Protocol) Service ## Overview GNS3 Server provides a standard [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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 ``` 2. **Query parameter** (for clients that can't set headers, e.g. browser EventSource): ``` GET /v3/mcp/transport?token= ``` ### Option 1: JWT Token (24h expiry) ```bash 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`: ```ini 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__` — the embedded UUID enables O(1) lookup without scanning all keys. Create one via the REST API: ```bash # Create an API key (requires a JWT to authenticate) curl -X POST http://localhost:3080/v3/access/api-keys \ -H "Authorization: Bearer " \ -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__ ↓ 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:` 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. ```python # 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`. ```python # 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: ```python 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: ```python 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__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 ```mermaid 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) ```bash # 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: ```bash 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: ```bash 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: ```ini ; 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: ```python # 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 ```mermaid 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 ) 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` — `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__`) 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 -t --no-close ''`, 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=` 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()` |