rustmistmcp

rustmistmcp

Async Rust Model Context Protocol server for the HPE Juniper Mist cloud

a mechub project — sovereign network-security automation

Unofficial / community project. This is an independent community project

and does not claim affiliation with or endorsement by Hewlett Packard

Enterprise or Juniper Networks. Product names and trademarks are used only to

identify the systems with which the software interoperates.

---

rustmistmcp exposes the Juniper Mist cloud — orgs, sites, APs, switches, gateways, WLANs, clients, SLE, and Marvis — to MCP clients as a bounded, auditable tool surface.

Where rustjunosmcp talks NETCONF to individual SRX devices and rustpanosmcp talks XML-API to individual PAN-OS firewalls, this server talks to a multi-tenant cloud control plane. One org-scoped call can reach every site and every access point in an estate, so scoping, bounded responses, and change control are not garnish here; they are the design.

The functional target is the Mist half of nowireless4u/hpe-networking-mcp — site health and SLE, device inventory and stats, WLAN/SSID management, client connectivity, events and alarms, audit logs, RRM and rogue detection, firmware, NAC/policy, guest access, webhooks, floor plans, and Marvis — reimplemented in Rust on the mecmcp foundation rather than as a Python spec-driven registry. That project registers on the order of a thousand generated tools; this one deliberately will not. A curated, scoped, individually-documented surface is the whole point of doing it again.

Relationship to mecmcp

mecmcp is the vendor-neutral Rust foundation shared by the mechub MCP server family. This repository is a consumer of that foundation, not a fork of it:

Everything that is *not* specific to the Mist API is upstream. If you find yourself writing generic auth or transport code here, it belongs in mecmcp. There is currently no temporary exception: the one the ledger at docs/UPSTREAM_COMPATIBILITY.md recorded — a Mist-typed token lifecycle adapter — was deleted when its removal condition was met. Any new exception must be recorded there with an objective removal condition.

The API

Mist publishes a versioned REST API under /api/v1, served from per-region cloud endpoints. The org's home region determines the host:

Additional regional clouds exist; the authoritative list is Juniper's *API Endpoints and Global Regions* table, and the region must be operator-configured rather than guessed.

The Mist vendor API supports API tokens and external OAuth 2.0. API tokens are sent as Authorization: Token , may be minted per user or organization, and inherit the privileges of the account that created them. rustmistmcp v1 intentionally implements API-token authentication only; it does not accept OAuth credentials. HTTP Basic authentication with Juniper Mist login credentials is deprecated as of September 2026 and will not be implemented here.

Primary references:

• RESTful API Overview
• Create API Tokens
• Mist API Reference

The concrete endpoint map, pagination, and rate-limit semantics are being vetted directly against the live API reference before any client code lands — this README will not restate a surface it has not verified.

Status

Foundation built; read-only live-tenant acceptance passed. The workspace has an audited operation catalog, strict profile metadata, authorization models, and a catalog-bound MistClient contract that validates Mist operation inputs and binds opaque cursors to a configured origin. mecmcp#90 has closed, so HttpMistClient — the concrete HTTPS implementation over mecmcp-http — is built by MistHandler::from_config on the production path.

A lab deployment has reached a real Mist org. On 2026-08-10, through a loopback-bound endpoint and a grant-scoped bearer token, get_mist_self (getSelf), get_mist_org (getOrg), and list_mist_sites (listOrgSites) each returned tenant data with result: ok in 92–325 ms. That was issue #11's gate, and it closed.

What is *not* done, and must not be described as done:

• That run is not full packaging acceptance. It was loopback-only with no TLS, one org, one token, three read tools. The checklist in docs/PACKAGING_ACCEPTANCE.md — TLS hostname and chain, anonymous and bad-bearer rejection, exact Host/Origin enforcement — is not complete.
• **No /api/v1/self *startup* identity probe.** The get_mist_self tool works against a live tenant; nothing probes /self during startup, and LIVE_MIST_BLOCKER still names that gap.
• Mutations exist only for batch-1 WAN edge objects. Batch-1 covers create and update for networks, services, service policies, gateway templates, and device profiles, reachable only through the plan → digest → approve → apply lifecycle. Delete operations and mist_configured device-profile assignment/unassignment remain out of reach. No live-tenant apply has been performed.

