Skip to main content
Glama

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 Node.js MCP TypeScript


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: Second Opinion MCP

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.

Available Tools

15 tools
nexus_agent_multiA

Run multiple autonomous AI agents IN PARALLEL, each with its own model and task. Each agent independently reads files, writes code, and executes commands. Perfect for divide-and-conquer tasks: one agent codes while another tests, or multiple agents each tackle a different part of a large codebase. All agents run simultaneously and results are returned together.

Inputs: agents (required).

nexus_agent_runA

Run an autonomous AI agent that can read files, write code, execute shell commands, search the web, and iterate until the task is complete. The agent uses the specified model (GPT-5.4, Nemotron, Gemini, etc.) and works independently through a ReAct loop. Returns the final answer plus a full trace of every action taken.

Inputs: task (required), model (required), provider (required), role, +7 more.

nexus_askB

Send a prompt to any AI provider (ChatGPT, Gemini, Claude, Ollama, etc.). Uses the active provider/model by default, or specify a different one.

Inputs: prompt (required), model, provider, maxTokens, +2 more.

nexus_configureB

Configure a provider directly from chat — set API keys, base URLs, enable/disable providers. For full management, use the web dashboard.

Inputs: provider (required), apiKey, baseUrl, enabled, +1 more.

nexus_councilA

Convene a multi-model council where AI agents deliberate in rounds and Opus makes the final decision. DISCUSSION: Models build on each other collaboratively. DEBATE: Models challenge each other adversarially. RESEARCH: Models investigate with tools (file read, web search) and cross-reference findings. All participants respond in parallel each round, seeing all prior contributions. Use this for architecture decisions, code reviews, security audits, complex analysis.

Inputs: topic (required), participants (required), mode, rounds, +1 more.

nexus_list_modelsA

List all available AI providers and their models, with status indicators. Optionally filter by a specific provider.

Inputs: provider.

nexus_plan_executeA

Execute a structured multi-step plan where Claude is the orchestrator and Nexus agents do the work. Independent steps run IN PARALLEL. Dependent steps wait and receive context from prior steps. Use mode="agent" for steps that need file access/code execution. Use mode="prompt" for analysis/review steps. Opus plans, Nexus executes.

Inputs: steps (required), title, context, max_total_time_ms.

nexus_plan_statusB

Check the status of a previously executed plan. Returns per-step results and metadata.

Inputs: plan_id.

nexus_reauthA

Open a browser window for re-authentication with a provider. Log into your account, then close the browser. Your session will be saved for future use. Supported providers: openai, gemini, anthropic, perplexity, mistral, cohere, huggingface, deepseek, groq

Inputs: provider (required), url.

nexus_statusB

Health check all configured AI providers. Shows connection status, latency, and any errors.

Inputs: provider.

nexus_subagent_collabA

Multi-model collaboration pipeline. Models work sequentially: first model produces output, next reviews/refines, optional final model synthesizes. Returns final output plus all intermediate steps showing each model's contribution.

Inputs: task (required), models (required).

nexus_subagent_runA

Execute all tasks in a spawned batch in parallel. Waits for all to complete. Returns results from every model with metadata (text, latency, tokens, errors).

Inputs: batchId (required).

nexus_subagent_spawnA

Spawn one or more AI subagent tasks for parallel execution. Each task targets a specific provider/model with its own prompt. Returns a batch ID — use nexus_subagent_run to execute.

Inputs: tasks (required), timeoutMs.

nexus_subagent_statusB

Check status of subagent batches. Shows pending, running, or completed batches with results. Omit batchId to list all recent batches.

Inputs: batchId.

nexus_switch_modelA

Switch the active AI provider and model. After switching, all subsequent nexus_ask calls will use the new provider/model.

Inputs: model (required), provider (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 15 tools

    Disambiguation3/5

    The provider-management tools are clearly distinct, but the orchestration family overlaps: nexus_subagent_spawn/run, nexus_agent_run/multi, nexus_subagent_collab, and nexus_council all involve dispatching model tasks, and the boundaries between subagent, agent, and council workflows are not immediately obvious. The descriptions clarify the different interaction patterns enough to be usable, but an agent could still misselect among them.

    Naming Consistency3/5

    All tools share the nexus_ prefix and snake_case, but the convention is inconsistent: list_models, switch_model, and reauth use verb-led names, while subagent_spawn, subagent_collab, agent_multi, and council use noun-led or noun-only names. The prefix helps recognition, but an agent cannot reliably predict a tool name from its function.

    Tool Count4/5

    At 15 tools, this sits at the upper edge of the ideal range but is justifiable for a multi-provider orchestration server covering provider configuration, simple prompts, subagents, autonomous agents, plans, and councils. A few orchestration modes could potentially be consolidated, but the count is not bloated.

    Completeness4/5

    The surface covers provider health, authentication, configuration, model listing/switching, prompt execution, subagent batches, autonomous agents, plans, and councils, with status/result retrieval for the async workflows. The main gap is the lack of any cancel/abort tool for long-running agents, batches, or councils, which is a notable but non-fatal omission.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers