Mist MCP Server

An MCP (Model Context Protocol) server that exposes the Juniper Mist REST API (api.mist.com/api/v1, Bearer token auth) as a curated set of MCP tools for AI agents.

Overview

This project bridges AI assistants (such as Claude, Copilot, or any MCP-compatible agent) with Juniper Mist's REST API. At startup, the server:

1. Authenticates with a permanent Bearer API token

2. Registers a static, hand-written set of 22 curated MCP tools

3. Serves the tools over the streamable-http MCP transport

The result: an AI agent can query organizations, sites, devices, WLANs, RF templates, networks, alarms, events, maps, and insights, execute Marvis AI queries, and perform targeted write operations, all through natural-language conversations — without any hand-written API glue.

Why curated tools? The Mist REST API is a large OpenAPI surface. The curated tool set provides safe, conveniently-shaped wrappers for the most common operations. Unlike other MCP servers in this family, there are no escape hatches — the 22 curated tools are the complete surface. There is also no write gating — the Mist API token's RBAC permissions are the sole access control.

Related MCP server: Cisco Catalyst SD-WAN MCP Server

Prerequisites

Before using this server, you must configure Juniper Mist for API access:

1. Create an API token

   • Navigate to Organization > Administrators > API Tokens in the Mist Console.

   • Create a new token and copy the generated value — this is your MIST_API_TOKEN.

2. Find your Organization ID

   • Navigate to Organization > Settings in the Mist Console.

   • The organization ID appears in the URL or on the settings page — this is your MIST_ORG_ID.

Important: The token's effective permissions are entirely determined by the Mist RBAC profile assigned to the token. The MCP server does not perform any additional access control. Write tools are exposed by the server but their actual reach is enforced by Mist via the token's RBAC permissions. Mist validates all write operations and rejects unauthorized ones.

How It Works

┌──────────────┐     streamable-http      ┌──────────────────┐
│  AI Agent    │ ◄──────────────────────► │  Mist MCP        │
│  (Claude,    │     tools/list           │  Server           │
│   Copilot…)  │     tools/call           │  (FastMCP)        │
└──────────────┘                          └────────┬─────────┘
                                                   │
                                        Authorization: Bearer <token>
                                                   │
                                                   ▼
                                        ┌──────────────────┐
                                        │  Juniper Mist    │
                                        │  REST API        │
                                        │  api.mist.com    │
                                        │  /api/v1         │
                                        └──────────────────┘

1. Bearer token auth — The server sends a permanent API token as Authorization: Bearer <token> on every request to api.mist.com/api/v1. The token is registered for log redaction so it never appears in logs or error messages.

2. Curated tool set — The server registers a fixed, hand-written set of 22 tools defined in src/mist_mcp/curated_tools.py. The set is:

   • Read tools (15): mist_orgs, mist_sites, mist_site, mist_devices, mist_device, mist_device_stats, mist_inventory, mist_wlans, mist_rf_templates, mist_networks, mist_alarms, mist_events, mist_maps, mist_insights, mist_marvis_query

   • Write tools (7): mist_marvis_suggest, mist_marvis_action, mist_create_wlan, mist_update_wlan, mist_delete_wlan, mist_claim_devices, mist_restart_device

   All 22 tools are always registered and always available. There are no escape hatches — no raw request tool, no introspection tool, no generic "pull anything" tool. Access control is enforced entirely by the Mist API token's RBAC permissions.

3. Retry & error handling — HTTP 429 and 5xx responses are retried with exponential backoff (1s, 2s, 4s). Timeouts are retried once. The API token is redacted from all log output and error messages.

Tool Catalog

Read tools (15)

Write tools (7)

Note: There are no escape hatches (no mist_get, no mist_raw_request). The 22 curated tools are the complete surface. Write tools have no server-side gate — Mist RBAC is the sole access control. Mist validates all writes and rejects unauthorized operations.

Environment Variables

See env.example for a documented template.

Build

Build the container image with Podman:

podman build --format docker -t ghcr.io/adam5isalive/mist-mcp-server:latest -f Containerfile .

Note: Build with --format docker. The default OCI image format does not preserve the HEALTHCHECK directive defined in the Containerfile; docker format keeps it for standalone podman run. The quadlet unit supplies its own HealthCmd, so this only matters outside quadlet.

Deploy with Podman Quadlet

Quadlet lets you run containers as systemd user services. This is the recommended deployment method for production use.

Step-by-step

1. Create the systemd user directory (if it does not already exist):

   mkdir -p ~/.config/containers/systemd/

2. Copy the quadlet file into that directory:

   cp mist-mcp.container ~/.config/containers/systemd/

3. Create the environment file with your credentials:

   mkdir -p ~/.config/mist-mcp

   Edit ~/.config/mist-mcp/env with the required variables (see env.example):

   MIST_API_TOKEN=your-api-token
   MIST_ORG_ID=org_abc123

4. Reload systemd and start the service:

   systemctl --user daemon-reload
   systemctl --user enable --now mist-mcp

5. Check status:

   systemctl --user status mist-mcp

6. View logs:

   journalctl --user -u mist-mcp

Example quadlet file (mist-mcp.container)

[Unit]
Description=Mist MCP Server
Documentation=https://github.com/adam5isalive/mist-mcp

[Container]
Image=localhost/mist-mcp:latest
EnvironmentFile=%h/.config/mist-mcp/env
PublishPort=127.0.0.1:8935:8935
Restart=always
HealthCmd=/usr/bin/curl -fsS -o /dev/null -X POST http://127.0.0.1:8935/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"healthcheck","version":"1"}}}'
HealthInterval=30s
HealthTimeout=10s
HealthStartPeriod=30s
HealthRetries=3
AutoUpdate=registry
Label=io.containers.autoupdate=registry

