Skip to main content
Glama

spillway-mcp — Multi-provider inference router

Node.js >= 18 MCP Protocol Zero Dependencies License: Apache 2.0

v1.4: read-only Codex bridge (Temporary Interim Release — v2 Rewrite Pending)

Status Notice: v1.4 is a temporary interim update that adds read-only Codex CLI capabilities to the existing v1 server architecture for immediate use. A full v2 architectural rewrite (persistent out-of-process supervisor, staged artifact isolation, OS-enforced containment, and a unified multi-provider execution control plane) is pending and will supersede the v1.x runtime.

Claude Code remains the orchestrator and owns task decomposition, acceptance, and commits. Codex adds independent research, debugging analysis, and code review through five tools:

Tool

Purpose

codex_research

Start read-only research with an explicit model and reasoning effort.

codex_followup

Resume a completed Spillway session by explicit session_id, in the same workspace/home and model.

codex_job_result

Inspect or wait for a job_id.

codex_status

Inspect setup, queue, configured model, and quota uncertainty without inference.

codex_cancel

Request cancellation and wait for stop evidence; never pre-approved as read-only.

Codex and agy have independent queues, one worker each. Cross-provider reads may overlap. Cooperating agy edits, local test commands, and local draft writes exclude both providers' reads. Local draft application checks for target drift after inference and refuses stale overwrites. Run only one Spillway server against a shared workspace/provider home in v1. These are in-process coordination rules, not machine-wide locks or protection from editor saves.

Setup

The current compatibility pin is codex-cli 0.166.0-alpha.5.1, verified on Windows. Other CLI versions fail explicitly until their config and sandbox behavior is validated. Node remains >=18; there are no new npm runtime dependencies. Native macOS/Linux execution has not been certified by this Windows test run.

  1. Use the pinned native Codex binary, or set SPILLWAY_CODEX_BIN to a native executable or the npm package's bin/codex.js. Standard npm Windows wrappers resolve to that Node entrypoint; the server does not execute wrappers through a shell.

  2. Optionally set SPILLWAY_CODEX_HOME to a dedicated directory. Its default is config/codex-runtime/home beneath AGY_CONFIG_DIR. Do not use your normal ~/.codex home. Use the same settings for setup and the MCP server.

  3. Run npm run codex:login interactively. This explicitly signs in with ChatGPT into the dedicated home, using file credential storage. Startup never copies credentials or triggers login. The helper does not change the parent process's environment or ordinary Codex config.

  4. Set SPILLWAY_CODEX_MODEL to an exact model slug available to your account, or supply model on a research call. No model is guessed. Add these SPILLWAY_CODEX_* settings to the server's MCP environment when launching from an IDE.

  5. Call codex_status, then codex_research with prompt, optional model, effort (low, medium, high, xhigh), cwd, and wait_ms. Model/effort availability depends on the account; unsupported selections fail without fallback. wait_ms: 0 returns a handle immediately; default/max wait is 540 seconds. The worker watchdog is 30 minutes.

The child ignores user config and execpolicy files, marks its project untrusted, disables MCP/app/plugin/subagent/hook delegation, and pins read-only execution with approvals disabled. Windows uses the unelevated sandbox. Prompts go through stdin, never shell interpolation. Ambient API keys, Codex overrides and Node injection settings are not forwarded. The bridge pins ChatGPT authentication and has no automatic API billing, effort, model, or cross-provider fallback. Administrator-managed restrictions still apply; a refusal is not worked around. See Codex non-interactive execution and the configuration reference.

ok means a zero-exit, valid completed CLI turn with nonempty text and a matching final artifact. It does not certify the answer or task success. Jobs record the explicitly requested model/effort, CLI version, prompt hash, usage as reported, session, output, and stop evidence. Account quota remains unknown. Filesystem reads are live; read-only is not a confidentiality boundary around the workspace. For independent review, pass source/diff, requirements and test evidence, withholding the author's rationale yourself; mechanical blinding and immutable artifact review are v2 features.

