Warmplane

Security controls:

The local control plane that keeps Model Context Protocol (MCP) sessions warm with compact capability facades, policy governance, and deterministic execution.

v0.28.0 — Changelog · User Guide · Agent Skill · Performance · Whitepaper · OpenAPI

---

⚡ What is Warmplane?

Warmplane is a local control plane and reverse proxy for AI tool calling. It maintains persistent, warm connections to multiple upstream MCP servers and multiplexes them behind a single, governed interface.

The Problems Warmplane Solves

1. Context Window Token Bloat: Sending massive JSON schemas for dozens of tools on every turn wastes tens of thousands of prompt tokens. Warmplane provides a compact catalog index (cutting payload size by 58–96%), on-demand schema discovery, and SHA-256 ETag caching.
2. Poor Tool Descriptions & Ambiguity: Many upstream tools have sparse, misleading, or poorly phrased docstrings that confuse LLMs. Warmplane lets you override tool summaries and descriptions via polymorphic aliases (AliasTarget) and generates compact parameter signatures (tool(req, [opt])) to optimize zero-shot agent accuracy without upstream code edits.
3. Duplicate Invocations & Retries: When network hiccups occur, naive agents retry blind mutations. Warmplane provides crash-resilient, exactly-once idempotency deduplication (idk_<sha256>) and explicit retry classifications (safe, idempotent, unsafe).
4. Ungoverned Execution & Security: Connecting agents directly to live infrastructure risks unauthorized operations. Warmplane enforces multi-tenant RBAC, per-profile server constellations, secret redaction, and Human-in-the-Loop (HITL) approval gates.
5. Cascading Hangs & Flakiness: Slow or crashed upstream processes freeze agent loops. Warmplane monitors health with sub-microsecond circuit breakers and self-healing process supervision.

---

🚀 Quick Start

1. Installation

Homebrew (macOS & Linux):

brew tap warmplane/tap
brew install warmplane

Cargo (crates.io):

cargo install warmplane

# Optional: with local ONNX vector search (FastEmbed)
cargo install warmplane --features semantic-search

Build from Source:

git clone https://github.com/Warmplane/warmplane.git
cd warmplane
cargo install --path . --features semantic-search

2. Configure Upstream Servers

Add servers interactively or import from existing AI tools:

# Interactive setup wizard
warmplane server add

# Or non-interactively
warmplane server add filesystem --command npx --arg "-y" --arg "@modelcontextprotocol/server-filesystem" --arg "/tmp"
warmplane server add context7 --url "https://mcp.context7.ai/sse" --bearer-env "CONTEXT7_API_KEY"

# Or 1-click import from Claude Desktop, Cursor, OpenCode, Zed
warmplane config import

Or configure mcp_servers.json:

{
  "port": 9090,
  "toolTimeoutMs": 15000,
  "capabilityAliases": {
    "db.query": "sqlite.read_query",
    "search": {
      "target": "semble-rs.search",
      "summary": "Search codebase using semantic or BM25 ranking. Pass absolute repo path."
    }
  },
  "policy": {
    "allow": ["db.*", "fs.*", "search"],
    "deny": ["fs.delete*"],
    "requireApproval": ["db.mutation*"],
    "redactKeys": ["token", "password", "api_key"]
  },
  "profiles": {
    "coding": {
      "servers": ["filesystem", "sqlite"],
      "description": "Local engineering and exploration tools"
    }
  },
  "mcpServers": {
    "sqlite": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sqlite", "./test.db"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
  }
}

3. Connect or Start Warmplane

Choose the run-mode that matches your workflow:

• Mode 1: Direct MCP Stdio Integration (No background daemon needed): Point your AI client (Cursor, Claude Desktop, Antigravity) to warmplane mcp-server. The AI client spawns Warmplane directly as a child process:

  {
    "mcpServers": {
      "warmplane": {
        "command": "warmplane",
        "args": ["mcp-server", "--config", "mcp_servers.json", "--profile", "coding"]
      }
    }
  }
  

• Mode 2: Background Daemon & Web Control Deck: Run a central persistent daemon hosting the REST API, interactive Web UI, and audit logs:

  warmplane daemon --port 9090
  

