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

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org)

---

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

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

### 2. Build & Run

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

Or for development:

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

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

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

```typescript
{
  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

```bash
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](LICENSE) for details.