A handler constructed without a credential uses BlockedMistClient, which performs no I/O; LIVE_MIST_BLOCKER is the message it refuses with.

Outbound Mist timeouts and 429 retries

The retry wait honors Retry-After but never exceeds --mist-max-retry-wait-secs. Out-of-range values are rejected at startup. A 429 retry wait holds a Mist concurrency permit, so long waits reduce throughput.

Site discovery

Site-scoped tools refuse any site the handler does not already know (see "The API"). At startup, the server calls listOrgSites for every allowlisted org to populate that map before it begins serving. --site-refresh-interval-secs (default 300) controls a background task that repeats this walk on an interval, so a site added or removed on the Mist side is picked up without a restart; 0 disables the background task and discovers once at startup only.

This refresh is idle polling against the operator-configured Mist origin — listOrgSites requests every site-refresh-interval-secs, independent of tool traffic, over the same catalog-validated MistClient every other read uses. It bypasses the per-tool audit trail, since it is a read that updates internal server state rather than a client-initiated call. A request failure or hitting the tracked-site ceiling for one org during a refresh keeps that org's previously known sites rather than dropping them; it does not affect other orgs' sites.

Shared TokenSecret, cancellation, and changeset primitives are reused, not rebuilt. Mist header names, catalog policy, request/response schemas, terminal states, retry classification, and deployment remain in this repository.

Tool listing mode

--tool-mode full|compact (env MCP_TOOL_MODE, default full) controls what tools/list advertises. compact lists only the catalog dispatchers the caller may see (search_mist_operations, get_mist_operation_schema, invoke_mist_read, invoke_mist_privileged_read) to keep the client's tool context small. The list is still scope-filtered: stdio callers and wildcard-scope tokens see three, and invoke_mist_privileged_read appears only for a token that explicitly allows it. It is listing only: every tool stays callable, and token tool/org/site scopes still authorize each call.

stdio transport

--transport stdio runs the server as a child process of a local MCP client (Claude Desktop, Claude Code, and similar), speaking MCP over stdin/stdout with no listening socket. Use it for single-operator, same-machine setups; use streamable-http for anything shared or remote.

• No bearer-token layer. --tokens-file is not read on stdio. The process boundary is the trust boundary: whoever can launch the process is the one caller, recorded in audit and change sets as the principal stdio. Tool, org and site scopes from the token store do not apply; the allowed_orgs list in mist.json still does. Because the planner and approver would both be stdio, self-approval is refused, so a stdio client can plan WAN edge changes but cannot apply them (see docs/THREAT_MODEL.md before combining stdio with --lab-mode).
• Restricted tools are hidden, not blocked. plan_mist_change, invoke_mist_privileged_read, get_mist_self, search_mist_audit_logs and the rest of RESTRICTED_TOOLS (crates/rustmistmcp/src/server/mod.rs) are omitted from tools/list on stdio but remain callable by name.
• Never combine stdio, `--lab-mode`, and a production-reaching Mist token. Under --lab-mode a single stdio agent can plan and apply a WAN edge change against the real org (docs/THREAT_MODEL.md).
• Native stdio audit is unredacted unless --audit-redact and --audit-hmac-key-file are given; the OCI image's entrypoint supplies both.
• The Mist API token still comes from the credential file (or env-var name) configured in mist.json, never from the client config.
• examples/mcp.json.example has two client entries: the native binary and the OCI image (arguments match server.json). Replace the placeholder paths.
• For clients with a small tool budget, add "--tool-mode", "compact" to args (see "Tool listing mode").

Pre-release packaging and deployment boundary

The checked-in Docker, archive, systemd, and LXC assets are pre-release packaging only. A lab LXC built from them has served live read-only tenant traffic (issue #11), which is not the same as packaging acceptance: that run used no TLS and no off-loopback bind, so the TLS, Host/Origin, and bad-bearer rows of docs/PACKAGING_ACCEPTANCE.md remain unproven. The /api/v1/self startup probe is unimplemented, and mutations exist only for batch-1 WAN edge objects behind the change-set lifecycle; no live-tenant apply has been performed. No v1 release label may be claimed until that checklist is complete.

The OCI image is a multi-stage build with a digest-pinned Rust builder and a digest-pinned distroless Debian 13 runtime. It runs only `/usr/local/bin/