Nexus Mcp

Nexus MCP

[](https://pypi.org/project/nexus-mcp/) [](https://www.python.org) [](https://opensource.org/licenses/MIT) [](https://github.com/astral-sh/ruff) [](https://mypy-lang.org/) [](https://pre-commit.com/) [](https://modelcontextprotocol.io/)

An MCP server that enables AI models to invoke AI CLI agents (Codex, Claude Code, OpenCode) as tools. Provides parallel execution, automatic retries with exponential backoff, JSON-first response parsing, 10 discoverable prompt templates, model tier classification, and persistent preferences through seven MCP tools, four MCP resources, and ten MCP 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

Features

• Parallel execution — batch_prompt fans out tasks with asyncio.gather and a configurable

semaphore (default concurrency: 3)

• 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

MCP Client Configuration

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](#configuration) for the full list.

Setup for Development

Prerequisites:

• Python 3.13+ (download)
• uv dependency manager (install guide)

``bash 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 
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

OpenCode Server (Docker) — experimental

> ⚠️ 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:

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

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

1. Start the server:

``bash docker compose up -d ``

1. Authenticate with your provider:

``bash docker exec -it opencode-server opencode auth login ``

1. Verify the server is healthy:

``bash 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](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.

Usage Examples

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", "label": "codex-security-review" },
    { "cli": "claude", "prompt": "Review this diff for correctness and edge cases:\n\n", "label": "claude-correctness-review" },
    { "cli": "opencode", "prompt": "Review this diff for style and maintainability:\n\n", "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

All prompt tools run as background tasks — they return a task ID immediately so the client can poll for results, preventing MCP timeouts for long operations (e.g. YOLO mode: 2–5 minutes).

| 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 |

Tool API Reference

batch_prompt

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | tasks | Yes | — | List of task objects (see below) | | max_concurrency | No | 3 | Max parallel agent invocations | | 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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: j7an
• Source: j7an/nexus-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.