contextwise

v0.4.2

Published

2 days ago

Dynamic Model Context Protocol (MCP) Tool Routing, Schema Compression & Execution Gateway

0High
0Medium
0Low

mcp model-context-protocol llm ai agent proxy routing tools token-optimization claude-code cursor antigravity developer-tools

ContextWise

Dynamic Model Context Protocol (MCP) Tool Routing, Schema Compression & Execution Gateway
Eliminate context-window bloat, cut workflow prompt tokens by 69%, and lower per-task cost — measured across seeded multi-run agent validation.

Overview

Connecting multiple MCP servers (Postgres, GitHub, Linear, AWS, Filesystem, Slack) easily dumps 50 to 300+ tool schemas into the model's active context window. This creates severe operational issues:

Token Inflation: Burns 5,000 to 25,000+ input tokens per turn on redundant JSONSchema definitions.
Tool Hallucination: Model selection accuracy drops dramatically when forced to pick from dozens of irrelevant tools.
Runaway Loops: Repeating failures and unvalidated parameters burn expensive API credits.

ContextWise acts as an intelligent MCP reverse proxy between your AI client (Claude Code, Cursor, Claude Desktop, Antigravity, Windsurf) and upstream MCP servers. ContextWise exposes only contextually relevant tools on-demand plus two meta-tools:

contextwise_search_tools(query, domain?): Discovers tools by natural language intent and hydrates them into the active toolset.
contextwise_execute_tool(tool_name, arguments): Universally executes any indexed tool on demand, even if its schema was never loaded into the context window.

⚡ Predictive Tool Pre-Activation & High-Performance Edge Ranking

ContextWise defaults to a high-performance predictive edge model evaluated in sub-millisecond (< 900 µs) inference at the Cloudflare Edge, eliminating context bloat and cutting token consumption before an agent takes its first turn.

The Problem with Raw Tool Flooding

In traditional MCP setups, models are overwhelmed with 50–300+ raw tool schemas (causing severe context bloat, runaway API costs, and hallucinations).

Turn 1 Predictive Tool Pre-Activation

ContextWise analyzes user workflow intent against registered candidate tool capabilities and automatically pre-activates the highest-probability tools directly into the active working context on Turn 1. Tools are immediately available for direct invocation and parallel execution from the start.

📊 Empirical Multi-Run Validation Results

Measured over 5 seeded agent runs per strategy (Antigravity backend, ~110 upstream tools, standard $0.15/$0.60 per-1M list pricing). "Workflow prompt tokens" excludes backend scaffolding — the tokens your task actually costs:

| Routing Strategy | Turns (avg) | Workflow Prompt Tokens | Completion Tokens | Cost / Run | | :--- | :--- | :--- | :--- | :--- | | Raw Passthrough (all tools) | 5.2 ± 0.4 | 41,397 | 1,520 | $0.02107 | | ContextWise Predictive Pre-Activation | 6.0 ± 0.0 | 12,780 | 859 | $0.01852 (−12%) |

69.1% Workflow Prompt Reduction: 12,780 vs. 41,397 task tokens per run.
43% fewer completion tokens, 80% less reasoning (859 vs. 1,520 completion; 181 vs. 915 reasoning tokens).
Task latency is backend-dominated (run variance ±45–70s on the test backend), so we report tokens and cost — not speed.

🛠️ Bring Your Own Model (BYOM) & Offline Fallback

