What can you do with this server?

Nexus MCP is an MCP server that enables AI models to invoke and orchestrate multiple AI CLI agents (Gemini CLI, Codex, Claude Code, OpenCode) as tools, with support for parallel execution, retries, and persistent preferences. * Parallel Agent Execution (batch_prompt): Fan out multiple prompts to different CLI runners simultaneously with configurable concurrency (default: 3), receiving aggregated results with success/failure counts * Single Agent Interaction (prompt): Convenience wrapper to send one prompt to a specific CLI runner as a background task, returning a task ID to avoid MCP timeouts * Persistent Preferences (set_preferences, get_preferences, clear_preferences): Configure and manage session-wide defaults for execution mode, model, max retries, output limits, timeouts, and backoff parameters * Execution Modes: default (safe, no auto-approve) and yolo (full auto-approve), configurable per-task or as a session default * Automatic Error Handling: Exponential backoff retries with jitter for transient errors (HTTP 429/503), with JSON-first parsing, brace-depth fallback, and temp-file spillover for large outputs (>50KB) * Prompt Templates: 10 discoverable workflow scaffolds (e.g., code_review, debug, research, implement_feature, compare_models) with structured expert framing * Model Tier Classification: Heuristic classification into quick/standard/thorough tiers, manageable via set_model_tiers and get_model_tiers * Interactive Elicitation: Prompts for missing parameters (runner selection, model choice, YOLO confirmation) when supported by the client, with suppression flags * Resource Access: Read-only endpoints (nexus://runners, nexus://config, nexus://preferences) for querying runner metadata, configuration, and current preferences * Client-Visible Logging: Sends runner events (retries, truncation, errors) to MCP clients via protocol notifications * Extensible Architecture: Add custom runners by implementing build_command + parse_output and registering in RunnerFactory * OpenCode Server Integration: Optional Docker-based OpenCode server providing additional MCP tools and HTTP-based agent execution

Which integrations are available for this server?

Integrates the Gemini CLI as a tool, allowing AI models to perform parallelized research, summarization, and content generation using Google's AI models. Enables interaction with the OpenCode CLI to query models via Ollama and Ollama Cloud, supporting structured outputs and concurrent multi-model comparisons.

de en es ja ko ru zh

nexus-mcp

by j7an

Overview Schema Source Related Servers Discussions Admin

Python

Local

Nexus MCP is an MCP server that enables AI models to invoke and orchestrate multiple AI CLI agents (Gemini CLI, Codex, Claude Code, OpenCode) as tools, with support for parallel execution, retries, and persistent preferences.

Parallel Agent Execution (batch_prompt): Fan out multiple prompts to different CLI runners simultaneously with configurable concurrency (default: 3), receiving aggregated results with success/failure counts
Single Agent Interaction (prompt): Convenience wrapper to send one prompt to a specific CLI runner as a background task, returning a task ID to avoid MCP timeouts
Persistent Preferences (set_preferences, get_preferences, clear_preferences): Configure and manage session-wide defaults for execution mode, model, max retries, output limits, timeouts, and backoff parameters
Execution Modes: default (safe, no auto-approve) and yolo (full auto-approve), configurable per-task or as a session default
Automatic Error Handling: Exponential backoff retries with jitter for transient errors (HTTP 429/503), with JSON-first parsing, brace-depth fallback, and temp-file spillover for large outputs (>50KB)
Prompt Templates: 10 discoverable workflow scaffolds (e.g., code_review, debug, research, implement_feature, compare_models) with structured expert framing
Model Tier Classification: Heuristic classification into quick/standard/thorough tiers, manageable via set_model_tiers and get_model_tiers
Interactive Elicitation: Prompts for missing parameters (runner selection, model choice, YOLO confirmation) when supported by the client, with suppression flags
Resource Access: Read-only endpoints (nexus://runners, nexus://config, nexus://preferences) for querying runner metadata, configuration, and current preferences
Client-Visible Logging: Sends runner events (retries, truncation, errors) to MCP clients via protocol notifications
Extensible Architecture: Add custom runners by implementing build_command + parse_output and registering in RunnerFactory
OpenCode Server Integration: Optional Docker-based OpenCode server providing additional MCP tools and HTTP-based agent execution

Nexus MCP

PyPI Python 3.13+ License: MIT Ruff type-checked: mypy pre-commit MCP

An MCP server that enables AI models to invoke AI CLI agents (Codex, Claude Code, OpenCode) as tools. Provides durable workspace-scoped jobs, parallel execution, automatic retries with exponential backoff, JSON-first response parsing, discoverable prompt templates, model tier classification, and persistent preferences through MCP tools, resources, and prompts.

Use Cases

Nexus MCP is useful whenever a task benefits from querying multiple AI agents in parallel rather than sequentially:

Research & summarization — fan out a topic to multiple agents, then synthesize their responses into a single summary with diverse perspectives
Code review — send different files or review angles (security, correctness, style) to separate agents simultaneously
Multi-model comparison — prompt the same question to different models and compare outputs side-by-side for quality or consistency
Bulk content generation — generate multiple test cases, translations, or documentation pages concurrently instead of one at a time
Second-opinion workflows — get independent answers from separate agents before making a decision, reducing single-model bias

Related MCP server: mcp-cli-catalog

Features

Parallel execution — batch_prompt fans out tasks with asyncio.gather and a configurable semaphore (default concurrency: 3)
Durable jobs — start, observe, cancel, and resume normalized agent work through stable job and session identities backed by a private per-user SQLite database
Automatic retries — exponential backoff with full jitter for transient errors (HTTP 429/503)
Output handling — JSON-first parsing, brace-depth fallback for noisy stdout, temp-file spillover for outputs exceeding 50 KB
Execution modes — default (safe, no auto-approve), yolo (full auto-approve)
CLI detection — auto-detects binary path, version, and JSON output capability at startup
Persistent preferences — set defaults for execution mode, model, retries, output limit, and timeout; preferences persist across MCP sessions via the backing store (MemoryStore default, FileTreeStore/RedisStore for restart persistence)
Prompt templates — 10 discoverable workflow scaffolds (code review, debug, research, implement feature, etc.) via list_prompts/get_prompt; each returns structured messages with expert framing the client can use or ignore
Model tier classification — heuristic-based model classification into quick/standard/thorough tiers; clients can override with sampling or live benchmarks. The nexus://runners resource includes tier data per model
Tool timeouts — configurable safety timeout (default 15 min) cancels long-running tool calls to prevent the server from blocking indefinitely
Client-visible logging — runner events (retries, output truncation, error recovery) are sent to MCP clients via protocol notifications, not just server stderr
Elicitation — interactive parameter resolution via MCP elicitation; disambiguates missing CLI, offers model selection, confirms YOLO mode, and prompts for elaboration on vague prompts. Auto-detects client support and skips gracefully when unavailable. Suppression flags prevent repeat prompts within a session
Benchmark data sources — server instructions include URLs for Artificial Analysis, OpenRouter, Chatbot Arena, and LLM Stats so clients can fetch live model benchmarks without API keys
Extensible — implement build_command + parse_output, register in RunnerFactory

Agent	Status
Codex	Supported
Claude Code	Supported
OpenCode	Supported

Installation

Run with uvx (recommended)

uvx nexus-mcp

uvx installs the package in an ephemeral virtual environment and runs it — no cloning required.

To check the installed version:

uvx nexus-mcp --version

To update to the latest version:

uvx --reinstall nexus-mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "nexus-mcp": {
      "command": "uvx",
      "args": ["nexus-mcp"],
      "env": {
        "NEXUS_CODEX_MODEL": "gpt-5.2",
        "NEXUS_CODEX_MODELS": "gpt-5.4,gpt-5.4-mini,gpt-5.3-codex,gpt-5.2-codex,gpt-5.2,gpt-5.1-codex-max,gpt-5.1-codex-mini",
        "NEXUS_CLAUDE_MODEL": "claude-sonnet-4-6",
        "NEXUS_CLAUDE_MODELS": "claude-sonnet-4-6,claude-haiku-4-5-20251001",
        "NEXUS_OPENCODE_MODEL": "ollama-cloud/kimi-k2.5",
        "NEXUS_OPENCODE_MODELS": "ollama-cloud/glm-5,ollama-cloud/kimi-k2.5,ollama-cloud/qwen3-coder-next,ollama-cloud/minimax-m2.5,ollama/gemini-3-flash-preview"
      }
    }
  }
}

