Nexus MCP

Nexus MCP

The Universal AI Gateway for Claude — Delegate tasks to 27 AI providers. Orchestrate multi-agent plans. Run councils for decisions. All from a single MCP server.

   

---

What is Nexus MCP?

Nexus MCP is a Model Context Protocol (MCP) server that turns Claude into an orchestration engine for multi-AI systems. Instead of Claude doing everything, Nexus agents execute tasks while Claude plans, decides, monitors, and intervenes.

Paradigm: Opus Plans, Nexus Executes

• Claude/Opus: Strategic thinking, planning, final decisions
• Nexus agents: Autonomous execution, research, reasoning, tool use, code generation
• 27 AI providers: GPT-5.4, Gemini, Nemotron, Claude, Ollama, local models, and more

Key Features

• 27 Providers: 22 cloud (OpenAI, Google Gemini, Anthropic, Mistral, Cohere, Groq, Together, Perplexity, DeepSeek, xAI, HuggingFace, Replicate, Nvidia, etc.) + 5 local (Ollama, LM Studio, llama.cpp, LocalAI, vLLM)
• 15 MCP Tools: Quick asks, subagents, autonomous agents, plan execution, multi-agent councils
• 3 Orchestration Modes:
• Agents: Autonomous execution with file/bash/web tools (ReAct loop)
• Plans: Structured DAG workflows with dependencies and context injection
• Councils: Multi-model deliberation (discussion/debate/research modes)
• 3 Auth Modes: API Key, Browser Session (Playwright), No Auth (local models)
• Web Dashboard: Visual config at http://localhost:9777 — no JSON editing
• Multi-Round Deliberation: Agents see each other's outputs. Opus makes final decision
• Zero AI SDKs: All providers via raw fetch() — minimal dependencies
• Browser Auth: Log in via Chromium — no API keys needed

---

Quick Start

1. Install

git clone https://github.com/your-username/nexus-mcp.git
cd nexus-mcp
npm install
npx playwright install chromium

2. Build & Run

npm run build    # Compile TypeScript
npm start        # Run the server

Or for development:

npm run dev      # Run with tsx (hot reload)

3. Add to Claude Desktop

Edit your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "nexus": {
      "command": "node",
      "args": ["C:/path/to/nexus-mcp/dist/index.js"]
    }
  }
}

Restart Claude Desktop. You should see Nexus tools in the MCP tool list.

4. Add to Claude Code

claude mcp add nexus -- node /path/to/nexus-mcp/dist/index.js

5. Configure

Open http://localhost:9777 in your browser to:

• Enable providers
• Add API keys
• Switch models
• Set up browser auth

Or configure from chat: `` Use nexus_configure to set up OpenAI with API key sk-... Use nexus_switch_model to switch to openai / gpt-4o Use nexus_ask to ask: What is the meaning of life? ``

---

MCP Tools (15 Total)

Core Tools

| Tool | Description | |------|-------------| | nexus_ask | Ask any provider/model a question — quick opinions | | nexus_switch_model | Change active provider and model | | nexus_list_models | List all 27 providers and 217+ models | | nexus_status | Health check all providers | | nexus_configure | Add/update API keys and settings from chat | | nexus_reauth | Re-authenticate OAuth providers |

Subagents — Parallel Text Tasks

| Tool | Description | |------|-------------| | nexus_subagent_spawn | Create batch of parallel text-only tasks | | nexus_subagent_run | Run subagents and collect results | | nexus_subagent_collab | Chain models: A drafts → B reviews → C synthesizes | | nexus_subagent_status | Check batch/task status |

Agents — Autonomous Execution

| Tool | Description | |------|-------------| | nexus_agent_run | Run single agent with file/bash/web tools (ReAct loop) | | nexus_agent_multi | Run multiple agents in parallel with tools |

Orchestration — Complex Work

| Tool | Description | |------|-------------| | nexus_plan_execute | DAG plan executor — steps with dependencies, parallel execution | | nexus_plan_status | Check plan status by ID | | nexus_council | Multi-model council — discussion/debate/research modes, multi-round |

