mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-11-20 13:15:14 +02:00
Field finding from the smoke test: login flushes typed-ahead input before printing "Password: ", so a password sent in a separate call is lost (Login incorrect loop). Sending username and password in the same command string logs in reliably; the shell then persists across calls.
560 lines
27 KiB
Markdown
560 lines
27 KiB
Markdown
# 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 <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)
|
||
|
||
```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_<api_key_id>_<random_secret>` — 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 <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 |
|
||
|
||
<!--
|
||
Symbol tools (symbol_list / symbol_get / symbol_dimensions /
|
||
symbol_defaults / symbol_upload / symbol_delete) are disabled for now:
|
||
they require a vision-capable model to be genuinely useful. Revisit later.
|
||
-->
|
||
|
||
### 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.
|
||
|
||
```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_<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
|
||
|
||
```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 <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` — `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. On QEMU serial consoles, log in in ONE call: send the username and the password in the same `command` string. `login` flushes typed-ahead input before printing `Password: `, so a password sent in a separate call is lost and the console loops on `Login incorrect`. Once logged in, the shell persists across calls. 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()` |
|