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.