---

Supported Providers (27 Total)

Cloud Providers (22)

| Provider | Auth Modes | Key Models | |----------|-----------|------------| | OpenAI | API Key, OAuth | gpt-4o, gpt-5.4, o1, o3-mini | | Google Gemini | API Key, OAuth | gemini-2.0-flash, gemini-2.0-pro | | Anthropic | API Key | claude-opus-4-6, claude-sonnet-4-6 | | Nvidia | API Key (free) | Nemotron-120B, NV-Embed | | Mistral | API Key | mistral-large, codestral | | Cohere | API Key | command-r-plus, command-r | | Groq | API Key | Llama-3.3-70B, Mixtral-8x7B | | Together AI | API Key | Llama-3.3-70B, Qwen2.5-72B | | Perplexity | API Key | sonar-pro, sonar-reasoning | | DeepSeek | API Key | deepseek-chat, deepseek-reasoner | | xAI (Grok) | API Key | grok-2, grok-2-mini | | HuggingFace | API Key | Llama-3.3-70B, Mixtral-8x7B | | Replicate | API Key | 100+ open-source models | | OpenRouter | API Key | Multi-provider routing | | Fireworks | API Key | Fast inference | | DeepInfra | API Key | 100+ models, cheap | | Cerebras | API Key | Fast inference | | SambaNova | API Key | CoE architecture | | Abacus.AI | API Key | Custom models | | AI21 Labs | API Key | Jurassic models | | OpenCode Zen | API Key | Custom gateway | | Custom | API Key, OAuth | Any OpenAI-compatible endpoint |

Local Providers (5)

| Provider | Default Port | Notes | |----------|-------------|-------| | Ollama | 11434 | Auto-discovers installed models | | LM Studio | 1234 | OpenAI-compatible API | | llama.cpp | 8080 | OpenAI-compatible API | | LocalAI | 8080 | OpenAI-compatible API | | vLLM | 8000 | OpenAI-compatible API |

---

Browser Authentication

For providers that support it, you can use your existing browser login instead of an API key:

1. Use nexus_reauth tool or click the 🔑 button in the dashboard
2. A Chromium browser window opens at the provider's login page
3. Log in normally
4. Close the browser — your session is saved
5. Future requests use the saved session (headless)

Sessions are stored at ~/.nexus/sessions/.

---

Architecture

