NEXUS MCP Agent

Agentic OS — Zero required API keys for core startup, optional tokens unlock private GitHub and external services.

An autonomous AI agent MCP server with 151 tools for advanced reasoning, multi-agent orchestration, persistent memory, filesystem, git, workflows, security scanning, GitHub integration, and more.

Quick Start

Via npx (recommended)

Add to your MCP client configuration:

{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["-y", "nexus-mcp-agent"],
      "env": {}
    }
  }
}

Global install

npm install -g nexus-mcp-agent

Then in your MCP config:

{
  "mcpServers": {
    "nexus": {
      "command": "nexus",
      "env": {}
    }
  }
}

For browser automation (optional)

npm install -g playwright
npx playwright install chromium

Tools (151)

The authoritative live tool list is available through the nexus://tools resource.

🌐 Web (4 tools)

web_search, web_fetch, web_scrape, url_extract

📁 Filesystem (6 tools)

fs_read, fs_write, fs_list, fs_search, fs_delete, fs_info

💻 Terminal (2 tools)

cmd_execute, cmd_spawn (real streaming via spawn)

🔀 Git (10 tools)

git_status, git_log, git_diff, git_branches, git_commit, git_clone, git_push, git_pull, git_checkout, git_add

🧠 Memory — Basic (5 tools)

mem_store, mem_recall, mem_list, mem_delete, mem_stats

🧠 Memory — Advanced (14 tools)

Episodic (store complete experiences): memory_episodic_store, memory_episodic_recall, memory_episodic_stats

Semantic (vector search): memory_semantic_store, memory_semantic_search, memory_semantic_list

Procedural (reusable how-to knowledge): memory_procedural_save, memory_procedural_find, memory_procedural_execute, memory_procedural_list

Knowledge Graph (entities and relationships): memory_kg_add_entity, memory_kg_add_relation, memory_kg_query, memory_kg_stats

🧠 Reasoning (5 tools)

reason_tot (Tree-of-Thought: explore multiple reasoning paths) reason_react (ReAct Loop: Think → Act → Observe) reason_plan (Plan-and-Execute: decompose and execute complex goals) reason_reflect (Reflection: analyze failures and generate corrections) reason_reflect_single (Quick correction for a single failure)

🤖 Multi-Agent Orchestration (5 tools)

agent_route (Route tasks to specialized agents) agent_pipeline (Sequential agent execution) agent_parallel (Concurrent agent execution) agent_fanout (Decompose + parallel execution) agent_hierarchical (Manager-worker delegation)

🎭 Agents (8 tools)

agent_catalog, agent_search, agent_load, agent_domains, agent_create, agent_delegate, agent_list, agent_delete

⚙️ System (4 tools)

sys_info, sys_env, sys_health, sys_echo

🛠️ Dev Intelligence (20 tools)

Workflows: workflow_create, workflow_execute, workflow_step_done, workflow_status, workflow_list Tasks: task_start, task_checkpoint, task_restore, task_list Skills: skill_save, skill_search, skill_load, skill_list Chains: chain_create, chain_execute, chain_step_done, chain_status, chain_list Review: review_code

📊 Intelligence (6 tools)

status, status_loop_check, status_summarize, status_history, context_save, context_restore

💾 Session (3 tools)

session_save, session_restore, session_list

📐 Project (3 tools)

project_analyze, project_scan, project_suggest

🐙 GitHub (4 tools)

github_issues, github_pr, github_search, github_content (Set GITHUB_TOKEN env var for private repos)

🔒 Security (3 tools)

scan_secrets, scan_injection, scan_deps

🔌 MCP Connect (5 tools)

mcp_connect, mcp_servers, mcp_tools, mcp_call, mcp_disconnect

📦 Catalog (3 tools)

catalog_fetch, catalog_search, catalog_status

🌐 Browser Automation (3 engines, 17 tools)

Playwright (natif, headless, rapide) : browser_pw_navigate, browser_pw_screenshot, browser_pw_extract, browser_pw_status

Chrome DevTools MCP (Google, debugging, performance) : browser_devtools_navigate, browser_devtools_screenshot, browser_devtools_performance, browser_devtools_status

browser-act (anti-bot, stealth, multi-session) : browser_act_status, browser_act_navigate, browser_act_extract, browser_act_screenshot, browser_act_list, browser_act_state, browser_act_click, browser_act_input

🤖 Automation (6 tools)

browse, browse_status, browse_screenshot, browse_click, schedule, schedule_list

Resources (9)

nexus://info, nexus://filesystem/{path}, nexus://memory, nexus://project, nexus://system, nexus://workflows, nexus://skills, nexus://tasks, nexus://tools

Prompts (6)