Default Cloudflare Edge: Evaluated globally in < 900 µs (https://contextwise.dev/v1/rank) with zero local runtime dependencies, keeping the npm package under 180 KB.
Bring Your Own Model (BYOM): Power users and enterprise teams can configure custom endpoints (provider: "custom", customEndpoint: "https://...") or local custom models (provider: "local", localModelPath: "./models/...").
Zero-Failure Offline Fallback: If offline or if the edge is unreachable without a local BYOM model, ContextWise automatically falls back to an embedded deterministic BM25 ranker (MiniSearch). Tool execution never fails or stalls.

Quick Start

Fastest: hosted gateway (no install)

Call ContextWise through the MCPaid edge — zero install, discovery free, cloud sync metered per use via MCPaid (USDC on Base L2):

# One-shot / stdio bridge (works with any MCP client)
npx -y @mcpaid/sdk bridge --gateway https://mcpaid.dev/mcp/contextwise

# Claude Code
claude mcp add contextwise -- npx -y @mcpaid/sdk bridge --gateway https://mcpaid.dev/mcp/contextwise

// Cursor (.cursor/mcp.json) or Claude Desktop — stdio entry
{
  "mcpServers": {
    "contextwise": {
      "command": "npx",
      "args": ["-y", "@mcpaid/sdk", "bridge", "--gateway", "https://mcpaid.dev/mcp/contextwise"]
    }
  }
}

No API keys, no signup for discovery. Paid sync calls return a 402 with funding instructions the first time; agents pay gaslessly via EIP-712 permits.

Self-host: local install

1. Installation

Install globally via npm:

npm install -g contextwise

Or run zero-install via npx:

npx contextwise start

2. Auto-Import Existing MCP Servers

ContextWise can automatically scan and import your existing MCP configurations from Cursor (.cursor/mcp.json) or Claude Desktop:

contextwise init

3. Connect to Your AI Client

Claude Code (Anthropic CLI)

claude mcp add contextwise -- npx -y contextwise start

Antigravity CLI / IDE (`~/.gemini/config/mcp_config.json`)

{
  "mcpServers": {
    "contextwise": {
      "command": "cmd.exe",
      "args": ["/c", "npx", "-y", "contextwise", "start"]
    }
  }
}

Cursor (`.cursor/mcp.json`) or Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "contextwise": {
      "command": "npx",
      "args": ["-y", "contextwise", "start"]
    }
  }
}

4. HTTP Mode (for MCPaid Publishing)

Expose ContextWise over Streamable HTTP instead of stdio, then monetize per-call with MCPaid:

# 1. Serve ContextWise locally over HTTP
npx contextwise start --http --port 3000
# Listening on http://127.0.0.1:3000/mcp

# 2. Publish to the MCPaid edge (pay-per-use USDC on Base L2)
npx @mcpaid/sdk publish mcpaid.config.json
# Live at https://mcpaid.dev/mcp/contextwise

Cloud sync is metered via MCPaid micropayments; search, execute, browse, server setup, and sync status are free. No subscriptions — sync usage is metered through MCPaid instead.

Downstream Edge Receipt Enforcement

To protect your HTTP server from direct bypass and verify payments cryptographically:

# Get your server's receipt secret from MCPaid
npx @mcpaid/sdk server receipt-secret contextwise

# Export the secret on your host or deployment
export MCPAID_RECEIPT_SECRET=mcpaid_sec_...

When MCPAID_RECEIPT_SECRET is set, ContextWise verifies X-MCPaid-Receipt on incoming HTTP requests for priced tools before execution. Calls without a valid receipt or with replayed nonces are rejected with 402 Payment Required. Verified receipts are securely forwarded to the ContextWise Cloud backend.

Server Management & Marketplace CLI

ContextWise makes finding and installing MCP servers seamless:

1. Browse Multi-Registry Catalog

Browse verified servers across the Official MCP Registry, Smithery.ai, and Curated Presets:

# Browse all verified servers
contextwise browse

# Search specific database or search tools
contextwise browse database
contextwise browse -q "github"

# Interactive keyboard navigation
contextwise browse --interactive

2. Add New Upstream Servers

Add servers with instant connection testing and persistence:

# Add from curated preset
contextwise add postgres postgresql://user:pass@localhost:5432/mydb
contextwise add sqlite ./app.db
contextwise add github --env GITHUB_PERSONAL_ACCESS_TOKEN=your_token

# Add any custom stdio command
contextwise add my-server --command "npx" --args "-y" "my-mcp-package"

# Add from Smithery
contextwise add slack -s @smithery/slack

3. Inspect Connections & Metrics

# List all configured servers and aggregated tools
contextwise list

# View ROI, dollar savings, and performance analytics
contextwise stats

# Export raw JSON metrics
contextwise stats --json

🔐 Secret Vault & Zero-Leakage Credential Management

Never commit plaintext API keys or database passwords to contextwise.json. ContextWise includes an encrypted secret vault backed by native OS Keystores (macOS Keychain / Windows DPAPI / Linux Secret Service) and AES-256-GCM encrypted file storage.

1. Storing & Managing Secrets

# Store a secret (interactive secure prompt if value omitted)
contextwise secret set GITHUB_TOKEN ghp_yourSecretToken123

# List all stored secrets (metadata only, values never printed)
contextwise secret list

# Preview secret with automatic masking
contextwise secret get GITHUB_TOKEN
# Or reveal full plaintext
contextwise secret get GITHUB_TOKEN --reveal