Claude Desktop/Code
    │
    ├──stdio──> Nexus MCP Server
    │              ├─ MCP Handler (15 tools)
    │              ├─ Orchestrator
    │              │   ├─ Agent Executor (ReAct loop, tools)
    │              │   ├─ Plan Executor (DAG scheduler, dependency injection)
    │              │   ├─ Council Manager (multi-round deliberation)
    │              │   └─ Subagent Manager (parallel text tasks)
    │              ├─ Provider Router (27 providers, auto-failover)
    │              ├─ Auth Manager (API Key, OAuth PKCE, Sessions)
    │              └─ Web Dashboard (:9777)
    │
    ├──http──> Dashboard UI (http://localhost:9777)
    │
    └──APIs──> 27 AI Providers
                 ├─ 22 Cloud APIs
                 └─ 5 Local Servers

Single Node.js process. Stdio for MCP (Claude communication), HTTP for dashboard UI, outbound to provider APIs. Config at ~/.nexus/config.json.

---

The Paradigm: Opus Plans, Nexus Executes

Claude/Opus is the strategic brain. It never executes directly. Instead:

1. Claude plans — Structure complex work as DAGs, orchestrate decisions via councils
2. Nexus agents execute — Autonomous execution with tools (file read/write, bash, web search)
3. Claude reviews & decides — Monitor all outputs, intervene when needed, make final calls

When to Use Each Tool

| Scenario | Tool | Why | |----------|------|-----| | Quick question | nexus_ask | Get instant opinion from any model | | Parallel research | nexus_subagent_run | 5 agents researching in parallel | | Code/file work | nexus_agent_run | Agent with tools (read, write, bash) | | Multi-step project | nexus_plan_execute | DAG with dependencies, parallel execution | | Architecture choice | nexus_council (debate) | Models challenge each other, Opus decides | | Security audit | nexus_council (research) | Agents investigate with tools |

Plan Example

A three-step code generation project:

{
  title: "Add JWT Auth",
  steps: [
    {
      id: "analyze",
      mode: "agent",
      description: "Read codebase and find auth patterns"
    },
    {
      id: "code",
      depends_on: ["analyze"],
      inject_context_from: ["analyze"],
      mode: "agent",
      description: "Generate JWT implementation"
    },
    {
      id: "test",
      depends_on: ["code"],
      inject_context_from: ["code"],
      mode: "agent",
      description: "Write and run tests"
    }
  ]
}

Step code automatically sees step analyze's output. Steps run in parallel where possible.

---

Configuration

All configuration is managed through the web dashboard or MCP tools. The config file is at ~/.nexus/config.json but you should never need to edit it manually.

Environment Variables

| Variable | Description | |----------|-------------| | NEXUS_DEBUG | Set to any value to enable debug logging |

---

Development

npm run dev          # Run with tsx
npm run build        # Compile TypeScript
npm run typecheck    # Type check without emitting

---

Architecture Deep Dive

Core Subsystems

• Agent Executor (src/agent/executor.ts) — ReAct loop with OpenAI function-calling format. Agents can read/write files, run bash, search web.
• Plan Executor (src/orchestrator/plan-executor.ts) — DAG scheduler using topological sort (Kahn's algorithm). Detects cycles, runs steps in parallel, injects context from dependencies.
• Council Manager (src/orchestrator/council.ts) — Multi-round deliberation. Three modes:
• Discussion — Models collaborate
• Debate — Models challenge each other
• Research — Agents investigate with tools
• Provider Router (src/providers/router.ts) — Failover logic. If one provider is down, auto-switches to next available.
• Auth Manager (src/auth/) — API keys, OAuth PKCE (Chromium browser), session storage.
• Web Dashboard (src/web/server.ts) — Visual config UI at port 9777.

File Structure

src/
├── index.ts                    # Entry point
├── mcp-server.ts               # MCP tool handlers
├── agent/
│   ├── executor.ts             # ReAct agent loop
│   ├── sandbox.ts              # Tool execution sandbox
│   └── tools.ts                # File/bash/web/search tools
├── orchestrator/
│   ├── plan-executor.ts        # DAG scheduler
│   ├── plan-types.ts           # PlanStep, PlanRecord interfaces
│   ├── council.ts              # Multi-agent councils
│   └── council-types.ts        # Council interfaces
├── providers/                  # 27 provider adapters
│   ├── router.ts               # Main routing logic
│   ├── registry.ts             # Provider registration
│   ├── cloud/                  # OpenAI, Gemini, Anthropic, etc.
│   └── local/                  # Ollama, LM Studio, etc.
├── auth/                       # Authentication strategies
├── config/                     # Config schema & defaults
├── tools/                      # 15 MCP tool definitions
├── utils/                      # Logging, errors, HTTP
└── web/                        # Dashboard frontend + server

dist/                           # Compiled JS (after npm run build)

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes
4. Run tests and type-check (npm run typecheck)
5. Submit a pull request

Adding a New Provider

1. Create a new file in src/providers/cloud/ or src/providers/local/
2. Implement the ProviderAdapter interface (or extend OpenAICompatibleProvider)
3. Register it in src/providers/registry.ts
4. Add default config in src/config/defaults.ts
5. Type-check and test with other providers

Adding a New MCP Tool

1. Create a new file in src/tools/my-tool.ts
2. Export a function matching the tool interface
3. Add to ALL_TOOLS in src/mcp-server.ts
4. Add the switch case handler

---

License

MIT License. See LICENSE for details.