Modern Model Context Protocol (MCP) deployments increasingly suffer from a structural inefficiency: repeated transmission and processing of large capability surfaces, even when only a small subset of tools, resources, and prompts are used per task. This paper introduces Warmplane, a local control plane that maintains persistent upstream MCP sessions while exposing a compact, deterministic, policy-governed interface to clients.
Warmplane separates backend protocol richness from frontend interaction cost by presenting index-first capability discovery, hybrid lexical/vector search, SHA-256 catalog cache validation (304 Not Modified), and on-demand schema expansion. In measured scenarios from the project evaluation harness, this approach reduced token footprint by 58.1%–58.2% in a public filesystem control suite and 95.6%–95.8% in an authenticated GitHub Copilot MCP suite. Micro-benchmarks demonstrate sub-microsecond facade overheads, including 50.4 ns cached catalog validation and 159.8 ns idempotency lookups. These improvements were achieved while introducing deterministic execution governance, including Human-in-the-Loop (HITL) approval gates, cryptographic Write-Once-Read-Many (WORM) audit logging, SIEM streaming (Splunk HEC, Webhooks), request context propagation (operation_id, actor_id, grant_id), idempotency deduplication (Idempotency-Key), safe/unsafe retry classification, and active operation cancellation.
We present the system architecture, transport model, policy and governance controls, error determinism model, hybrid capability search engine, catalog versioning model, cryptographic audit subsystem, and empirical evaluation methodology. We also discuss enterprise implications for latency, cost, reliability, security, and auditability, and outline future research directions for adaptive schema compaction and workload-aware orchestration.
As organizations operationalize AI agents, tool connectivity moves from demonstration to infrastructure. MCP has become a useful substrate for standardizing tool, resource, and prompt access. However, in direct MCP client-server patterns, agent loops frequently overpay in two dimensions:
The result is avoidable token spend, higher startup latency, security exposure, compliance vulnerability, and reduced operational predictability.
The central thesis of this whitepaper is:
Agent systems should treat MCP integration as a two-plane architecture: rich protocol backend + compact control-plane frontend.
Warmplane implements this thesis by:
This paper contributes:
keychain://, op://, env://)._jsonpath, _limit_lines, _truncate_bytes) and multi-step chained batch execution with reference interpolation ($step.field).In many agent stacks, the dominant cost is not tool execution but tool description overhead. Before a model can execute a single operation, it may receive broad catalogs of full schemas for tools that are never invoked.
This “description tax” creates three compounding effects:
Direct MCP connectivity maximizes compatibility, but at scale it can underperform operationally when each client independently handles:
Warmplane addresses this by introducing a local control plane that standardizes these concerns once.
┌──────────────────────────────────────────────┐
│ AI Clients & Agent Orchestrators │
│ (Claude Desktop, Cursor, Web, REST Gateways)│
└──────────────────────┬───────────────────────┘
│
┌──────────────────────▼───────────────────────┐
│ WARMPLANE CONTROL PLANE │
│ │
│ ┌────────────────────┐ ┌─────────────────┐ │
│ │ Compact HTTP / CLI │ │ Stdio MCP Proxy │ │
│ │ + Web Control Deck │ │ Lightweight │ │
│ └─────────┬──────────┘ └────────┬────────┘ │
│ │ │ │
│ ┌─────────▼─────────────────────▼────────┐ │
│ │ Governance & Policy Pipeline │ │
│ │ • Allow/Deny Gates • HITL Approvals │ │
│ │ • Redaction Filter • Idempotency │ │
│ │ • Request Context • Retry Tags │ │
│ └───────────────────┬────────────────────┘ │
│ │ │
│ ┌───────────────────▼────────────────────┐ │
│ │ Registry & Search Subsystem │ │
│ │ • Hybrid Search (BM25 + FastEmbed) │ │
│ │ • ETag Catalog Digest (SHA-256) │ │
│ │ • Cursor Change Feeds │ │
│ └───────────────────┬────────────────────┘ │
└──────────────────────┼───────────────────────┘
│ Managed Persistent Sessions
┌──────────────────────▼───────────────────────┐
│ Upstream MCP Servers (Warm & Ready) │
│ [GitHub] [Postgres] [Filesystem]... │
└──────────────────────────────────────────────┘
Warmplane consists of five major components:
POST /v1/config/reload).capabilityAliases, resourceAliases, promptAliases).ttl_ms and cache_scope hints.requireApproval) and manages suspension states with crash-safe atomic disk persistence (AtomicFile), auto-expiring timeouts across daemon restarts.operation_id, actor_id, grant_id, work_item_id) and Retry Governance (safe|unsafe|idempotent classification)._jsonpath, _limit_lines, _truncate_bytes) reducing agent context token consumption.POST /v1/tools/batch_call, capabilities_batch_call) with $step.field reference interpolation.input_responses and request_state propagation for interactive approvals and missing input elicitation.Idempotency-Key backed by atomic on-disk persistence and in-memory TTL caching.POST /v1/operations/:id/cancel)./v1/audit/verify) and streaming exports (/v1/audit/export).StandardMcpServers, OpenCode mcp, Zed context_servers).keychain://, op://, env://)./ui and /)./v1 facade (exposing capabilities, hybrid search, tool execution, batch calls, catalog events, approvals, WORM audit verification/export, operation cancellation, SSE resource updates, argument completion, sampling, resources, and prompts).warmplane server, config, client, secret, approvals, search-capabilities, list-catalog-events, cancel-operation).capability_search, capabilities_batch_call, subscriptions_listen, completion_complete, etc.) and native resources/prompts methods.X-Warmplane-Profile / ?profile=) or stdio-scoped (--profile) subset partitioning of upstream MCP servers with independent ETag caching (-p:<profile_id>:<hash>).While Multi-Tenant RBAC enforces identity and role authorization boundaries (who can call what), Profiles provide task-relevant view selection (which constellation of tools is relevant to a task) and fine-grained per-task governance:
/v1/capabilities, /v1/resources, /v1/prompts), hybrid search, and execution boundaries are filtered to the declared subset of servers.policy definitions (allow, deny, requireApproval, redactKeys). Unincluded constellation servers are visually distinguished and automatically receive implicit <server>.* denial rules.304 Not Modified validations across independent client constellations while instantly invalidating when profile membership or policy changes.Per upstream server, transport is inferred by strict configuration:
command $\rightarrow$ stdio transporturl $\rightarrow$ streamable HTTP transportExactly one selector must be set; ambiguous entries fail fast at startup.
For HTTP/SSE upstreams, Warmplane supports:
protocolVersion header control (defaults to "2026-07-28" with backward compatibility for "2025-11-25").allowStateless behavior.bearer, basic) and dynamic oauth2 (OAuth 2.1 / OIDC) flows featuring PKCE (S256), dynamic server discovery (RFC 9728 & RFC 8414), RFC 9207 / SEP-2468 iss matching, scope accumulation during step-up challenges, and silent token refreshing via rotated refresh tokens.Warmplane introduces an integrated HITL suspension engine:
policy.requireApproval patterns are intercepted before upstream dispatch.appr-1723668200-1), capturing sanitized parameters and caller context, atomically persisted to disk.X-Warmplane-Signature-256) are dispatched to operator dashboards or chat bots.warmplane approvals approve).APPROVAL_REJECTED or APPROVAL_TIMEOUT error codes.To satisfy enterprise compliance mandates (SOC2 Type II, ISO 27001, HIPAA), Warmplane implements a Write-Once-Read-Many (WORM) audit subsystem:
GET /v1/audit/verify): Traverses the sequential log in $O(N)$ time, recomputing and verifying each link. Returns a detailed verification report identifying the exact record ID if corruption is detected.To eliminate duplicate side-effect execution caused by agent retry loops, transient network faults, or upstream crashes, Warmplane enforces exactly-once semantics across tool capabilities:
Idempotency-Key, Warmplane derives a deterministic SHA-256 key from a canonical representation of the invocation:
\(\text{Key} = \text{SHA256}(\text{capability\_id} \mathbin{\Vert} \text{canonical\_json}(\text{args}) \mathbin{\Vert} \text{actor\_id} \mathbin{\Vert} \text{request\_id})\)
Dictionary keys are sorted recursively, guaranteeing that semantically identical JSON objects with differing whitespace or key ordering produce identical idempotency digests.X-Warmplane-Deduplicated: true header.is_replay: true and the associated idempotency_key, maintaining a complete audit ledger linking initial attempts, timeouts, and replays./v1/idempotency/records): Exposes queryable inspection endpoints and CLI tooling (warmplane idempotency list/get) to inspect replay counts and active deduplication records.Micro-benchmarks measured with Criterion on Apple Silicon demonstrate Warmplane’s minimal resource overhead:
| Benchmark Target | Scale / Workload | Latency ($p_{50}$) | Speedup / Optimization |
|---|---|---|---|
Catalog If-None-Match Validation |
Match $\rightarrow$ 304 Not Modified |
$50.4\ \text{ns}$ | Zero-copy quote-trim validation (66.3% faster) |
Catalog If-None-Match Check |
Header Absent | $1.98\ \text{ns}$ | Direct HeaderMap lookup miss |
| Idempotency Cache Hit | Single thread | $159.8\ \text{ns}$ | Immediate return of cached value |
| Concurrent Idempotency Contention | 16 threads (800 ops) | $550.7\ \mu\text{s}$ | $<0.7\ \mu\text{s}$ per op (83.1% faster than lock retention) |
| Catalog SHA-256 Versioning | 500 capabilities | $126.0\ \mu\text{s}$ | In-memory key sort + SHA-256 hash |
| Lexical Search Scan | 1,000 capabilities | $372.1\ \mu\text{s}$ | Zero-allocation streaming match (~2.7M evals/sec) |
| Hybrid Search (RRF Filtered) | $N=50$ candidates | $15.9\ \mu\text{s}$ | Server filter + Reciprocal Rank Fusion |
| Hybrid Search (RRF Unfiltered) | $N=1,000$ candidates | $1.41\ \text{ms}$ | Full candidate scan + Reciprocal Rank Fusion |
Let:
In direct mode, repeated loop cost over $n$ turns approximates:
\[C_{raw}(n) = n \cdot R_t\]In index-first facade mode with one on-demand expansion cost $D$:
\[C_{facade}(n) = n \cdot I + D\]where $I$ is compact index cost.
When $R_t \gg I$, savings scale with loop length:
\[\eta(n) = 1 - \frac{nI + D}{nR_t}\]As $n \to \infty$, $\eta(n) \to 1 - I/R_t$.
Warmplane extends this model in two dimensions:
If-None-Match: <etag> receives HTTP 304 Not Modified:Thus, total context spend across $n$ turns with zero schema changes collapses to only execution payloads, driving asymptotic savings $\eta(n) \to 100\%$ for non-mutating turns.
Measured from the evaluation harness (eval/token-efficiency/):
54,715 tokens2,386 tokens52,329 (95.6%)260,005 tokens11,173 tokens248,832 (95.7%)547,150 tokens22,895 tokens524,255 (95.8%)2,552 tokens1,066 tokens1,486 (58.2%)12,760 tokens5,349 tokens7,411 (58.1%)25,520 tokens10,669 tokens14,851 (58.2%)Higher raw schema density drives disproportionately larger gains in compact-plane architectures.
Warmplane concentrates control points to enforce strict security invariants:
actor_id and grant_id context through execution policies and audit trails.Warmplane demonstrates that MCP scale problems are solved through control-plane design rather than connectivity alone.
By maintaining persistent upstream sessions and exposing compact, deterministic, policy-governed interfaces, Warmplane delivers 58%–96% token savings, sub-microsecond routing performance, and enterprise-grade security and HITL governance.