# Delete a secret
contextwise secret delete GITHUB_TOKEN

2. Referencing Secrets in `contextwise.json`

Use the vault:// protocol to inject secrets at child-process spawn time:

{
  "upstreams": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "vault://GITHUB_TOKEN"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "vault://PROD_DB_URL"
      }
    }
  }
}

3. Security Audit & Stream Redaction

# Scan workspace configuration for exposed plaintext keys and credentials
contextwise secret audit

All secrets registered in the vault are continuously sanitized across stdout, stderr, logs, and tool error messages by ContextWise's automated RedactionFilter.

☁️ Zero-Knowledge Cloud Sync & Team Sharing

Synchronize your MCP configurations and encrypted secrets securely across multiple workstations and teammates.

Zero-Knowledge: Master encryption keys never leave your machine; the cloud backend only stores ciphertext.
Asymmetric Envelope Encryption: Team secrets are encrypted with recipients' X25519 public keys so teammates can share credentials without sharing account passwords.

# Authenticate with ContextWise Cloud
contextwise login

# Inspect cloud identity and accessible workspaces
contextwise whoami

# Push local workspace configuration and encrypted secrets
contextwise push

# Pull and merge cloud snapshot into your local workspace
contextwise pull

# Check synchronization status
contextwise sync

📖 Developer Documentation

Explore comprehensive technical documentation, configuration schemas, and reference guides at contextwise.dev/docs:

Predictive Tool Pre-Activation: Sub-millisecond edge ranking, Turn 1 pre-activation, and custom BYOM models.
Zero-Knowledge Secret Vault (vault://): Authenticated AES-256-GCM encrypted keystore with in-memory stream redaction.
MCPaid Cloud Sync & Micro-Monetization: Zero-knowledge multi-device sync via EIP-712 USDC micropayments.
Enterprise Guardrails & Circuit Breakers: Pre-flight Ajv JSONSchema validation, SHA-256 caching, and runaway loop prevention.
Dynamic Server Discovery & Hot-Loading: Terminal registry browser and autonomous in-chat server hot-loading.

Architecture & Features

+─────────────────────────────────────────────────────────────+
|                     AI Client Applications                  |
|        (Claude Code, Cursor, Antigravity, Claude Desktop)   |
+─────────────────────────────────────────────────────────────+
                               │  [JSON-RPC 2.0 / stdio]
                               ▼
+─────────────────────────────────────────────────────────────+
|                      CONTEXTWISE PROXY                      |
|                                                             |
|  [Dynamic Router]            [Pre-Flight Execution Guard]   |
|   • BM25 + Vector Search      • AJV JSONSchema Validator    |
|   • Top-K Context Routing     • Read-Only Response Cache    |
|   • Pinned Core Tools         • Runaway Loop Breaker        |
|   • LRU Tool Eviction         • Velocity Rate Limiter       |
|                              │                              |
|  [Upstream Multiplexer & Supervisor]                        |
|   • Cross-platform child process management                 |
|   • Stdio & SSE upstream multiplexing                       |
|   • Persistent ROI & Token Analytics Engine                 |
+─────────────────────────────────────────────────────────────+
         │                     │                     │
         ▼ [stdio]             ▼ [stdio]             ▼ [SSE]
    Upstream MCP 1        Upstream MCP 2        Upstream MCP 3
      (Postgres)             (GitHub)              (Linear)

Upstream Multiplexing: Connects to multiple stdio and SSE MCP servers simultaneously.
Dynamic Meta-Tooling (Mode 1): Search and invoke any tool with zero initial token bloat.
List-Changed Event Push (Mode 2): Dynamically pushes hydrated tools using notifications/tools/list_changed.
Pre-Flight Argument Validation: Compiles JSONSchemas with Ajv and rejects invalid arguments in < 1 ms before calling upstreams.
Idempotent Response Cache: Caches read-only queries with content-addressable SHA-256 keys, invalidating automatically when write tools execute.
Runaway Loop Breaker: Detects repeating failures (trips circuit after 3 consecutive failures with identical args) and caps call velocity.
Workspace Context Pre-Priming (Mode 4): Auto-detects project files (.git, Dockerfile, SQL) to pre-seed relevant tools.

Testing

ContextWise is tested end-to-end with unit and integration tests across multiplexing, caching, circuit breaking, and dynamic routing:

npm test

 Test Files  16 passed (16)
      Tests  138 passed (138)