Cursor (.cursor/mcp.json in your project or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "nexus-mcp": {
      "command": "uvx",
      "args": ["nexus-mcp"],
      "env": {
        "NEXUS_CODEX_MODEL": "gpt-5.2",
        "NEXUS_CODEX_MODELS": "gpt-5.4,gpt-5.4-mini,gpt-5.3-codex,gpt-5.2-codex,gpt-5.2,gpt-5.1-codex-max,gpt-5.1-codex-mini",
        "NEXUS_CLAUDE_MODEL": "claude-sonnet-4-6",
        "NEXUS_CLAUDE_MODELS": "claude-sonnet-4-6,claude-haiku-4-5-20251001",
        "NEXUS_OPENCODE_MODEL": "ollama-cloud/kimi-k2.5",
        "NEXUS_OPENCODE_MODELS": "ollama-cloud/glm-5,ollama-cloud/kimi-k2.5,ollama-cloud/qwen3-coder-next,ollama-cloud/minimax-m2.5,ollama/gemini-3-flash-preview"
      }
    }
  }
}

Claude Code (CLI):

claude mcp add nexus-mcp \
  -e NEXUS_CODEX_MODEL=gpt-5.2 \
  -e NEXUS_CODEX_MODELS=gpt-5.4,gpt-5.4-mini,gpt-5.3-codex,gpt-5.2-codex,gpt-5.2,gpt-5.1-codex-max,gpt-5.1-codex-mini \
  -e NEXUS_CLAUDE_MODEL=claude-sonnet-4-6 \
  -e NEXUS_CLAUDE_MODELS=claude-sonnet-4-6,claude-haiku-4-5-20251001 \
  -e NEXUS_OPENCODE_MODEL=ollama-cloud/kimi-k2.5 \
  -e NEXUS_OPENCODE_MODELS=ollama-cloud/glm-5,ollama-cloud/kimi-k2.5,ollama-cloud/qwen3-coder-next,ollama-cloud/minimax-m2.5,ollama/gemini-3-flash-preview \
  -- uvx nexus-mcp

Generic stdio config (any MCP-compatible client):

{
  "command": "uvx",
  "args": ["nexus-mcp"],
  "transport": "stdio",
  "env": {
    "NEXUS_CODEX_MODEL": "gpt-5.2",
    "NEXUS_CLAUDE_MODEL": "claude-sonnet-4-6",
    "NEXUS_OPENCODE_MODEL": "ollama-cloud/kimi-k2.5"
  }
}

All env keys are optional — see Configuration for the full list.

Prerequisites:

Python 3.13+ (download)

uv dependency manager (install guide)

curl -LsSf https://astral.sh/uv/install.sh | sh

Optional (for integration tests):

Codex — check with codex --version
Claude Code — check with claude --version
OpenCode — check with opencode --version

Claude Code note: Nexus invokes Claude Code non-interactively via claude -p. Anthropic says claude -p and Agent SDK usage draw from separate monthly Agent SDK credits starting 2026-06-15, while interactive Claude Code usage remains on plan usage limits: https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan

Note: Integration tests are optional. Unit tests run without CLI dependencies via subprocess mocking.

# 1. Clone the repository
git clone <repository-url>
cd nexus-mcp

# 2. Install dependencies
uv sync

# 3. Install pre-commit hooks (runs linting/formatting on commit)
uv run pre-commit install

# 4. Verify installation
uv run pytest                    # Run tests
uv run mypy src/nexus_mcp        # Type checking
uv run ruff check .              # Linting

# 5. Run the MCP server
uv run python -m nexus_mcp

⚠️ Experimental — This integration has not been validated end-to-end by the maintainer. Expect rough edges in setup, auth, and tool exposure. The MCP tools surfaced from upstream OpenCode track the upstream project and may change without notice. Feedback and bug reports are welcome.

Run an isolated OpenCode server for HTTP-based agent execution alongside the CLI runner. Provides session management, file search, permissions, and 38 additional MCP tools when the server is healthy.

Quick start:

Copy .env.example to .env and set PROJECT_DIR to your project path:

cp .env.example .env
# Edit .env: set PROJECT_DIR=/path/to/your/project

