mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-11-20 21:25:14 +02:00
SkillsManager refused to start when the local skills directory was not a git repository (cloning into a non-empty path fails), and reload_skills() returned early when injection/ was missing, so device and feature skills never loaded. reload_packet_analysis_protocols() had the opposite bug: an empty result wiped the registry while still reporting success. - initialize(): accept a non-empty directory without .git as a local-only source (skip automatic updates, keep loading files); degrade to local files when GitPython is unavailable. - _update_if_needed(): re-create/clone when the local directory vanished or moved, instead of reusing a stale handle forever. - reload_skills(): injection, device and feature load independently; a missing category keeps its previously loaded entries. - reload_packet_analysis_protocols(): an empty/missing directory keeps the existing registry and reports failure. - reload_skills_repository(): drop the console guard cache so config/console_guard.txt applies on reload. MCP device_skill_get now exposes the category filter, documents the single-file (topic-less) layout, and returns a sections list for index/summary of skills that have no topics/issues. An uninitialized skills repository fails with a clear error instead of an empty list.
539 lines
23 KiB
Markdown
539 lines
23 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
|
||
|
||
**79 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` | Get WebSocket console URL |
|
||
| `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 (4)
|
||
|
||
| 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) |
|
||
|
||
**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) |
|
||
| VNC console | `node_console` (returns a websocat URL) |
|
||
|
||
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.
|
||
|
||
### 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`
|
||
|
||
### Console WebSocket
|
||
|
||
The `node_console` tool returns a WebSocket URL for connecting to a node's console. The URL includes a short-lived **access ticket** (10 min) — a short random string (`gns3t_…`, 22 chars) minted server-side and bound to that node's console endpoints. `link_capture_download` uses the same kind of ticket bound to one exact resource path instead of embedding a Bearer JWT in the returned curl command. Tickets replaced the long JWTs previously embedded in these URLs/commands: LLM clients retyping them into shell commands reliably corrupted a ~200-char JWT, while a short ticket survives copying. Re-request the URL when the ticket expires (logging out also invalidates outstanding tickets). This endpoint is protocol-agnostic — it works for **telnet**, **ssh**, and **vnc** console types alike. The WebSocket simply proxies raw byte streams between the client and the compute node; protocol negotiation (e.g. SSH key exchange) happens on the compute side.
|
||
|
||
The WebSocket URL is constructed using 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 returned WebSocket 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 in the URL without modification.
|
||
|
||
Use `websocat` to connect from the command line (use the `command` returned by `node_console` verbatim — never reconstruct the URL by hand):
|
||
|
||
```bash
|
||
# The host in the URL is automatically resolved to a reachable address
|
||
websocat ws://192.168.1.3:3080/v3/projects/{project_id}/nodes/{node_id}/console/ws?token=<console_ticket>
|
||
```
|
||
|
||
### 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()` |
|