Warmplane — The Hot Local Control Plane for MCP Sessions

01 — The Problem

The description tax is real

Before an LLM agent executes a single tool call, it ingests the full schema catalog of every connected MCP server on every turn. As server count grows, prompt tokens balloon rapidly—adding cost, latency, and context distraction.

Direct MCP Pattern

Uncontrolled Overhead

Every turn re-transmits full JSON schemas, detailed descriptions, resource trees, and prompt definitions from every upstream server.

✕ 54,715 tokens per discovery pull (GitHub Copilot MCP)

✕ 547,150 tokens over a 10-turn mixed agent loop

✕ No cross-server caching, no search, no policy profile

With Warmplane

Compact Control Plane

Index-first discovery with lazy schema expansion. Agents pull compact alias indices and query expanded schemas on demand.

✓ 2,386 tokens per discovery pull (95.6% reduction)

✓ 22,895 tokens over same 10-turn mixed loop

✓ SHA-256 ETag caching → 0 tokens on 304 Not Modified

02 — Empirical Measurement

Proven Token Savings

Reproducible evaluation measured with the cl100k_base tokenizer. Run the evaluation suite in eval/token-efficiency/ to verify on your own workloads.

GitHub Copilot MCP Suite

95.8%

Token Savings · 10-turn mixed loop

Discovery pull 54,715 → 2,386 tokens

5-turn tool loop 260,005 → 11,173 tokens

10-turn mixed loop 547,150 → 22,895 tokens

Filesystem Control Suite

58.2%

Token Savings · 10-turn mixed loop

Discovery pull 2,552 → 1,066 tokens

5-turn tool loop 12,760 → 5,349 tokens

10-turn mixed loop 25,520 → 10,669 tokens

Token Efficiency Benchmark | Measured Eval Harness Output Tokenizer: cl100k_base

Suite: github_copilot_only
Discovery      54,715 -> 2,386   (95.6% savings)
5-turn loop   260,005 -> 11,173  (95.7% savings)
10-turn mixed 547,150 -> 22,895  (95.8% savings)

Control: public_filesystem_only
Discovery       2,552 -> 1,066   (58.2% savings)
5-turn loop    12,760 -> 5,349   (58.1% savings)
10-turn mixed  25,520 -> 10,669  (58.2% savings)

03 — Capability Matrix

Built for Hot Production Stacks

Everything ships in a single zero-dependency Rust binary compliant with Microsoft Pragmatic Rust guidelines.

Unified Control Plane

⊞

Unified Facade for Tools, Resources & Prompts

Build a clean, stable contract across heterogeneous upstream MCP servers. Enumerate compact aliases, fetch full schemas lazily, and route standard invocations with complete correlation.

Alias Registry Compact Schemas On-demand Expansion MCP Native Exposure Hybrid Search

v0.25.0 Spec Extension

⚡

SEP-2663 Tasks & Unified HITL

Official io.modelcontextprotocol/tasks capability: asynchronous long-running tool execution (202 Accepted + resultType: "task"), MRTR inputRequests delegation, cooperative cancellation, and persistent atomic task registry.

Vector & Lexical

◎

Hybrid BM25 + Vector Search

Find the right tool by name or natural language intention using BM25 keyword matching plus optional ONNX vector embeddings.

v0.23.0 Resiliency

⇌

Exactly-Once Idempotency & Replay Ledger

Deterministic auto-key derivation (idk_<sha256>), X-Warmplane-Deduplicated caching, replay count tracking, WORM audit trail linking, and in-flight cancellation.

Multi-Tenant Governance

⊘

Fine-Grained RBAC & Policy Constellations

Named server constellations (profiles), static/JWT token auth, per-role policy overrides, dynamic catalog/search pruning, and automated secret redaction.

Observability & WORM

⊙

OTLP Traces, SIEM & Cryptographic Audit

Append-only SHA-256 hash-chained audit logging, Splunk/Webhook SIEM export, and end-to-end OpenTelemetry trace propagation across execution envelopes.

In-Process Rust Engine

🦀

Embedded Rust Control Plane

Embed Warmplane directly into Rust applications via EmbeddedWarmplane and ControlPlaneHandle — zero HTTP/IPC serialization overhead on your Tokio runtime.

Enterprise Auth

⊕

OAuth 2.1 & OIDC Client Infrastructure

Complete OAuth 2.1 authorization code flow with PKCE, dynamic discovery, scope accumulation, and silent background token refresh with rotation for HTTP upstreams.

Catalog Engine

⌗

Catalog Versioning & ETag Validation

SHA-256 state hashing with conditional 304 Not Modified responses, profile-scoped ETag partitioning, and cursor-based SSE event feeds for zero-token client revalidation.

04 — API & Protocol Spec

Interactive Control Plane Endpoints