Start the server:
```
docker compose up -d
```

Authenticate with your provider:

docker exec -it opencode-server opencode auth login

Verify the server is healthy:

curl -u opencode:nexus http://localhost:4096/global/health

The server binds to 127.0.0.1 (localhost only) by default for security. See docs/opencode-server-setup.md for the full guide including remote access, multi-project setup, and network security.

Usage

Once nexus-mcp is configured in your MCP client, your AI assistant automatically sees its tools. The reliable trigger is explicitly asking for output from an external AI agent (e.g. Codex, Claude Code, OpenCode). Generic "do this in parallel" prompts may be handled by the host AI's own capabilities instead. The cli parameter is optional — if omitted and the client supports MCP elicitation, the server will ask which runner to use. The server provides runner metadata (names, models, availability, execution modes) in its connection instructions — no discovery call needed. The cli parameter includes a JSON schema enum listing valid runner names.

Fan out a research question (batch_prompt)

You say: "Get perspectives from Codex, Claude Code, and OpenCode on transformer architectures."

{
  "tasks": [
    { "cli": "codex", "prompt": "Summarize the key findings of the Attention Is All You Need paper", "label": "codex-summary" },
    { "cli": "claude", "prompt": "What are the main limitations of transformer architectures?", "label": "claude-limitations" },
    { "cli": "opencode", "prompt": "List 3 real-world applications of transformers beyond NLP", "label": "opencode-applications" }
  ]
}

Code review from multiple angles (batch_prompt)

You say: "Have Codex, Claude Code, and OpenCode each review this diff in parallel."

{
  "tasks": [
    { "cli": "codex", "prompt": "Review this diff for security vulnerabilities:\n\n<paste diff>", "label": "codex-security-review" },
    { "cli": "claude", "prompt": "Review this diff for correctness and edge cases:\n\n<paste diff>", "label": "claude-correctness-review" },
    { "cli": "opencode", "prompt": "Review this diff for style and maintainability:\n\n<paste diff>", "label": "opencode-review" }
  ]
}

Single-agent prompt

You say: "Ask Codex to explain the difference between TCP and UDP."

{ "cli": "codex", "prompt": "Explain the difference between TCP and UDP in simple terms", "model": "gpt-5.2" }

Elicitation (server picks the runner)

You say: "Explain the CAP theorem using one of the available agents."

{ "prompt": "Explain the CAP theorem in simple terms" }

If the client supports MCP elicitation, the server asks which runner to use. Pass "elicit": false to skip.

Persistent preferences

You say: "Use YOLO mode with Codex from now on."

{ "execution_mode": "yolo", "model": "gpt-5.2", "max_retries": 5 }

Subsequent calls inherit these settings. Preferences persist across MCP sessions until explicitly cleared.

Fallback chain: explicit parameter → saved preference → per-runner env → global env → hardcoded default.

MCP Tools

Nexus exposes a durable agent_* surface and the original compatibility prompt surface. Every durable tool requires an explicit workspace selector containing exactly one of an existing workspace_id or a filesystem path; Nexus never infers a durable workspace from the server's current directory. A path is resolved to one canonical workspace identity before admission.

Execution-starting durable tools return a JobHandle immediately. Clients use the observation and control tools to follow the normalized job independently of an MCP request lifetime.

Tool	Description
`agent_start`	Create a durable session and queue its first turn
`agent_continue`	Queue another turn on an existing session
`agent_fork`	Create a child session when the backend supports forking
`agent_review`	Queue a typed review operation on an existing session
`agent_diagnose`	Queue a sessionless backend diagnostic job
`agent_status`	Read the current normalized status of one job
`agent_result`	Read the pending or terminal typed result of one job
`agent_list`	Page through authorized jobs in one workspace
`agent_backends`	List backend capabilities and current availability for one workspace
`agent_cancel`	Request idempotent cancellation of a queued or active job
`agent_respond`	Resolve a pending approval, permission, question, or form input

The compatibility prompt and batch_prompt tools retain their background-task behavior. They return FastMCP task IDs so clients can poll without holding a long-running MCP request open. Per-call concurrency defaults to 3. The shared process runtime starts with 3 workers and grows to a high-water maximum of 8; one call whose effective demand exceeds 8 is rejected explicitly, while concurrent calls share the process ceiling and may queue.

Tool	Task?	Description
`batch_prompt`	Yes	Fan out prompts to multiple runners in parallel; returns `MultiPromptResponse`
`prompt`	Yes	Single-runner convenience wrapper; routes to `batch_prompt`
`set_preferences`	No	Set or selectively clear persistent defaults for execution mode, model, retries, timeouts, elicitation, and trigger suppression
`get_preferences`	No	Retrieve current preferences
`clear_preferences`	No	Reset all preferences
`set_model_tiers`	No	Save model tier classifications (client sends sampling/benchmark results; server persists)
`get_model_tiers`	No	Retrieve saved model tier classifications

`batch_prompt`

Parameter	Required	Default	Description
`tasks`	Yes	—	List of task objects (see below)
`max_concurrency`	No	`3`	Max parallel agent invocations for this call; effective demand above the process worker maximum of 8 is rejected
`elicit`	No	pref or `true`	Enable/disable interactive elicitation for this call

Task object fields:

Field	Required	Default	Description
`cli`	No	—	Runner name (e.g. `"codex"`); if omitted, elicitation asks which runner to use
`prompt`	Yes	—	Prompt text
`label`	No	auto	Display label for results
`context`	No	`{}`	Optional context metadata dict
`execution_mode`	No	pref or `"default"`	`"default"` or `"yolo"`
`model`	No	pref or CLI default	Model name override
`max_retries`	No	pref or env default	Max retry attempts for transient errors
`output_limit`	No	pref or env default	Max output bytes
`timeout`	No	pref or env default	Subprocess timeout in seconds
`retry_base_delay`	No	pref or env default	Base delay for exponential backoff
`retry_max_delay`	No	pref or env default	Max delay cap for backoff

Note: elicit is a batch-level parameter. When enabled, the server runs a single upfront elicitation pass across all tasks rather than prompting per-task.

`prompt`

Same parameters as a single task object in batch_prompt, plus elicit (batch-level in batch_prompt, per-call here).

`set_preferences`