Validation and recovery

npm test exercises mock providers, stream parsing, lifecycle failures, workspace coordination, and MCP framing without cloud inference. npm run test:codex-canary separately exercises the installed CLI against a loopback fake Responses provider, including explicit resume. The Windows canary verified a file read, denied writes inside/outside the workspace, and no user/project MCP startup. It uses no account credentials or real inference, and stores private proof under .local/canaries/.

Codex records and logs live under config/codex-runtime/ (or the configured runtime config directory). Unconfirmed stops become quarantined; lost active ownership on restart becomes outcome_unknown. Both block further managed execution. Local commands also leave a conservative recovery marker if execution or termination is unresolved. Do not delete a marker merely because the parent PID is gone: stop all owning server instances and inspect remaining processes before manually resolving retained records. No automatic recovery/clear tool is supplied in v1. Retention is manual; preserve unresolved jobs and session data needed for follow-up.

The package allowlist excludes live credentials, runtime records, and .local/. These runtime paths are Git-ignored. Persistent supervisor ownership, stronger containment, staged edits/apply, and automatic recovery remain v2 work.

Related MCP server: multi-ai-hub

1. Executive Summary

spillway-mcp is a zero-dependency Node.js Model Context Protocol (MCP) server that connects Claude Code (Opus / Fable / Sonnet) to Gemini through agy, read-only Codex CLI, and local GPU inference. The existing Gemini/local routing tiers remain:

  1. Tier 0 (Apex Orchestrator): Claude Code (Opus / Fable / Sonnet) handles high-level architectural decisions, surgical multi-line Edit patches, and final user synthesis.

  2. Tier 1 & 2 (Cloud Subagent Governor — Google Antigravity agy): Routes wide-context exploration, disjoint-directory swarms, and deep multi-file reasoning across Gemini 3.8 Flash (1x–2x weight) and Gemini 4 Argon (4x–6x weight) with deterministic 5-hour/weekly quota governance and automatic 429 step-down.

  3. Tier 3 (Local Consumer GPU Context Scrubber — Ollama / llama-server): Intercepts high-volume file reads, verbose test/build logs, and leaf-node boilerplate generation on a local GPU (0x cloud quota burn), returning <300 token forensic <file>:<line> digests so raw file bloat and passing test noise never enter cloud context windows.

In production workflows, this spillway architecture reduces frontier cloud token consumption by 40–60% while eliminating mid-session context rot and stale-memory hallucinations.


2. Architecture & Data Flow

+-----------------------------------------------------------------------------------+
|                        TIER 0: FRONTIER ORCHESTRATOR                              |
|                 Claude Code (Opus / Fable / Sonnet Session)                       |
|   Receives `ZERO-TRUST MEMORY` & routing rules via MCP `initialize.instructions`  |
+-----------------------------------------+-----------------------------------------+
                                          |
                                          | JSON-RPC 2.0 over stdio
                                          v
+-----------------------------------------------------------------------------------+
|                     SPILLWAY MCP SERVER (`server/index.js`)                       |
|  - Server-side disk reader (raw files & verbose logs never cross MCP arguments)   |
|  - Single-process execution queues (AGY_MAX_CONCURRENCY=1, LOCAL_GPU_CONCURRENCY=1)|
|  - Secret/binary lockout (.env*, id_rsa, first-4KB \0 null-byte detection)        |
+-------------------+-------------------------------------------+-------------------+
                    |                                           |
     [Context Scrubbing & Leaf Tasks]            [Cross-Module Analysis & Swarms]
     `local_file_scout`                          `agy_delegate_research`
     `local_exec_and_triage`                     `agy_spawn_swarm` (disjoint paths)
     `local_draft_leaf_code`                     `agy_delegate_edit` / `followup`
                    |                                           |
                    v                                           v
