Nexus 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

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

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

{
  "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"
      }
    }
  }
}

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

{
  "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"
  }
}

# 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

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.

{
  "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" }
  ]
}

{
  "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" }
  ]
}

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

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

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

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.

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.

Managing Preferences

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.

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

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.

{
  "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"]
}

{
  "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": []
}

# 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

# 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

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

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