Parameter	Required	Default	Description
`execution_mode`	No	—	`"default"` or `"yolo"`
`model`	No	—	Model name (e.g. `"gpt-5.2"`)
`max_retries`	No	—	Max total attempts (≥1; 1 = no retries)
`output_limit`	No	—	Max output bytes (≥1)
`timeout`	No	—	Subprocess timeout seconds (≥1)
`retry_base_delay`	No	—	Backoff base delay seconds (≥0)
`retry_max_delay`	No	—	Backoff max delay seconds (≥0)
`elicit`	No	`true`	Enable/disable elicitation
`confirm_yolo`	No	`true`	Prompt before YOLO mode (auto-suppressed after first accept)
`confirm_vague_prompt`	No	`true`	Prompt on very short prompts
`confirm_high_retries`	No	`true`	Prompt when max_retries > 5
`confirm_large_batch`	No	`true`	Prompt when batch > 5 tasks
`clear_*`	No	`false`	Clear any field individually (e.g. `clear_model: true`)

`get_preferences` / `clear_preferences`

get_preferences — no parameters, returns all fields (null when unset). clear_preferences — no parameters, resets all to null. Does not clear model tiers.

`set_model_tiers`

Parameter	Required	Default	Description
`tiers`	Yes	—	Dict mapping model names to tiers (`"quick"`, `"standard"`, `"thorough"`)

Persists tier classifications. Clients typically call once via sampling or benchmark fetch.

`get_model_tiers`

No parameters. Returns saved tiers as dict[str, str], or {} if none saved.

Managing Preferences

Operation	Tool	Notes
Set fields	`set_preferences`	Persists across sessions
Read values	`get_preferences`	`null` for unset fields
Clear all	`clear_preferences`	Does not clear model tiers
Clear one field	`set_preferences` with `clear_*: true`	Others preserved
Suppress elicitation	`set_preferences` with `confirm_*: false`	YOLO/batch/retry auto-suppress after accept
Re-enable prompt	`set_preferences` with `clear_confirm_*: true`	Resets to default
Save/read tiers	`set_model_tiers` / `get_model_tiers`	Persists across sessions

Durable Job Architecture

The framework-independent core separates normalized domain contracts from concrete backends, storage, and the MCP transport. A job is one admitted operation and owns its retry attempts, events, controls, and terminal result. A session is a durable conversation identity bound to one workspace and backend; agent_start creates it, agent_continue reuses it, and agent_fork creates a child when supported. Diagnostic jobs may be sessionless. A session and a job are not MCP client sessions or FastMCP background-task IDs.

Jobs and sessions use private | workspace access policies:

private (the default) is visible only to the owning principal.
workspace is visible to the owner and to callers explicitly authorized for that same workspace. It never grants cross-workspace access. For the local MCP adapter, the operating-system user is the principal and the private database permissions form the trust boundary.

The SQLite database contains sensitive prompts, normalized events, provider references, and results. Set NEXUS_DB_PATH to override its location. Otherwise Nexus uses these per-user paths:

macOS: ~/Library/Application Support/nexus-mcp/nexus.sqlite3
Windows: %LOCALAPPDATA%\nexus-mcp\nexus.sqlite3 (falling back to ~/AppData/Local/nexus-mcp/nexus.sqlite3)
Linux and other Unix platforms: ${XDG_DATA_HOME:-~/.local/share}/nexus-mcp/nexus.sqlite3

On POSIX systems Nexus removes group and other access from the database directory and SQLite files. Normalized job, session, event, and result records are retained indefinitely by default; Nexus does not schedule automatic pruning. Applying retention cutoffs is an explicit store operation, and no public MCP pruning tool is currently exposed.

Codex, Claude Code, and OpenCode execution currently passes through the temporary LegacyRunnerBackend bridge while native backends are developed. The bridge supports normalized turns only: it does not provide backend cancellation, graceful interruption, session forking, or safe reconciliation after an interrupted attempt. These are legacy-backend limitations, not core job-model promises; clients should inspect agent_backends capabilities before selecting an operation.

MCP Prompts

Nexus MCP provides 10 discoverable prompt templates that clients can browse via list_prompts() and render via get_prompt(name, args). Each prompt returns structured messages with expert framing — the client decides how (or whether) to use them.

Design principle: Server informs, client decides. Prompts provide the scaffold (role, structure, methodology); the client decides runner, model, depth, and orchestration. Prompts are completely optional — existing prompt/batch_prompt tools work exactly as before.

Prompt	Tags	Parameters	Purpose
`code_review`	analysis	`file`, `instructions`	Structured code review with findings by severity
`debug`	analysis	`error`, `context`, `file`	Systematic diagnosis: reproduce, isolate, root cause, fix
`quick_triage`	analysis	`description`, `file`	Fast assessment: what's wrong, severity, next step
`research`	analysis	`topic`, `scope`	Structured research with source citations
`second_opinion`	analysis	`original_output`, `question`	Independent review of another AI's output
`implement_feature`	generation	`description`, `language`, `constraints`	Feature implementation with quality checklist
`refactor`	generation	`file`, `goal`, `constraints`	Behavior-preserving restructuring
`bulk_generate`	generation	`template`, `variables`	Expand template across variable sets
`write_tests`	testing	`file`, `framework`, `coverage_goal`	Test generation with configurable coverage approach
`compare_models`	comparison	`prompt`, `criteria`	Multi-runner comparison framework

# 1. Client discovers available prompts
list_prompts() → sees "code_review", "debug", "compare_models", etc.

# 2. Client renders a prompt with arguments
get_prompt("code_review", {file: "src/auth.py", instructions: "security vulnerabilities"})

# 3. Server returns structured messages
→ PromptResult(
    messages=[
      Message("You are a senior code reviewer...", role="assistant"),
      Message("Review the file `src/auth.py`...\nFocus: security vulnerabilities\n...", role="user"),
    ],
    description="Code review of src/auth.py"
  )

# 4. Client feeds messages into prompt/batch_prompt with chosen runner+model
prompt(cli="claude", prompt=<rendered messages>)

MCP Resources

Read-only data endpoints that clients query for runner metadata, configuration, and preferences.

Resource URI	Description
`nexus://runners`	All registered CLI runners with models (enriched with tier data), modes, availability
`nexus://runners/{cli}`	Single runner details by name (URI template)
`nexus://config`	Resolved operational config defaults (timeouts, retries, output limits)
`nexus://preferences`	Current preferences with config fallback