+---------------------------------------+   +---------------------------------------+
|     TIER 3: LOCAL GPU WORKER (0x)     |   |   TIER 1 & 2: GEMINI CLOUD GOVERNOR   |
|  Local GPU 8-24GB (`127.0.0.1:11434/8080`)|   |     Google Antigravity CLI (`agy`)    |
|  - Probes Ollama `/api/ps` (hot VRAM) |   |  - `argon-high` (6x) -> `argon-med`   |
|  - 1-based line numbers + 50/50 slice |   |    -> `argon-low` -> `flash-high`     |
|  - Forensic `SCOUT_SYSTEM_PROMPT`     |   |    -> `flash-medium` -> `flash-low`   |
|  - Empty/truncated overwrite guard    |   |  - 80% session context auto-compaction|
+-------------------+-------------------+   +-------------------+-------------------+
                    |                                           ^
                    +----- Automatic Zero-Error Spillover ------+
                      (If local GPU is offline / gaming mode
                       or payload exceeds VRAM ceiling)

3. Key Engineering Problems Solved

A. Context Pollution & Cloud Token Burn ("Context Rot")

When a frontier orchestrator (Opus / Fable / Sonnet) reads five 800-line source files (~16,000 tokens) or runs pytest / npm test producing 2,500 lines of passing test output (~25,000 tokens), those raw tokens remain in the conversation history for every subsequent turn.

  • How spillway-mcp solves it: local_file_scout and local_exec_and_triage read files and execute test runners on the MCP server side. The local GPU extracts only the requested <file>:L<line> signatures or failing stack traces (<300 tokens), keeping 95%+ of raw noise out of the cloud context window.

B. Zero-Trust Disk Verification (Eliminating Stale-Memory Hallucinations)

In long-running coding sessions (15+ turns), frontier LLMs (Opus / Fable / Sonnet) suffer from recency/memory bias—answering architectural questions from stale turns rather than re-verifying the disk, or skipping Read calls to save context.

  • How spillway-mcp solves it:

    1. Triple-Anchored ZERO-TRUST MEMORY Rule: Injected at Turn 0 via MCP initialize.instructions, reinforced in tool schema descriptions, and anchored at the bottom of every tool output in the [AGY GOVERNOR TELEMETRY] footer.

    2. Forensic SCOUT_SYSTEM_PROMPT: Instructs the local GPU to report only verbatim signatures with 1-based line numbers (src/auth.ts:L42-L58), or emit the deterministic sentinel "NOT_FOUND_ON_DISK: [symbol/query]" if absent.

C. Consumer GPU Safeguards (12 GB VRAM Hard Limits)

Running a local LLM on a multipurpose workstation requires strict hardware safeguards:

  1. Ollama /api/ps vs. /v1/models Trap Guard: On Ollama (:11434), GET /v1/models lists every downloaded model on disk, which can trigger a 15-second cold load of an oversized model. The router probes GET /api/ps first to use the model already hot in VRAM and passes "keep_alive": "30m".

  2. Empty-Output & Truncation Overwrite Guard: In local_draft_leaf_code, if the local model returns <15 characters, conversational filler, an unclosed markdown code fence (```), or finish_reason === "length", the server aborts the disk write, leaves target_file untouched, and escalates to gemini-3.8-flash-high.

  3. Windows Process-Tree Reaping (taskkill /T /F): Timed-out test runners request a tree stop. Windows confirmation requires successful taskkill /T /F and observed child closure; failed confirmation is reported explicitly. This is ordinary process-tree handling, not escape-proof containment.

  4. 50-50 Head/Tail Slicing with Preserved Line Numbers: Files exceeding the VRAM context budget (80,000 chars on 12 GB VRAM) are numbered first (1: ...) and sliced 50% head / 50% tail so imports at the top and exports at the bottom retain exact line numbers.

D. Deterministic Quota & Rate-Limit Governance

  • Tracks rolling 5-hour and weekly weighted burn budgets in config/state-ledger.json (auto-initialized from config/state-ledger.example.json).

  • Parses 429 RESOURCE_EXHAUSTED cooldown timers (Resets in 1h20m30s) from agy logs, locks the exhausted tier until its reset timestamp, and transparently steps down the fallback chain (argon-high -> argon-medium -> argon-low -> flash-high -> flash-medium -> flash-low).

E. Non-Invasive Security & Least-Privilege Defaults

  • Zero Side Effects on stdio Startup: Starting the MCP server never modifies CLAUDE.md, AGENTS.md, .git/config, or .claude/settings.local.json.

  • Least-Privilege Bootstrap: Running --bootstrap never sets enableAllProjectMcpServers: true and pre-approves only the 5 read-only tools (agy_status, agy_delegate_research, agy_spawn_swarm, agy_job_result, local_file_scout).

  • Safe Triage Command Allowlist: local_exec_and_triage blocks shell chaining operators (&&, ;, |) and restricts execution to allow-listed test, typecheck, and lint runners.

  • Async Job Handoff & Hard Watchdog (AGY_SOFT_TIMEOUT_MS / AGY_RUN_MAX_MS): Every agy run is assigned a job_id and registered in sessions and agy_process_queue at launch (state: "running", started_at, elapsed_s, tier, prompt_preview). If a run exceeds the soft budget (AGY_SOFT_TIMEOUT_MS, default 540000 = 540s, below the 600s MCP client timeout), the tool returns a normal non-error response (still running, job <id>...; fetch with agy_job_result <id>) while the child continues in the background, preventing dropped stdio connections. A hard watchdog (AGY_RUN_MAX_MS, default 1800000 = 30m) terminates genuinely hung processes and preserves the log path, and agy_cancel lets callers abort any in-flight or queued job on demand.


4. Exposed MCP Tools (11 Tools)

Tool Name

Tier

Quota Burn

Purpose

local_file_scout

Tier 3 (Local GPU -> Flash Fallback)

0x

Forensic <file>:L<line> signature & import extractor (<300 tokens).

local_exec_and_triage

Tier 3 (Local GPU -> Flash Fallback)

0x

Runs allow-listed test/build commands; returns <=40 lines directly or scrubs >40 lines on GPU.

local_draft_leaf_code

Tier 3 (Local GPU -> Flash Fallback)

0x

Drafts boilerplate/unit tests to disk with truncation guard + git diff --stat.

agy_delegate_research

Tier 1/2 (Gemini Flash / Argon)

1x–6x

Read-only codebase investigation (--mode=plan) with headless git allow-list rules & 540s soft async handoff.

agy_spawn_swarm

Tier 1 (Gemini Flash Low/Med)

1x/task

Disjoint-directory subagent swarm (serialized sequentially) with path-collision validation.

agy_delegate_edit

Tier 2 (Gemini Argon / Flash)

2x–6x

Scoped multi-file modifications (--mode=accept-edits) with optional IDE --diff review.

agy_session_followup

Tier 1/2 (Session Resume)

1x–6x

Resumes cached conversation_id and auto-compacts at 80% context usage.

agy_job_result

Utility (Async Job Fetch)

0x

Retrieves the stored answer or live elapsed status of an async job_id (or "latest").

agy_cancel

Utility (Queue Control)

0x

Cancels a running or queued job_id (or "active"), waiting for stop evidence; unconfirmed stops quarantine the job and block new agy launches.

agy_configure_workspace

Utility

0x

Auto-detects .venv / node_modules/.bin and configures optional Antigravity IDE HUD sync.

agy_status

Utility

0x

Reports live GPU VRAM probe, cloud quota timers, active/waiting jobs (agy_process_queue), and sessions.


5. Quick Start Guide

Step 1: Clone & Run the Sandboxed Smoke Test

git clone https://github.com/Secret-art-stack/spillway-mcp.git
cd spillway-mcp
npm test

(npm test runs provider, lifecycle, and process-stop regression tests plus node server/smoke-test.js inside a disposable os.tmpdir() workspace and verifies all offline safeguards, permission rules, and MCP stdio framing).

Step 2: Configure Local GPU Inference (Ollama or llama-server)

Pick your hardware preset in config/model-matrix.json (8gb_vram, 12gb_vram, or 24gb_vram_or_mac_unified). For a 12 GB VRAM GPU with Ollama:

# Enable Flash Attention, 8-bit quantized KV cache, and 16K context window
export OLLAMA_FLASH_ATTENTION=1
export OLLAMA_KV_CACHE_TYPE=q8_0
export OLLAMA_CONTEXT_LENGTH=16384

# Pull and warm the default coding model
ollama pull qwen2.5-coder:14b

Or with llama.cpp (llama-server) on port 8080:

llama-server -m qwen2.5-coder-14b-instruct-q4_k_m.gguf \
  --port 8080 --ctx-size 16384 --cache-type-k q8_0 --cache-type-v q8_0 -fa -ngl 99

Tip: If running heavy desktop/IDE apps alongside the GPU on a 12 GB card (~6.5–7 GB free VRAM), use a 9B/12B model like qwen3.5:9b or gemma4:12b-q4_K_M (~5.5–6.5 GB) so weights + KV cache stay 100% in VRAM without PCIe spillover.

Step 3: Register in Claude Code (.mcp.json)

Copy .mcp.example.json to .mcp.json in your project root (or run node server/index.js --bootstrap with user confirmation):

{
  "mcpServers": {
    "agy-subagent": {
      "command": "node",
      "args": ["./spillway-mcp/server/index.js"],
      "timeout": 600000,
      "env": {
        "AGY_NO_SELF_BOOTSTRAP": "1",
        "AGY_GIT_REPORT_ONLY": "1",
        "AGY_DENY_SKIP_PERMISSIONS": "1",
        "LOCAL_GPU_PROFILE": "12gb_vram",
        "LOCAL_LLM_BASE_URL": "http://127.0.0.1:11434/v1",
        "LOCAL_OLLAMA_MODEL": "qwen2.5-coder:14b"
      }
    }
  }
}

6. Repository Structure

spillway-mcp/
├── server/
│   ├── index.js               # Zero-dependency MCP server & hybrid routing engine
│   ├── providers/agy.js       # Antigravity invocation and response adapter
│   ├── provider-test.js       # Offline provider/routing regression tests
│   └── smoke-test.js          # Sandboxed test suite (runs in os.tmpdir())
├── config/
│   ├── model-matrix.json      # Tiered routing & 8GB / 12GB / 24GB hardware presets
│   ├── state-ledger.example.json
│   └── ide-sync.example.json
├── docs/
│   └── ROUTING_GUIDE.md       # Optional @import guide for CLAUDE.md
├── .mcp.example.json          # Example MCP registration for Claude Code
├── .gitignore                 # Ignores live state-ledger.json, ide-sync.json, .env, logs
├── LICENSE                    # Apache License 2.0
├── package.json               # Metadata and offline test scripts
└── README.md                  # Architectural documentation

7. License

Licensed under the Apache License, Version 2.0.

Execution recovery limits

Running agy cancellation transitions through terminating. Confirmed stops become cancelled or timed_out; unconfirmed stops become quarantined. Restarted servers mark unowned active executions outcome_unknown. Both unresolved states block new agy launches with EXECUTION_UNRESOLVED; they are not automatically pruned or retried. Inspect the recorded job, attempt logs, and remaining processes before resolving ledger records. There is no automatic recovery/clear operation yet; do not clear a record solely because its parent PID is absent.

This v1 gate coordinates agy, Codex, and local writers within one server, not atomic ownership across multiple server processes. Local commands persist an unresolved-execution marker and block further managed work after uncertain termination or restart. Native containment, cross-client scheduling, and recovery controls belong to the v2 supervisor. Retained attempt logs require manual retention management; preserve unresolved-job evidence.

Available Tools

16 tools
agy_cancelA
Idempotent

Cancel a currently running or queued Antigravity job by job_id (or "active"), terminating any hung or unneeded child process tree (taskkill /T /F) and freeing the serialized agy queue immediately. WHEN TO USE: Aborting an in-flight or queued agy job shown in agy_status so subsequent calls are not blocked. DO NOT USE FOR: Read-only status checks (use agy_status or agy_job_result). RETURNS: JSON cancellation report { ok, job_id, previous_state, state, pid, elapsed_s, message } plus telemetry footer.

Inputs: job_id (required).

agy_configure_workspaceA
Idempotent

Update workspace environment configuration and Antigravity IDE Visual HUD settings. Auto-detects project toolchains (.venv, node_modules/.bin), registers monorepo directories (--add-dir), injects environment variables, optionally syncs .vscode/settings.json, and attaches or launches the Antigravity IDE window. WHEN TO USE: Only when configuring custom virtualenv/monorepo paths or toggling IDE Visual HUD attachment. DO NOT USE FOR: Read-only status or quota checks (use agy_status instead). RETURNS: JSON object { ide_window_attached, opened_ide_window, workspace_environment } plus telemetry footer.

Inputs: cwd, add_dirs, attach_ide, follow_files, +6 more.

agy_delegate_editA

Delegate complex multi-file code modifications or cross-module refactoring to Antigravity (agy) in --mode=accept-edits. SERIALIZATION & ASYNC BUDGET: Calls are serialized (one at a time, AGY_MAX_CONCURRENCY = 1); split edits needing >~8 minutes into smaller scoped calls or fetch in-flight runs via agy_job_result. WHEN TO USE: Coordinated edits across multiple existing files requiring Gemini Argon/Flash reasoning. DO NOT USE FOR: Generating a single standalone boilerplate, DTO, schema, or unit test file (use local_draft_leaf_code instead at 0x quota), read-only analysis (use agy_delegate_research), or running test suites (use local_exec_and_triage). RETURNS: Edit summary, optional IDE visual diff confirmation, and telemetry footer.

Inputs: prompt (required), cwd, tier, allow_shell, +2 more.

agy_delegate_researchA
Read-onlyIdempotent

Delegate deep read-only codebase research, cross-module architectural analysis, bug root-cause tracing, or security verification to Google Antigravity CLI (agy) using verified Gemini 3.8 Flash or Gemini 4 Argon models in --mode=plan. SERIALIZATION & ASYNC BUDGET: Calls are serialized (one at a time, AGY_MAX_CONCURRENCY = 1); a prompt that needs more than ~8 minutes of agent time should be split into one bounded question per call, or launched expecting to fetch the result by job_id via agy_job_result (soft handoff at 540s, hard watchdog at AGY_RUN_MAX_MS, cancellable via agy_cancel). WHEN TO USE: Complex multi-file reasoning or architectural audits across 5–30+ files after initial scouting. DO NOT USE FOR: Simple signature, import, or line-number extraction on known files (use local_file_scout instead at 0x quota) or parallel disjoint directory scans (use agy_spawn_swarm instead). RETURNS: Markdown analysis with : citations (or an async job_id handle if still running at soft budget) and telemetry footer.

Inputs: tier (required), prompt (required), cwd, files_to_follow, +2 more.

agy_job_resultA
Read-onlyIdempotent

Fetch the stored output or live status of an Antigravity job by job_id (or "latest"). WHEN TO USE: Retrieving the result of a long-running agy_delegate_research, agy_spawn_swarm, agy_delegate_edit, or agy_session_followup call that returned "still running, job <id>..." after reaching the soft budget (default 540s). DO NOT USE FOR: Starting a new research or edit task. RETURNS: The full completed subagent response and session telemetry if finished (done / failed / cancelled / timed_out), or "still running, job <id>, started <time>, elapsed <s>s; fetch with agy_job_result <id>" if still in flight.

Inputs: job_id (required), wait_ms.

agy_session_followupA

Resume an existing Antigravity conversation ID (--conversation ) so previously loaded files remain in context cache, automatically compacting the session if context usage exceeds 80%. SERIALIZATION & ASYNC BUDGET: Calls are serialized (one at a time, AGY_MAX_CONCURRENCY = 1); keep follow-ups to one bounded question (<~8 minutes) or fetch in-flight runs by job_id via agy_job_result. WHEN TO USE: Multi-turn follow-up questions on an existing Session ID returned by a prior agy_delegate_research or agy_delegate_edit call. DO NOT USE FOR: Starting a brand-new research task without a prior session (use agy_delegate_research instead). RETURNS: Follow-up response, optional compaction notice, and updated session telemetry.

Inputs: prompt (required), conversation_id (required), cwd, mode, +2 more.

agy_spawn_swarmA
Read-onlyIdempotent

Dispatch multiple read-only Antigravity subagents using gemini-3.8-flash-low or gemini-3.8-flash-medium across strictly disjoint directory partitions. SERIALIZATION & ASYNC BUDGET: Tasks run sequentially one after another (one at a time, AGY_MAX_CONCURRENCY = 1) and share the same ~8-minute soft budget ceiling; keep each task prompt bounded or fetch any in-flight task result by job_id via agy_job_result. WHEN TO USE: Exploring multiple independent subsystems or directories in a single turn. DO NOT USE FOR: Single-directory research (use agy_delegate_research), single-file signature extraction (use local_file_scout), or overlapping directory paths (rejected by partition validator). RETURNS: Aggregated markdown report per subagent task (or async job_id handles for tasks still running at soft budget) plus telemetry footer.

Inputs: tasks (required), cwd, soft_timeout_ms.

agy_statusA
Read-onlyIdempotent

Inspect current system health, Gemini 5-hour/weekly quota windows, Local GPU VRAM availability (/api/ps), process queue state (active_job, waiting_jobs, recent_jobs with job_id, state, started_at, elapsed_s, tier, prompt_preview), active session context remaining, and Git worktree pre-flight status in read-only mode. WHEN TO USE: Checking whether the Local GPU worker or Gemini Argon/Flash tiers are online, inspecting in-flight/queued jobs, and checking token savings. DO NOT USE FOR: Modifying workspace settings or attaching the IDE (use agy_configure_workspace instead). RETURNS: JSON status report { agy_process_queue, local_gpu_queue, local_gpu_probe, local_gpu_telemetry, model_quotas, sessions } plus telemetry footer.

Inputs: refresh_models.

codex_cancelA
Idempotent

Cancel a queued or running Codex job. Waits for process-stop evidence; an unconfirmed stop quarantines execution.

Inputs: job_id (required).

codex_followupA
Read-only

Continue an explicit completed Spillway Codex session in the same workspace/home and model. Always read-only; never resumes the latest ambient session.

Inputs: prompt (required), session_id (required), cwd, model, +2 more.

codex_job_resultB
Read-onlyIdempotent

Inspect or wait for a Codex job, including retained output and stop evidence.

Inputs: job_id (required), wait_ms.

codex_researchA
Read-only

Run read-only research through a dedicated headless Codex CLI. Separate serialized queue from agy. No automatic provider/model fallback. Returns exact model/effort, session, usage when available, and retained job evidence.

Inputs: prompt (required), cwd, model, effort, +1 more.

codex_statusA
Read-onlyIdempotent

Codex setup, queue, model and quota status. Quota is unknown; this does not perform inference.

Inputs: no named parameters.

local_draft_leaf_codeA

Draft standalone leaf-node boilerplate, unit test files, DTOs, or schemas on disk using the Local GPU LLM (0x cloud quota). Reads reference_files on the server side, validates that the drafted code is >=15 chars with closed markdown fences and no truncation placeholders before writing target_file (automatically aborting disk write and escalating to agy_delegate_edit flash-high if invalid or offline). WHEN TO USE: Creating or updating a single self-contained leaf file (unit tests, schemas, types, boilerplate). DO NOT USE FOR: Complex multi-file refactoring or cross-module architectural edits (use agy_delegate_edit instead). RETURNS: Write confirmation, byte/line counts, and git diff --stat summary.

Inputs: spec (required), target_file (required), reference_files (required), cwd.

local_exec_and_triageA
Read-only

Execute allow-listed test, build, typecheck, or lint commands (pytest, npm test, npx tsc, cargo check, go test) in a managed subprocess with Windows process-tree kill protection (taskkill /T /F) and scrub verbose output on the Local GPU (0x cloud quota). WHEN TO USE: Running any test suite, compiler check, or linter that may produce >40 lines of noisy output. DO NOT USE FOR: Chained shell commands (&&, ;, | are blocked) or file edits. RETURNS: Full output directly if <=40 lines; otherwise a Local GPU-scrubbed digest containing only exit code, failing test names, <file>:<line> locations, and isolated stack traces.

Inputs: command (required), working_dir (required), timeout_ms.

local_file_scoutA
Read-onlyIdempotent

ZERO-TRUST MEMORY TOOL: Read repository files directly from disk on the server side and use the Local GPU LLM (0x cloud quota) as a strict forensic disk-evidence extractor. Outputs verbatim signatures, imports, and logic with exact 1-based <file>:L<line> citations (<300 tokens), or "NOT_FOUND_ON_DISK: [symbol/query]" if absent (automatically escalating to Gemini 3.8 Flash if the local GPU is offline). WHEN TO USE: Always call before raw Read on unfamiliar/large files (>150 lines) or whenever verifying disk state before answering or editing. DO NOT USE FOR: Multi-directory architectural synthesis across 10+ files (use agy_delegate_research after scouting). RETURNS: Concise markdown bullet digest with <file>:L<line> citations and telemetry footer.

Inputs: query (required), file_paths (required), cwd.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 16 tools

    Disambiguation3/5

    The prefix scheme separates three backends (codex_, agy_, local_), but each backend exposes near-parallel operations — codex_research vs agy_delegate_research, codex_followup vs agy_session_followup, codex_status vs agy_status, codex_cancel vs agy_cancel — so an agent must read the routing rules to pick correctly. Descriptions do a lot of work with explicit 'DO NOT USE FOR' clauses, but the overlapping research/scout/draft/edit triad (local_file_scout vs agy_delegate_research vs local_draft_leaf_code vs agy_delegate_edit) remains genuinely easy to misselect.

    Naming Consistency3/5

    A consistent three-prefix scheme (codex_/agy_/local_) groups tools predictably, which is a real strength. Within groups, however, conventions are mixed: verb_noun (agy_delegate_edit, agy_spawn_swarm) sits beside noun-phrase tools (agy_status, agy_job_result, codex_job_result) and odd forms like local_file_scout (noun_verb) and local_exec_and_triage.

    Tool Count3/5

    Sixteen tools is at the borderline of heavy, and the cost is amplified because the surface duplicates the same lifecycle (research, follow-up, status, cancel, job-result) across two agent backends plus a local tier. Each tool is justified individually, but the aggregate feels larger than the underlying domain requires.

    Completeness4/5

    Coverage is broad: research, editing, multi-file delegation, drafting, command execution, session follow-up, job retrieval, cancellation, status, and workspace configuration are all present, so most workflows have a path forward. Minor gaps include no generic file read/list or job-listing operation independent of the status tools, and Codex offers no edit path at all.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      One MCP that turns Claude Code into your whole dev stack by swallowing other MCP servers, delegating to Codex & Gemini on your CLI subscriptions, remembering projects in a searchable knowledge graph, and carrying setup across sessions — secret-free by design.
      23
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides an MCP endpoint that lets clients like Google Antigravity and Claude Desktop dispatch LLM tasks to local GPU models with automatic hardware-adaptive routing and cloud fallback, enabling near-zero token cost execution.
      3
      4
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents and MCP clients to dispatch queries to the most suitable model among 70+ LLMs by scoring intent, budget, cost, and latency, returning structured routing decisions with execution telemetry. It runs as a zero-dependency Python MCP server that plugs into Claude Desktop, Cursor, and other MCP-compatible clients.
      8
      -