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:

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

2. Start the server:

   docker compose up -d
   

3. Authenticate with your provider:

   docker exec -it opencode-server opencode auth login
   

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

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.

batch_prompt

Task object fields:

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

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

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.

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

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

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

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