[Service]
Restart=on-failure
TimeoutStartSec=60

[Install]
WantedBy=default.target

Host binding / pasta: The container binds 0.0.0.0 (baked into the image via ENV MIST_HOST=0.0.0.0), which is required so rootless Podman's pasta network can forward into the container on WSL2/macOS. The security boundary is the host-side port publish, pinned to loopback with PublishPort=127.0.0.1:8935:8935. The server is reachable only from the host at http://127.0.0.1:8935/mcp. Never publish the port on 0.0.0.0 host-side.

Verify

List the available tools using any MCP client, or test directly with curl. The server is reachable at http://127.0.0.1:8935/mcp from the host. The MCP streamable-http transport requires a full handshake (initialize → capture Mcp-Session-Id → notifications/initialized → tools/list) and the proper Accept header.

For a manual check, first establish a session and capture the session ID:

curl -i -X POST http://127.0.0.1:8935/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Then, using the Mcp-Session-Id header from the response, list the tools:

curl -X POST http://127.0.0.1:8935/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

A successful response lists all 22 tools, for example:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "mist_orgs",
        "description": "Return all organizations accessible with the configured API token, including org id, name, and metadata.",
        "inputSchema": { "type": "object", "properties": {} }
      },
      {
        "name": "mist_sites",
        "description": "Return all sites in an organization, including site id, name, address, and configuration.",
        "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string" } } }
      },
      {
        "name": "mist_devices",
        "description": "Return all devices (APs, switches, gateways) at a site, including id, mac, model, name, type, and status.",
        "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string" } } }
      },
      {
        "name": "mist_marvis_query",
        "description": "Ask a natural language question to Marvis, the Mist AI engine. Supports questions about network health, client experience, device status, and more.",
        "inputSchema": { "type": "object", "properties": { "query": { "type": "string" }, "org_id": { "type": "string" } } }
      },
      {
        "name": "mist_create_wlan",
        "description": "Create a new WLAN at a site with the given SSID and JSON configuration.",
        "inputSchema": { "type": "object", "properties": { "site_id": { "type": "string" }, "ssid": { "type": "string" }, "config": { "type": "string" } } }
      },
      …
    ]
  }
}

Hermes Registration

To register this MCP server with an AI agent that supports the Hermes MCP configuration format, add the following to the agent's MCP config:

{
  "mcpServers": {
    "mist-mcp": {
      "url": "http://127.0.0.1:8935/mcp"
    }
  }
}

Security Notes

• Secrets come from environment variables only — The API token and org ID are never baked into the container image. They are provided at runtime via the EnvironmentFile in the quadlet (or set directly in the shell for development).

• The API token is redacted from all logs and error messages — MistClient registers the token with a log redaction filter, and outgoing request headers are logged with the authorization header replaced by Bearer ***.

• No escape hatches — Unlike other MCP servers in this family, this server has no raw request tool, no introspection tool, and no generic "pull anything" tool. The 22 curated tools are the complete surface. Agents cannot bypass the curated tool set.

• No write gating — All 7 write tools are always registered and always available. There is no ALLOW_WRITE flag. Access control is enforced entirely by the Mist API token's RBAC permissions. Mist validates all writes and rejects unauthorized operations.

• Loopback-only exposure — The security boundary is the host-side port publish, pinned to loopback (PublishPort=127.0.0.1:8935:8935 in the quadlet). The server is reachable only from the host at http://127.0.0.1:8935/mcp. Inside the container the server binds 0.0.0.0 (baked into the image via ENV MIST_HOST=0.0.0.0) so rootless Podman's pasta network can forward into the container on WSL2/macOS. Never publish the port on 0.0.0.0 host-side. For direct host runs the bind defaults to 127.0.0.1.

• TLS verification is on by default — MIST_INSECURE_SKIP_VERIFY=true should only be used in development or test environments. The Mist cloud API always uses valid TLS certificates.

• Rootless operation — The quadlet runs under systemctl --user, meaning the container runs without root privileges. This follows the principle of least privilege.

Development

Run the server locally without a container. The curated tool set is registered by register_curated_tools() in src/mist_mcp/curated_tools.py:

# Create and activate a virtual environment
python -m venv .venv && . .venv/bin/activate

# Install the package in editable mode
pip install -e .

# Run with required environment variables
MIST_API_TOKEN=your-api-token \
MIST_ORG_ID=org_abc123 \
python -m mist_mcp

Or use the installed console script:

MIST_API_TOKEN=your-api-token \
MIST_ORG_ID=org_abc123 \
mist-mcp

The server will start on 127.0.0.1:8935 by default. You can override the bind address, port, log level, timeout, and TLS verification via the environment variables listed above.

Updating

If the container image is published to a registry, and the quadlet includes AutoUpdate=registry, you can update to the latest image with:

podman auto-update

This pulls the latest image and restarts the container gracefully. Check the status afterwards:

systemctl --user status mist-mcp

Architecture

mist-mcp-server/
├── env.example              # Documented environment variable template
├── pyproject.toml           # Project metadata, dependencies, entrypoint
├── src/
│   └── mist_mcp/
│       ├── __main__.py      # Entrypoint: env loading, init, server start
│       ├── rest_client.py   # Async REST client for api.mist.com/api/v1
│       └── curated_tools.py # Static, hand-written MCP tool set (22 tools)
└── tests/                   # Test suite (see test files)

Module responsibilities

Skills

• skills/mist-tools.skill.md — Per-tool reference for all 22 tools: exact names, argument signatures, return shapes, and read/write status.

• skills/mist-api.skill.md — Reference for the Juniper Mist REST API itself: endpoint, auth, URL paths, and RBAC.

• skills/podman-deploy.skill.md — Rootless Podman quadlet build and deployment of the server.