Models in nexus://runners include tier data: {"name": "gpt-5.4-mini", "tier": "quick"}. Tiers are quick (fast/cheap), standard (balanced), or thorough (max quality). Models with only heuristic tiers appear in unclassified_models — calling set_model_tiers moves them out.

Before set_model_tiers — all tiers are heuristic guesses, all models are unclassified:

{
  "models": [
    {"name": "gpt-5.1-codex-max", "tier": "thorough"},
    {"name": "gpt-5.4-mini", "tier": "quick"},
    {"name": "claude-sonnet-4-6", "tier": "standard"}
  ],
  "unclassified_models": ["gpt-5.1-codex-max", "gpt-5.4-mini", "claude-sonnet-4-6"]
}

After set_model_tiers — saved tiers replace heuristics, classified models leave the list:

{
  "models": [
    {"name": "gpt-5.1-codex-max", "tier": "thorough"},
    {"name": "gpt-5.4-mini", "tier": "quick"},
    {"name": "claude-sonnet-4-6", "tier": "standard"}
  ],
  "unclassified_models": []
}

Global Environment Variables

Variable	Default	Description
`NEXUS_DB_PATH`	Platform per-user data directory	Durable SQLite job database; contains sensitive prompts and results
`NEXUS_OUTPUT_LIMIT_BYTES`	`50000`	Max output size in bytes before temp-file spillover
`NEXUS_TIMEOUT_SECONDS`	`600`	Subprocess timeout in seconds (10 minutes)
`NEXUS_TOOL_TIMEOUT_SECONDS`	`900`	Tool-level timeout in seconds (15 minutes); set to `0` to disable
`NEXUS_RETRY_MAX_ATTEMPTS`	`3`	Max attempts including the first (set to 1 to disable retries)
`NEXUS_RETRY_BASE_DELAY`	`2.0`	Base seconds for exponential backoff
`NEXUS_RETRY_MAX_DELAY`	`60.0`	Maximum seconds to wait between retries
`NEXUS_CLI_DETECTION_TIMEOUT`	`30`	Timeout in seconds for CLI binary version detection at startup
`NEXUS_EXECUTION_MODE`	`default`	Global execution mode (`default` or `yolo`)

Per-Runner Environment Variables

Pattern: NEXUS_{AGENT}_{KEY} (agent name uppercased). Per-runner values override global values.

Valid {AGENT} values: CLAUDE, CODEX, OPENCODE, OPENCODE_SERVER

Variable pattern	Example	Description
`NEXUS_{AGENT}_MODEL`	`NEXUS_CODEX_MODEL=gpt-5.2`	Default model for this runner
`NEXUS_{AGENT}_MODELS`	`NEXUS_CODEX_MODELS=gpt-5.2,gpt-5.4-mini`	Comma-separated model list (surfaced in server instructions)
`NEXUS_{AGENT}_TIMEOUT`	`NEXUS_CODEX_TIMEOUT=900`	Subprocess timeout override
`NEXUS_{AGENT}_OUTPUT_LIMIT`	`NEXUS_CODEX_OUTPUT_LIMIT=100000`	Output limit override
`NEXUS_{AGENT}_MAX_RETRIES`	`NEXUS_CLAUDE_MAX_RETRIES=5`	Max retry attempts override
`NEXUS_{AGENT}_RETRY_BASE_DELAY`	`NEXUS_CLAUDE_RETRY_BASE_DELAY=1.0`	Backoff base delay override
`NEXUS_{AGENT}_RETRY_MAX_DELAY`	`NEXUS_OPENCODE_RETRY_MAX_DELAY=30.0`	Backoff max delay override
`NEXUS_{AGENT}_EXECUTION_MODE`	`NEXUS_CODEX_EXECUTION_MODE=yolo`	Execution mode override

Invalid per-runner values are silently ignored (the global or hardcoded default is used instead).

Testing

This project follows Test-Driven Development (TDD) with strict Red→Green→Refactor cycles.

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=nexus_mcp --cov-report=term-missing

# Run specific test types
uv run pytest -m integration           # Integration tests (requires CLIs)
uv run pytest -m "not integration"     # Unit tests only
uv run pytest -m "not slow"            # Skip slow tests

# Run specific test file
uv run pytest tests/unit/runners/test_codex.py

Test markers:

@pytest.mark.integration — requires real CLI installations
@pytest.mark.slow — tests taking >1 second

Code Quality

All quality checks run automatically via pre-commit hooks. Run manually:

# Lint and format
uv run ruff check .              # Check for issues
uv run ruff check --fix .        # Auto-fix issues
uv run ruff format .             # Format code

# Type checking (strict mode)
uv run mypy src/nexus_mcp

# Run all pre-commit hooks manually
uv run pre-commit run --all-files

Adding Dependencies

uv add <package>              # Production dependency
uv add --dev <package>        # Development dependency
uv sync                       # Sync environment after changes

Tool Configuration

Ruff: line length 100, 17 rule sets (E/F/I/W + UP/FA/B/C4/SIM/RET/ICN/TID/TC/ISC/PTH/TD/NPY) — pyproject.toml → [tool.ruff]
Mypy: strict mode, all type annotations required — pyproject.toml → [tool.mypy]
Pytest: asyncio_mode = "auto", no @pytest.mark.asyncio needed — pyproject.toml → [tool.pytest.ini_options]
Pre-commit: ruff-check, ruff-format, mypy, trailing-whitespace, end-of-file-fixer — .pre-commit-config.yaml

Python 3.13+ Syntax

type keyword for type aliases: type AgentName = str
Union syntax: str | None (not Optional[str])
match statements for complex conditionals
NO from __future__ import annotations

Project Structure

