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

Related MCP server: Agent Communication MCP Server

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

Subagents — Parallel Text Tasks

Agents — Autonomous Execution

Orchestration — Complex Work

Supported Providers (27 Total)

Cloud Providers (22)

Local Providers (5)

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

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

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.