• Mode 3: Persistent Daemon with Streamable HTTP/SSE MCP Connection: If mcpHttpServer is configured, your AI clients can connect over HTTP/SSE (http://127.0.0.1:9191/sse) to a single shared daemon instance.

---

🔌 Client Interfaces

Warmplane exposes three primary access models sharing the same unified core state, policy gates, and telemetry:

1. Native MCP Stdio Proxy (warmplane mcp-server)

Point any MCP-native desktop client (Claude Desktop, Cursor, Zed, Windsurf) directly to Warmplane:

{
  "mcpServers": {
    "warmplane": {
      "command": "warmplane",
      "args": ["mcp-server", "--config", "mcp_servers.json", "--profile", "coding"]
    }
  }
}

2. HTTP REST Control Plane (warmplane daemon)

Full-featured HTTP JSON API for gateways, web apps, and backend services:

• GET /v1/capabilities: Compact capability catalog index
• POST /v1/capabilities/search: Hybrid lexical + semantic capability search
• POST /v1/tools/call: Normalized execution envelope with context distillation (_jsonpath, _limit_lines) and idempotency keys
• POST /v1/tools/batch_call: Chained multi-step execution with $step.field parameter interpolation
• GET /v1/tasks & POST /v1/tasks/:id/update: SEP-2663 async task lifecycle & HITL review
• GET /ui: Embedded standalone Web Control Deck

3. In-Process Embedded Engine (EmbeddedWarmplane)

Direct in-process Rust library for zero-overhead agent execution without HTTP child processes or network hops:

use warmplane::{EmbeddedWarmplane, engine::ExecutionOptions};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let (cp, _token) = EmbeddedWarmplane::start_from_path("mcp_servers.json").await?;
    let res = cp.call_capability(
        "filesystem.read_file",
        json!({ "path": "/tmp/test.txt" }),
        ExecutionOptions::default().with_request_id("req-1"),
    ).await;
    println!("Output: {:?}", res.data);
    Ok(())
}

---

🤖 Teach Your AI Agent Warmplane (Agent Skill)

Warmplane includes an official Agent Skill (.skills/warmplane/) adhering to the agentskills.io open standard. Point your coding agent (Claude Code, Google Antigravity, Cursor, OpenCode, Codex) directly to this repository:

# Install Warmplane Skill into Claude Code
claude skill install Warmplane/warmplane

# Or copy into your agent workspace
mkdir -p .agents/skills/warmplane && cp -r .skills/warmplane/* .agents/skills/warmplane/

• 📖 .skills/warmplane/SKILL.md — Core prompt triggers and standard agent workflows
• 🔌 references/mcp_stdio_usage.md — 1-Click client configs (17 IDEs) & MCP facade tools
• ⚙️ references/configuration_schema.md — mcp_servers.json schema & dynamic secrets
• 🛠️ references/cli_cheatsheet.md — Terminal commands for daemon, sync, and vault
• 🚑 references/error_resolution.md — Circuit breakers, policy denials, and recovery

---

📊 Performance Highlights

Warmplane is engineered in pure Rust with zero-cost abstractions:

• 50.4 ns: ETag Cache Validation (If-None-Match $\rightarrow$ 304 Not Modified)
• 159.8 ns: Idempotent Cache-Hit Deduplication
• 1.58 µs: SHA-256 Incremental Catalog Version Hashing ($N=10$)
• 15.9 µs: Filtered Hybrid Capability Search ($N=50$)
• 372.1 µs: Zero-Allocation Lexical Tag Search across 1,000 Tools

👉 See complete benchmarks and methodology in docs/PERFORMANCE.md.

---

🛡️ Core Capabilities Matrix

Capability	Since	Description
Real-Time MCP list_changed & Passthrough Tools	v0.28.0	Real-time tool/resource/prompt list change notifications, SEP-1319 _meta discovery hints, top-level native tool passthrough, and WORM mutation audit logging
Custom Alias Descriptions & Signatures	v0.27.0	Polymorphic docstring overrides (AliasTarget), compact LLM signatures (tool(req, [opt])), bidirectional alias resolution
1-Click AI Client Injector & Sync	v0.26.0	Bidirectional MCP adapter engine for Claude Desktop, OpenCode, Claude Code, Cursor, Zed, Windsurf, Cline
Native OS Keychain Vault	v0.26.0	Secure OS Keychain storage and dynamic secret URI resolution (keychain://, op://, env://)
Actionable ChatOps Webhooks	v0.26.0	Bidirectional Slack, Discord, and Microsoft Teams approval cards with HMAC-SHA256 signatures
Per-Profile Governance & Constellations	v0.26.0	Fine-grained per-profile policy rules, constellation boundary badges, and live filter metrics
Control Deck Tasks & HITL UI	v0.25.0	Live Tasks & Approvals hub, MRTR input resolution forms, Playground async toggle, and embedded task API
SEP-2663 Tasks Extension	v0.24.0	Non-blocking io.modelcontextprotocol/tasks capability, unified HITL state machine, REST & CLI commands
In-Process Embedded Rust Engine	v0.23.0	EmbeddedWarmplane & ControlPlaneHandle for zero-overhead library integration
Streamable HTTP/SSE MCP Transport	v0.22.0	Co-hosted /mcp/sse MCP transport for remote agent connectivity
Named Server Constellations	v0.21.0	Profile grouping (profiles) with scoped ETag partitioning and stdio filtering
Multi-Tenant RBAC	v0.20.0	Role-based token access, deterministic catalog partitioning, tenant context propagation
Client-Delegated MCP Sampling	v0.19.0	Reverse RPC sampling (sampling/createMessage) with ticket tracking & long-polling
Persistent State Subsystem	v0.18.0	Atomic restart-resilient disk storage (AtomicFile<T>) for approvals, idempotency, and OAuth2 tokens
Signal Handling & Graceful Teardown	v0.18.0	Robust SIGINT/SIGTERM handling, async worker flushes, child process orphan prevention
MCP Resource & Prompt Studio	v0.17.0	360° resource explorer, prompt template renderer with dynamic forms, and SSE syncing
Multi-Step Batch Pipelines	v0.17.0	Visual pipeline editor with reference parameter interpolation (POST /v1/tools/batch_call)
Enterprise Security & Auth	v0.16.0	Token-based middleware protection, WORM audit HMAC verification, and secret masking
Fault Tolerance & Supervision	v0.15.0	Degraded startup, per-server circuit breakers, exponential backoff restart supervision
Agent Enrichment Suite	v0.14.0	Facade search, context distillation (_jsonpath/_limit_lines), and multi-step batch execution
HITL Approval Engine	v0.13.0	Operator gate approval engine, suspension, argument editing, and HMAC webhook dispatch
WORM Audit & SIEM	v0.12.0	Append-only SHA-256 hash-chained audit logging, verification API, and Splunk/Webhook SIEM export
Control Deck Web UI	v0.11.0	Standalone embedded web dashboard for servers, testing playground, policy & telemetry
Dynamic Hot-Reloading	v0.11.0	Zero-downtime upstream mounting/unmounting, explicit warmplane reload & /v1/config/reload

---

Changelog

v0.28.0 — Real-Time MCP list_changed Notifications, SEP-1319 Discovery Hints & Passthrough Tools

• Real-Time MCP list_changed Notifications (src/mcp_server.rs, src/daemon/state.rs): Advertised listChanged: true across tools, resources, and prompts capabilities (enable_tool_list_changed, enable_resources_list_changed, enable_resources_subscribe, enable_prompts_list_changed). Active MCP stdio sessions receive real-time JSON-RPC notifications whenever upstream servers mount/unmount or config/aliases mutate.
• SEP-1319 Metadata Discovery Hints (src/mcp_server.rs): Injected io.warmplane/discovery_hint metadata payload into notifications/tools/list_changed advising agents to run capabilities_list to discover backend capabilities without incurring constant token costs on tool schemas.
• Top-Level Native Tool Passthrough (src/config.rs, src/mcp_server.rs, src/cli_config.rs): Promoted capability aliases (passthrough: true) into native top-level tools exported directly in tools/list with strict MCP name sanitization (^[a-zA-Z0-9_-]{1,64}$) and direct dispatch resolution.
• WORM Audit Trail on Dynamic Mutations (src/daemon/lifecycle.rs, src/http_v1/config_api.rs): Added tamper-evident SHA-256 hash-chained AuditEventType::ConfigMutation audit records across server mounts/unmounts, alias mutations, security policy updates, and profile configuration changes.
• Interactive Alias Management UI (ui/src/components/aliases.ts, ui/src/main.ts): Added click-to-edit alias rows, passthrough toggle pill badges, and input sanitization directly in the Control Deck web UI.

v0.27.0 — Custom Alias Descriptions, Compact LLM Tool Signatures & Task Inspector

• Custom Alias Descriptions & Docstring Overrides (src/config.rs, src/supervisor.rs): Upgraded alias configuration model to support polymorphic definitions (AliasTarget). Aliases can be simple target strings ("alias": "server.tool") or detailed objects ("alias": { "target": "server.tool", "summary": "...", "description": "..." }), enabling platform engineers and developers to repair or improve poorly-described upstream tools for zero-shot LLM ergonomics without upstream source changes.
• Compact LLM Tool Signatures (src/supervisor.rs, src/daemon/types.rs, src/engine/types.rs): Derived deterministic, compact parameter signatures (tool_name(req1, [opt1], [opt2])) from JSON Schemas (accounting for required fields vs nullable/optional properties). Surfaced across MCP capabilities_list, catalog search, and Web UI index summaries.
• Bidirectional Alias Resolution (src/supervisor.rs): Resolved mapping mismatch where supervisory discovery checks target equality against configured alias keys, ensuring canonical targets are promoted seamlessly to client interfaces.
• Rich Task Inspector Modal & Dual Controls (ui/src/components/tasks.ts): Enhanced Tasks & Approvals UI with dedicated inspector modal, live state viewers, formatted JSON payload inspections, and dual inspect/cancel action controls.
• Server Template Missing Secret Warnings (ui/src/components/servers.ts, src/vault/): Added live (Missing Keys) warning badges and status indicators across server cards and diagnostics when required template environment variables or Keychain secrets are unconfigured.
• Live Alias Configuration API & UI: Added custom summary inputs to the Control Deck Aliases tab (ui/src/components/aliases.ts) and CLI (warmplane config alias set --summary ...) with automated live hot-reloading reconciliation on disk mutation.

v0.26.1 — MCP Stdio Stream Isolation & Logging Fix

• MCP Stdio Stream Isolation (src/telemetry.rs): Configured tracing_subscriber::fmt::layer() to write to stderr (.with_writer(std::io::stderr)). Prevents runtime structured JSON logs and span diagnostics from polluting stdout.
• Upstream Process Stderr Inheritance (src/supervisor.rs): Upstream stdio child processes now explicitly inherit Warmplane's standard error (cmd.stderr(std::process::Stdio::inherit())). Prevents upstream startup banners (e.g. Memory and Filesystem server banners) from leaking into stdio JSON-RPC sessions.
• Client Protocol Reliability: Resolves JSON-RPC initialization failure (invalid message version tag ""; expected "2.0") when running Warmplane in stdio server mode (warmplane mcp-server) with AI agents and IDEs.

v0.26.0 — 1-Click AI Client Sync, Native Secrets Vault, ChatOps & Profile Governance

• 1-Click AI Client Injector & Ecosystem Sync (src/client_sync.rs): Zero-configuration bidirectional MCP adapter engine. Detects, injects, and detaches Warmplane proxy configurations with profile binding across Claude Desktop (macOS, Linux, Windows), OpenCode, Claude Code CLI (CLAUDE_CONFIG_DIR), Cursor (Global & Workspace), Zed Editor (context_servers), Windsurf, and Roo Code / Cline.
• 100% Agent Config Import Parity (src/config_import.rs): Unified external config discovery with dialect-aware parsers (StandardMcpServers, OpenCode mcp, Zed context_servers) and self-proxy protection.
• Native OS Keychain Vault & Dynamic Secrets (src/vault/): Added secure OS-level credential management (warmplane secret set/get/delete) and dynamic runtime secret expansion (keychain://, op://, env://) in environment variables with masked logs.
• Actionable ChatOps & Bidirectional Webhooks (src/chatops/): Rich interactive approval cards for Slack (Block Kit), Discord (Embeds), and Microsoft Teams (Adaptive Cards) with HMAC-SHA256 signature verification.
• Per-Profile Governance Policies (src/policy.rs, ui/src/components/policy.ts): Fine-grained per-profile allow, deny, and requireApproval rules overriding or scoping global policies.
• Constellation Boundaries & Dynamic Visibility (ui/src/components/servers.ts): Visual constellation badges (✔ IN CONSTELLATION, 🚫 EXCLUDED FROM PROFILE), auto-derived <server>.* implicit policy denials, and 1-click membership toggles.
• Server Diagnostics & 1-Click Restart: Added live error diagnostics modals, server restart endpoint (POST /v1/config/servers/:id/restart), and automated smoke testing suite for all 25 MCP server templates (scripts/test-templates.ts).
• Dynamic Catalog ETag Fingerprinting & Layout Stabilization: Profile-aware fingerprint hashing (sha256:...-p:<profile_id>:<hash>) ensuring immediate ETag invalidation and playground catalog re-population. Stabilized viewport layouts with continuous scrollbar gutter reservation.

v0.25.2 — Official MCP Registry Metadata & MCPB Packaging Format

• MCPB Distribution Format (packaging/mcpb/, .github/workflows/release-artifacts.yml): Added automated build and packaging of platform-specific Model Context Protocol Bundles (.mcpb) containing standalone binaries, bootstrap configurations, and standardized manifests (manifest_version: "0.3").
• Official MCP Registry Metadata (server.json): Release workflows now automatically generate canonical registry metadata adhering to the official server.schema.json specification (io.github.warmplane/warmplane) with multi-arch SHA-256 package digests.
• Homebrew Tap (Warmplane/homebrew-tap): Configured official tap distribution with prebuilt macOS and Linux formula (brew tap warmplane/tap && brew install warmplane).

v0.25.1 — Asynchronous Task Completion State Machine Fix

• Asynchronous Task Finalization (src/engine/mod.rs, src/http_v1/execute.rs): Resolved regression where asynchronous capability executions (async_task: true or Prefer: respond-async) and tasks resumed after Human-in-the-Loop (HITL) input responses remained indefinitely in TaskStatus::Working. Background workers now reliably record terminal state (TaskStatus::Completed with result, or TaskStatus::Failed with structured error) directly into TaskRegistry.
• Embedded Task Lifecycle Tests (tests/embedded_tests.rs, tests/tasks_tests.rs): Added comprehensive automated integration tests verifying that get_task and list_tasks observe terminal completed status with upstream payload following approval submissions and direct asynchronous calls.

v0.25.0 — Control Deck Tasks & HITL UI, In-Process Embedded Task API

• Control Deck Tasks & Approvals Hub (ui/src/components/tasks.ts): Upgraded the review queue into a unified Tasks & Approvals dashboard (data-tab="tasks") with live status KPIs (input_required, working, completed, cancelled/failed), interactive action cards with inlined MRTR input resolution forms (booleans, JSON editors, text fields), TTL countdown timers, and cooperative cancellation controls.
• MCP Playground Async Execution Mode: Added "⚡ Async Task Mode" toggle in the tool testing playground and an interactive 202 Accepted task card preview with 1-click navigation to the Tasks & Approvals review deck.
• Embedded Rust Task Management API (ControlPlaneHandle): Exposed direct task management methods on the in-process ControlPlaneHandle (list_tasks, get_task, update_task, cancel_task), allowing embedding applications to manage asynchronous SEP-2663 tasks without HTTP or JSON-RPC serialization overhead.
• Overview Cockpit & Badge Integration: Added "Tasks & HITL State" telemetry card in the Overview Cockpit and linked real-time sidebar badges to outstanding input_required tasks.