nexus-mcp/
├── src/nexus_mcp/
│   ├── __main__.py          # Entry point
│   ├── core/                # Framework- and provider-independent domain contracts
│   ├── backends/            # Typed backend protocols and runtime registry
│   ├── jobs/                # Job service, worker, SQLite store, and migrations
│   ├── legacy/              # Temporary adapter over existing CLI runners
│   ├── mcp/                 # FastMCP transport adapter
│   │   ├── server.py        # Server, compatibility tools, and registration
│   │   ├── job_tools.py     # Typed durable agent_* tools
│   │   ├── runtime.py       # MCP lifespan ownership for job runtime services
│   │   └── prompts/         # Discoverable prompt templates
│   ├── server.py            # Compatibility re-export for the MCP server
│   ├── types.py             # Compatibility request and response models
│   ├── exceptions.py        # Exception hierarchy
│   ├── config.py            # Legacy environment configuration
│   ├── process.py           # Legacy subprocess wrapper
│   ├── parser.py            # Legacy JSON-to-text output parsing
│   ├── cli_detector.py      # CLI binary detection and version checks
│   └── runners/
│       ├── base.py          # Legacy runner protocol and template method
│       ├── factory.py       # RunnerFactory
│       ├── claude.py        # ClaudeRunner
│       ├── codex.py         # CodexRunner
│       ├── opencode.py      # OpenCodeRunner
│       └── opencode_server.py # OpenCode server runner
├── tests/
│   ├── unit/               # Fast, mocked tests
│   │   └── prompts/        # Prompt template tests
│   ├── e2e/                # End-to-end MCP protocol tests
│   ├── integration/        # Real CLI tests
│   └── fixtures.py         # Shared test utilities
├── .github/
│   └── workflows/          # CI, security, dependabot
├── pyproject.toml          # Dependencies + tool config
└── .pre-commit-config.yaml # Git hooks configuration

Releases

Stable releases are cut by running the Tag Release workflow from the Actions tab and choosing a bump (auto infers it from Conventional Commits since the last tag). Pre-releases are tagged manually. See RELEASE.md for the full maintainer workflow, recovery steps, and notes on server.json placeholder fields.

License

MIT

Available Tools

5 tools

batch_promptBatch Prompt CLI AgentsA

Destructive

Send multiple prompts to CLI runners in parallel (primary tool).

Fans out tasks server-side with asyncio.gather and a semaphore, enabling true parallel runner execution within a single MCP call. Single-task usage is perfectly valid — use prompt for convenience when sending one task.

ParametersJSON Schema

Name	Required	Description
`tasks`	Yes	List of AgentTask objects, each with cli, prompt, and optional fields.
`elicit`	No
`max_concurrency`	No	Max parallel runner invocations (default: 3).

Output Schema

ParametersJSON Schema

Name	Required	Description
`total`	Yes
`failed`	Yes
`results`	Yes
`succeeded`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds value beyond annotations by explaining the internal parallel execution mechanism ('asyncio.gather and a semaphore') and that it is a single MCP call. While annotations include destructiveHint=true, the description does not elaborate on destructiveness, but it does not contradict them. The added implementation detail justifies a 4.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with the primary purpose, followed by implementation detail and usage guidance. Every sentence is necessary and non-redundant, achieving maximum efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core behavior and differentiation from siblings. An output schema exists, so return format is assumed covered. However, it lacks details on error handling, partial failures, or the implications of destructiveHint, which would enhance completeness for a batch tool. Still, it is largely sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67%, and the input schema already provides detailed descriptions for all parameters. The tool description itself does not add additional meaning beyond stating the tool sends multiple prompts. With high schema coverage, a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool sends multiple prompts to CLI runners in parallel, using 'fans out tasks server-side' and explicitly distinguishes it from the sibling 'prompt' tool. The verb 'send' and resource 'multiple prompts' are specific, making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when to use this tool ('primary tool' for multiple prompts) and when to use the sibling 'prompt' ('convenience when sending one task'). It provides clear context and alternatives, leaving no ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

clear_preferencesClear Session PreferencesA

DestructiveIdempotent

Clear all persistent preferences, reverting to per-call defaults.

Returns: Confirmation string.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds behavioral context by explaining that it reverts to per-call defaults and returns a confirmation string, clarifying the meaning of 'destructive'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (two sentences), front-loaded with the purpose, and includes the return type. Every word is necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 0 parameters and annotations cover safety traits, the description is complete: it states what it clears, the effect, and the return value. No gaps for invoking correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0 parameters and 100% schema coverage (vacuously), the description adds no parameter information beyond the schema. Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Clear' and resource 'persistent preferences', and distinguishes it from siblings like 'set_preferences' by stating it reverts to per-call defaults.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'set_preferences'. It lacks context about prerequisites or appropriate scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

promptPrompt CLI AgentA

Destructive

Send a prompt to a CLI runner as a background task.

Returns immediately with a task ID. Client polls for results. This prevents timeouts for long operations (YOLO mode: 2-5 minutes).

ParametersJSON Schema

Name	Required	Description
`cli`	No	CLI runner name (e.g., "codex"). None triggers interactive selection.
`model`	No	Model name. None triggers interactive selection or uses CLI default.
`elicit`	No
`prompt`	Yes	Prompt text to send to the runner
`context`	No	Optional context metadata
`timeout`	No	Subprocess timeout seconds (None inherits session preference or uses env default).
`max_retries`	No	Max retry attempts for transient errors (None inherits session preference).
`output_limit`	No	Max output bytes (None inherits session preference or uses env default).
`execution_mode`	No	'default' (safe) or 'yolo'. None inherits session preference.
`retry_max_delay`	No	Backoff ceiling in seconds (None inherits session preference or config).
`retry_base_delay`	No	Base delay seconds for exponential backoff (None inherits session/config).

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true, but the description adds valuable behavioral details: returns immediately with task ID, client polls, prevents timeouts, and specifies YOLO mode duration. This exceeds annotation-only info.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no wasted words. Front-loaded with core action, followed by async behavior and benefit. Highly concise and structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (11 parameters, async, destructive), the description covers the key workflow (async polling, timeout). Output schema exists, so return format is covered elsewhere. Missing minor details like polling mechanism, but sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 91% schema coverage, the description adds minimal parameter detail beyond the schema. It mentions YOLO mode and timeout but does not explain individual parameters further. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it sends a prompt to a CLI runner as a background task, returns immediately with a task ID, and prevents timeouts. This distinguishes it from siblings like batch_prompt (batch) and preference tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the async nature and timeout prevention, providing clear context for use. However, it does not explicitly contrast with sibling tools like batch_prompt or state when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_model_tiersSet Model TiersA

Idempotent

Save model tier classifications.

Client sends sampling/benchmark results; server persists to backing store. Overwrites any previously saved tiers entirely.

ParametersJSON Schema