Explore the primary RESTful HTTP/v1 endpoints exposed by Warmplane daemon.

// HTTP GET /v1/capabilities // ETag header matching yields HTTP 304 Not Modified (0 tokens) { "etag": "\"3a8f9c1b-p:default\"", "capabilities": [ { "alias": "db.query", "upstream_id": "sqlite.read_query", "summary": "Execute a read-only SQL query against SQLite", "policy_group": "read_only" }, { "alias": "fs.read", "upstream_id": "filesystem.read_file", "summary": "Read text contents of a file", "policy_group": "read_only" } ] }

// HTTP GET /v1/tasks/task_1771891200_a81f // SEP-2663 Tasks Extension (io.modelcontextprotocol/tasks) { "taskId": "task_1771891200_a81f", "status": "input_required", "progress": 0.5, "ttlSeconds": 300, "inputRequests": { "operator_approval": { "type": "confirmation", "prompt": "Approve write mutation to production SQLite database?", "tool": "db.exec" } } }

// HTTP POST /v1/capabilities/search // Body: {"query": "database sql query", "limit": 2} { "matches": [ { "alias": "db.query", "score": 0.942, "match_type": "hybrid_bm25_vector", "description": "Run parameterized SELECT query on configured SQLite database" } ] }

// HTTP POST /v1/tools/call // Header: Idempotency-Key: op-9481-run1 { "request_id": "req_01HJ8Z", "status": "success", "execution_time_ms": 12, "retry_metadata": { "classification": "idempotent", "attempt": 1 }, "content": [ { "type": "text", "text": "[{\"id\":101, \"name\":\"warmplane\"}]" } ] }

// HTTP GET /v1/resources/updates (Server-Sent Events) // Streams real-time catalog changes and resource update notifications event: catalog_change data: {"event_id": 42, "type": "capability_registered", "alias": "github.search_issues"} event: resource_update data: {"uri": "file:///workspace/logs/app.log", "timestamp": 1770982800}

// HTTP POST /v1/completion/complete (MCP Autocompletion API) // Body: {"ref": {"type": "ref/prompt", "name": "sql_query"}, "argument": {"name": "table", "value": "us"}} { "completion": { "values": ["users", "user_permissions", "user_sessions"], "total": 3, "has_more": false } }

05 — Access Modes

Four Client Modes, One Engine

All interfaces share identical policy rules, session warmers, idempotency layers, and execution envelopes.

⌁

HTTP Daemon

RESTful /v1/ API exposing capability indices, SEP-2663 tasks, hybrid search, SSE streams, and operation cancellation.

warmplane daemon --config mcp_servers.json

⊞

MCP Server (Stdio / SSE)

Standard MCP facade. Point Claude Desktop, Cursor, or remote agents at Warmplane via stdio or streamable HTTP/SSE.

warmplane mcp-server --config mcp_servers.json

🦀

Embedded Rust Engine

Direct in-process library interface (EmbeddedWarmplane, ControlPlaneHandle) with zero HTTP/IPC overhead.

EmbeddedWarmplane::start(config).await

⊳

CLI Interface

Direct terminal commands for scripting, manual tool execution, SEP-2663 task control, and catalog inspection.

warmplane tasks list

06 — Quick Start

Running in Three Minutes

Configure your upstreams, validate your profile, and start serving warm sessions.

            mcp_servers.json
            json
          

{
  "port": 9090,
  "toolTimeoutMs": 15000,
  "capabilityAliases": {
    "sqlite.read_query": "db.query"
  },
  "policy": {
    "allow": ["db.*", "fs.*"],
    "deny":  ["fs.secret"],
    "redactKeys": ["token", "api_key"]
  },
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "./db"]
    }
  }
}

            Terminal Commands
            shell
          

# Install binary from source or crates.io
$ cargo install warmplane

# Interactively add servers, or import from Claude Desktop / Cursor
$ warmplane server add
$ warmplane config import

# Start the local control plane daemon
$ warmplane daemon --config mcp_servers.json

# Perform vector/keyword hybrid tool search
$ warmplane search-capabilities "query database" --limit 5

# Execute tool through control plane
$ warmplane call-capability db.query \
    --params '{"query":"SELECT 1"}' \
    --idempotency-key op-42-run-1

Keep your MCP
sessions warm & hot

The description tax is real

Proven Token Savings

Built for Hot Production Stacks

Interactive Control Plane Endpoints

Four Client Modes, One Engine

Running in Three Minutes

The cheapest token is
the one never sent

Keep your MCPsessions warm & hot

The description tax is real

Proven Token Savings

Built for Hot Production Stacks

Interactive Control Plane Endpoints

Four Client Modes, One Engine

Running in Three Minutes

The cheapest token isthe one never sent

Keep your MCP
sessions warm & hot

The cheapest token is
the one never sent