prompt_code_review, prompt_debug, prompt_audit, prompt_setup, prompt_skill_crystalize, prompt_plan

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | NEXUS_DATA_DIR | Where to store state files | ~/.nexus/ | | WORKSPACE_DIR | Default workspace path | process.cwd() | | NEXUS_ALLOWED_DIRS | Semicolon/comma-separated allowlist for filesystem access | workspace + home | | NEXUS_ALLOW_SHELL | Set to 1 to explicitly allow shell execution for cmd_* and bg_* | 0 | | NEXUS_ALLOWED_ENV | Comma-separated allowlist for extra environment variables readable via sys_env | safe defaults only | | NEXUS_ALLOWED_MCP_COMMANDS | Semicolon/comma-separated allowlist for extra MCP server commands | common local commands | | GITHUB_TOKEN | GitHub API token for private repos | none | | DEFAULT_LLM_PROVIDER | LLM provider | ollama | | DEFAULT_LLM_MODEL | Default model | qwen2.5-coder:7b |

Features

• Zero required API keys — starts instantly for local/core workflows; optional tokens unlock private GitHub and external services
• Advanced reasoning — Tree-of-Thought, ReAct loops, Plan-and-Execute, Reflection
• Multi-agent orchestration — Route, pipeline, parallel, and hierarchical agent coordination
• Persistent memory — Episodic, semantic (vector search), procedural, and knowledge graph
• Workflow engine — DAG-based multi-step execution with checkpoints
• Skill crystallization — learn from experience, reuse patterns
• Agent chains — pipeline multiple AI agents in sequence
• Anti-loop detection — detects and warns about repeated tool calls
• Security scanning — find secrets, injection risks, and vulnerable deps
• MCP proxy — connect to other MCP servers and use their tools
• Cross-platform — works on Windows, macOS, and Linux
• Session save/restore — persist entire state (memory, workflows, tasks) to disk
• Triple browser engine — Playwright (fast), Chrome DevTools (debug/performance), browser-act (anti-bot/stealth)
• 100% free browser automation — no API keys required for any browser engine
• Rate monitoring — sliding window rate tracker warns on excessive tool usage (120 RPM default)
• Circuit breaker — automatically stops calling failing tools after 3 consecutive errors, resets after 30s
• Fully async I/O — all memory operations are async, never block the event loop on long sessions

Security model

NEXUS keeps agent autonomy while avoiding unsafe shell patterns by default:

• cmd_execute, cmd_spawn, and bg_start parse command strings into executable + arguments instead of running a shell.
• Shell mode is disabled unless NEXUS_ALLOW_SHELL=1 is set explicitly.
• Filesystem tools resolve paths against allowed roots (WORKSPACE_DIR, current directory, home, and NEXUS_ALLOWED_DIRS).
• sys_env only exposes safe environment variables unless NEXUS_ALLOWED_ENV explicitly allows more.
• Tool history redacts secrets before writing .nexus/tool_history.json.
• mcp_connect only allows common local MCP commands unless NEXUS_ALLOWED_MCP_COMMANDS adds more.
• Persistence uses atomic JSON writes for core state files.

Metrics & Monitoring

NEXUS includes built-in middleware for long-running sessions:

• Rate Monitor: sliding 60s window per tool, logs a warning at 120+ calls/minute. Does not block — observes and warns.
• Circuit Breaker: after 3 consecutive failures on any tool, it returns a graceful error message instead of calling the tool again. Resets automatically after 30s of no failures.
• Tool History: all tool calls are recorded into tool_history.json with timestamps, arguments (redacted), and success/failure status. Access via status_history tool.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    NEXUS MCP Server                          │
├─────────────────────────────────────────────────────────────┤
│  Middleware Layer                                            │
│  ├─ Rate Monitor (120 RPM per tool)    ├─ Circuit Breaker   │
│  └─ Call Logging + Metrics Collection                       │
├─────────────────────────────────────────────────────────────┤
│  Plugin Registry (auto-discover 27 tool modules)            │
├─────────────────────────────────────────────────────────────┤
│  Reasoning Layer                                            │
│  ├─ Tree-of-Thought    ├─ ReAct Loop                        │
│  ├─ Plan-and-Execute   └─ Reflection                        │
├─────────────────────────────────────────────────────────────┤
│  Multi-Agent Orchestration                                  │
│  ├─ Router             ├─ Pipeline                          │
│  ├─ Parallel           └─ Hierarchical                      │
├─────────────────────────────────────────────────────────────┤
│  Advanced Memory (fully async I/O)                          │
│  ├─ Episodic             ├─ Semantic (Vector DB)            │
│  ├─ Procedural           └─ Knowledge Graph                 │
├─────────────────────────────────────────────────────────────┤
│  Core Tools                                                 │
│  ├─ Filesystem    ├─ Git       ├─ Terminal    ├─ Web        │
│  ├─ GitHub        ├─ Security  ├─ Agents      └─ System     │
├─────────────────────────────────────────────────────────────┤
│  Dev Intelligence                                           │
│  ├─ Workflows     ├─ Tasks     ├─ Skills      ├─ Chains     │
│  └─ Session Save/Restore                                    │
└─────────────────────────────────────────────────────────────┘

License

MIT