Name	Required	Description	Default
`tiers`	Yes	Mapping of model name to tier ('quick', 'standard', 'thorough').

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explicitly states it overwrites previously saved tiers entirely, adding behavioral context beyond annotations. Annotations already indicate idempotence, but the description clarifies the overwriting behavior. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three efficient sentences: first states purpose, second explains process, third details effect. No wasted words, and critical information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter, full schema coverage, and an output schema. The description covers the key behavior (overwrite) and is complete for this complexity level, though it omits error handling details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already describes the tiers parameter as a mapping to allowed tier values. The description adds no further meaning, so baseline score is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool saves model tier classifications, using a specific verb (Save) and resource (model tier classifications). It distinguishes from sibling tools like prompt and set_preferences, which deal with prompts and preferences.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use vs. alternatives. The context implies it is for persisting model tiers after sampling/benchmarks, but lacks explicit when-not-to-use or comparison with siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_preferencesSet Session PreferencesA

Idempotent

Set persistent preferences that apply to subsequent prompt/batch_prompt calls.

Preferences persist across MCP sessions. Call again to update, or use clear_preferences to reset all fields at once.

To clear a single field while keeping others, pass the corresponding clear_* flag: set_preferences(clear_model=True) # clears model, keeps execution_mode

ParametersJSON Schema

Name	Required	Description
`model`	No	Default model name (e.g. 'gpt-5.2'). None retains the current value (use clear_model=True to reset).
`elicit`	No
`timeout`	No	Default subprocess timeout in seconds. None retains the current value (use clear_timeout=True to reset).
`clear_model`	No	If True, resets model to None regardless of the model argument.
`max_retries`	No	Default max retry attempts for transient errors. None retains the current value (use clear_max_retries=True to reset).
`clear_elicit`	No
`confirm_yolo`	No
`output_limit`	No	Default max output bytes per response. None retains the current value (use clear_output_limit=True to reset).
`clear_timeout`	No	If True, resets timeout to None regardless of the argument.
`execution_mode`	No	Default execution mode ('default' or 'yolo'). None retains the current value (use clear_execution_mode=True to reset).
`retry_max_delay`	No	Default max delay cap seconds for exponential backoff. None retains the current value (use clear_retry_max_delay=True to reset).
`retry_base_delay`	No	Default base delay seconds for exponential backoff. None retains the current value (use clear_retry_base_delay=True to reset).
`clear_max_retries`	No	If True, resets max_retries to None regardless of the argument.
`clear_confirm_yolo`	No
`clear_output_limit`	No	If True, resets output_limit to None regardless of the argument.
`confirm_large_batch`	No
`clear_execution_mode`	No	If True, resets execution_mode to None regardless of the execution_mode argument.
`confirm_high_retries`	No
`confirm_vague_prompt`	No
`clear_retry_max_delay`	No	If True, resets retry_max_delay to None.
`clear_retry_base_delay`	No	If True, resets retry_base_delay to None.
`clear_confirm_large_batch`	No
`clear_confirm_high_retries`	No
`clear_confirm_vague_prompt`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate idempotency ('idempotentHint': true) and non-destructiveness. The description adds value by explaining persistence across sessions and the update semantics. No contradictions found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with three concise paragraphs: purpose, persistence, and example usage. No unnecessary words, every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 24 parameters (none required) and an output schema, the description covers the key behavioral aspects: persistence, update, clearing, and relation to sibling tools. The output schema handles return values, so no further detail needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 58% with descriptions for most fields. The description explains the overall pattern of using 'None' to retain values and 'clear_*' flags to reset, which adds context beyond individual parameter descriptions but does not detail every parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Set'), resource ('persistent preferences'), and scope ('apply to subsequent prompt/batch_prompt calls'). It effectively distinguishes from sibling tool 'clear_preferences' by mentioning its specific function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use (set preferences for future calls), persistence across sessions, update behavior, and how to clear fields individually using 'clear_*' flags. Also names 'clear_preferences' as alternative for resetting all fields.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

5 tool updatesv1.0.0May 30, 2026

Changedbatch_prompt9 fields changed

addedInput schema / properties / elicit

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / max_concurrency / description

Added value: +"Max parallel runner invocations (default: 3)."

addedInput schema / properties / tasks / description

Added value: +"List of AgentTask objects, each with cli, prompt, and optional fields."

addedInput schema / properties / tasks / items / properties / cli / anyOf

Added value: +[
+  {
+    "minLength": 1,
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / tasks / items / properties / cli / default
```
Added value: +null
```

changedInput schema / properties / tasks / items / properties / cli / enum

Previous value: -[
-  "claude",
-  "codex",
-  "gemini",
-  "opencode"
-]New value: +[
+  "claude",
+  "codex",
+  "opencode",
+  "opencode_server"
+]

removedInput schema / properties / tasks / items / properties / cli / minLength
```
Removed value: -1
```
removedInput schema / properties / tasks / items / properties / cli / type
```
Removed value: -"string"
```

changedInput schema / properties / tasks / items / required

Previous value: -[
-  "cli",
-  "prompt"
-]New value: +[
+  "prompt"
+]

Removedget_preferences

Changedprompt16 fields changed

addedInput schema / properties / cli / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / cli / default
```
Added value: +null
```

addedInput schema / properties / cli / description

Added value: +"CLI runner name (e.g., \"codex\"). None triggers interactive selection."

changedInput schema / properties / cli / enum

Previous value: -[
-  "claude",
-  "codex",
-  "gemini",
-  "opencode"
-]New value: +[
+  "claude",
+  "codex",
+  "opencode",
+  "opencode_server"
+]

removedInput schema / properties / cli / type
```
Removed value: -"string"
```
addedInput schema / properties / context / description
```
Added value: +"Optional context metadata"
```

addedInput schema / properties / elicit

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / execution_mode / description

Added value: +"'default' (safe) or 'yolo'. None inherits session preference."

addedInput schema / properties / max_retries / description

Added value: +"Max retry attempts for transient errors (None inherits session preference)."

addedInput schema / properties / model / description

Added value: +"Model name. None triggers interactive selection or uses CLI default."

addedInput schema / properties / output_limit / description

Added value: +"Max output bytes (None inherits session preference or uses env default)."

addedInput schema / properties / prompt / description
```
Added value: +"Prompt text to send to the runner"
```

addedInput schema / properties / retry_base_delay / description

Added value: +"Base delay seconds for exponential backoff (None inherits session/config)."

addedInput schema / properties / retry_max_delay / description

Added value: +"Backoff ceiling in seconds (None inherits session preference or config)."

addedInput schema / properties / timeout / description

Added value: +"Subprocess timeout seconds (None inherits session preference or uses env default)."

changedInput schema / required

Previous value: -[
-  "cli",
-  "prompt"
-]New value: +[
+  "prompt"
+]

Addedset_model_tiers

Changedset_preferences24 fields changed

addedInput schema / properties / clear_confirm_high_retries

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedInput schema / properties / clear_confirm_large_batch

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedInput schema / properties / clear_confirm_vague_prompt

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedInput schema / properties / clear_confirm_yolo

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedInput schema / properties / clear_elicit

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedInput schema / properties / clear_execution_mode / description

Added value: +"If True, resets execution_mode to None regardless of the\nexecution_mode argument."

addedInput schema / properties / clear_max_retries / description

Added value: +"If True, resets max_retries to None regardless of the argument."

addedInput schema / properties / clear_model / description

Added value: +"If True, resets model to None regardless of the model argument."

addedInput schema / properties / clear_output_limit / description

Added value: +"If True, resets output_limit to None regardless of the argument."

addedInput schema / properties / clear_retry_base_delay / description
```
Added value: +"If True, resets retry_base_delay to None."
```
addedInput schema / properties / clear_retry_max_delay / description
```
Added value: +"If True, resets retry_max_delay to None."
```

addedInput schema / properties / clear_timeout / description

Added value: +"If True, resets timeout to None regardless of the argument."

addedInput schema / properties / confirm_high_retries

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / confirm_large_batch

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / confirm_vague_prompt

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / confirm_yolo

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / elicit

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / execution_mode / description

Added value: +"Default execution mode ('default' or 'yolo').\nNone retains the current value (use clear_execution_mode=True to reset)."

addedInput schema / properties / max_retries / description

Added value: +"Default max retry attempts for transient errors.\nNone retains the current value (use clear_max_retries=True to reset)."

addedInput schema / properties / model / description

Added value: +"Default model name (e.g. 'gpt-5.2').\nNone retains the current value (use clear_model=True to reset)."

addedInput schema / properties / output_limit / description

Added value: +"Default max output bytes per response.\nNone retains the current value (use clear_output_limit=True to reset)."

addedInput schema / properties / retry_base_delay / description

Added value: +"Default base delay seconds for exponential backoff.\nNone retains the current value (use clear_retry_base_delay=True to reset)."

addedInput schema / properties / retry_max_delay / description

Added value: +"Default max delay cap seconds for exponential backoff.\nNone retains the current value (use clear_retry_max_delay=True to reset)."

addedInput schema / properties / timeout / description

Added value: +"Default subprocess timeout in seconds.\nNone retains the current value (use clear_timeout=True to reset)."

5 tool updatesv0.8.1Mar 22, 2026
- First observedbatch_prompt
- First observedclear_preferences
- First observedget_preferences
- First observedprompt
- First observedset_preferences

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-05-30 09:06 across 5 tools

Disambiguation4/5

Most tools are clearly distinct: set/clear preferences and set_model_tiers are separate concerns. However, prompt and batch_prompt both handle sending prompts to CLI runners, which could cause confusion despite descriptions clarifying batch_prompt for parallel tasks.

Naming Consistency5/5

All tool names use consistent snake_case and follow a verb_noun pattern (e.g., clear_preferences, set_preferences). 'prompt' is a slight exception as a noun, but it's a clear and conventional name.

Tool Count5/5

Five tools cover the core functionality of sending prompts, managing preferences, and setting model tiers without unnecessary complexity. The count is appropriate for the server's purpose.

Completeness3/5

Missing a tool to retrieve current preferences or task results within MCP. The prompt tool returns a task ID but expects client-side polling, leaving a gap in the tool surface.

Maintenance

ActivityActive

ResponsivenessResponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

toolweaveOAuth
io.github.andreysparish
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
App Automation AI & Machine Learning Agent Orchestration
2
strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
RogerRat A
io.github.opcastil11
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Communication Agent Orchestration
21

Related MCP Servers

MCP-Ables
Shell Access Command Line Developer Tools
mfakbar127
F
license
Not graded
quality
D
maintenance
Turns any shell command into an MCP server by defining command-line tools in simple YAML files. Enables AI agents to execute system commands, security scanners, DevOps tools, and CLI utilities directly from chat interfaces.
Updated a year ago (2025-10-12 17:16 UTC)
4
-
mcp-cli-catalog
Shell Access
abcpro1
A
license
Not graded
quality
D
maintenance
An MCP server that publishes CLI tools on your machine for discoverability by LLMs
Updated 10 months ago (2025-11-16 20:50 UTC)
7 npm
1
MIT
consult-mcp
Agent Orchestration Autonomous Agents AI & Machine Learning
oblogin
A
license
A
quality
D
maintenance
MCP server orchestrating local CLI agents (Claude Code, OpenAI Codex, Google Gemini) for cross-validation, second opinions, and persona-driven prompting.
Updated 4 months ago (2026-05-03 17:38 UTC)
18
MIT
wrapmcp
Shell Access Command Line
SubZtep
A
license
Not graded
quality
C
maintenance
Universal MCP server that wraps any CLI tool, enabling AI assistants to run commands via natural language.
Updated 3 months ago (2026-06-08 02:02 UTC)
MIT

Nexus MCP

Use Cases

Features

Installation

Run with uvx (recommended)

Usage

Fan out a research question (batch_prompt)

Code review from multiple angles (batch_prompt)

Single-agent prompt

Elicitation (server picks the runner)

Persistent preferences

MCP Tools

batch_prompt

prompt

set_preferences

get_preferences / clear_preferences

set_model_tiers

get_model_tiers

Managing Preferences

Durable Job Architecture

MCP Prompts

MCP Resources

Global Environment Variables

Per-Runner Environment Variables

Testing

Code Quality

Adding Dependencies

Tool Configuration

Python 3.13+ Syntax

Project Structure

Releases

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

`batch_prompt`

`prompt`

`set_preferences`

`get_preferences` / `clear_preferences`

`set_model_tiers`

`get_model_tiers`