mcp-nexus

<p align="center"> <br/> <img src="https://img.shields.io/badge/MCP-Nexus-6366f1?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxwYXRoIGQ9Ik0xMiAyTDIgN2wxMCA1IDEwLTV6Ii8+PHBhdGggZD0iTTIgMTdsMTAgNSAxMC01Ii8+PHBhdGggZD0iTTIgMTJsMTAgNSAxMC01Ii8+PC9zdmc+" alt="MCP Nexus"/> <br/> <h1 align="center">MCP Nexus</h1> <p align="center"> <strong>Turn any AI assistant into a full-stack DevOps engineer for your server.</strong> <br/> 163 tools for files, terminal, git, services, databases, debugging, monitoring, deployment, and observability<br/> — with a built-in intelligence layer that learns how you work. </p> <p align="center"> <a href="#hosted-gateway">Hosted Gateway</a> &bull; <a href="#quick-start">Quick Start</a> &bull; <a href="#intelligence">Intelligence</a> &bull; <a href="#tools">163 Tools</a> &bull; <a href="#architecture">Architecture</a> &bull; <a href="#configuration">Config</a> </p> </p>

---

Hosted Gateway

Don't want to install anything? Use the Lightcap-hosted MCP Nexus instance as a gateway to your servers:

https://lightcap.ai/mcp/nexus

Connect your AI client directly, enter your own server credentials once, and let ChatGPT or Claude operate that machine through the gateway. No agent install, no daemon on your server, no custom packaging step.

Open that URL in a browser and you now get a real connect page, not a blank MCP endpoint. It explains the flow, shows the MCP and OAuth values, and links directly to GitHub and the docs while preserving the same path for actual MCP clients.

Why people use the hosted gateway:

• Bring any Linux server you already own. MCP Nexus handles the AI-facing side.
• Use one connection for terminal, files, git, deploy, database, process control, monitoring, and debugging.
• Keep the target explicit. You type your own server host, SSH user, SSH port, and SSH password at connect time.
• Skip setup overhead when you just want to put ChatGPT on a real machine and start shipping.

What that page does for humans:

• Shows the exact MCP URL to paste into ChatGPT or Claude.
• Shows manual OAuth values for clients that still ask for them.
• Explains which values are OAuth credentials and which values are your real server credentials.
• Links back to the GitHub repository and README for deeper setup details.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "nexus": {
      "url": "https://lightcap.ai/mcp/nexus/sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Claude Code (.mcp.json):

{
  "mcpServers": {
    "nexus": {
      "url": "https://lightcap.ai/mcp/nexus/sse"
    }
  }
}

ChatGPT Apps / Connectors

Use the MCP server URL directly:

• Connector URL: https://lightcap.ai/mcp/nexus

ChatGPT discovers OAuth automatically from:

• https://lightcap.ai/.well-known/oauth-authorization-server
• https://lightcap.ai/.well-known/oauth-protected-resource/mcp/nexus

During Connect, MCP Nexus redirects you to a consent screen where you choose the SSH target for that ChatGPT connection. The resulting OAuth access token is then bound to that server and every tool call is routed through the matching SSH pool.

ChatGPT Connect In 60 Seconds

What you will enter on the MCP Nexus consent page:

• Your server host or IP
• Your SSH user
• Your SSH port
• Your SSH password

Those are your real server credentials. They do not go into OAuth client_id or client_secret.

If the ChatGPT UI asks for manual OAuth fields instead of using discovery, use:

• MCP URL: https://lightcap.ai/mcp/nexus
• Auth URL: https://lightcap.ai/authorize
• Token URL: https://lightcap.ai/token
• Registration URL: https://lightcap.ai/register
• Authorization server base: https://lightcap.ai
• Resource: https://lightcap.ai/mcp/nexus
• Client ID: nexus-lightcap-prod
• Client Secret: nxs_sec_9f78f08ec360-lc2026
• Scope: nexus or leave it blank if the client allows that

These are the shared manual OAuth values for the Lightcap-hosted gateway only. They are not your server credentials and they are not meant for self-hosted MCP Nexus deployments.

Do not use these values in ChatGPT Connect:

• https://lightcap.ai/mcp/nexus/oauth/token as Auth URL
• https://lightcap.ai/mcp/nexus/oauth/token as Token URL
• Your server IP as OAuth client_id
• Your SSH password as OAuth client_secret

Important: ChatGPT Connect uses standard OAuth discovery plus the consent screen. SSH host, user, port, password, or key belong in the consent step, not in OAuth client fields.

If ChatGPT opens a page on https://lightcap.ai/..., that is expected. That page is the OAuth consent screen. Enter your real SSH target there:

• SSH host: your server host or IP such as 149.102.155.77
• SSH user: your SSH username such as root
• SSH port: usually 22
• SSH password / key: your real SSH credential for that server

Do not reuse those SSH values as OAuth client_id or client_secret.

If you self-host MCP Nexus and want manual OAuth fields to work, configure a real static OAuth client in the server first:

• NEXUS_OAUTH_CLIENT_ID
• NEXUS_OAUTH_CLIENT_SECRET
• NEXUS_OAUTH_CLIENT_REDIRECT_URIS

NEXUS_OAUTH_CLIENT_REDIRECT_URIS must contain the exact ChatGPT callback URL shown by the client.

If you previously saved a connector with old manual values such as:

• Auth URL: https://lightcap.ai/mcp/nexus/oauth/token
• Token URL: https://lightcap.ai/mcp/nexus/oauth/token
• client_id = your server IP
• client_secret = your SSH password

delete that connector and create a fresh one. ChatGPT may keep reusing the stale OAuth client configuration, which produces invalid /authorize requests instead of the standards-based discovery flow.

If ChatGPT says Client ID '...' not found, the problem is not localhost handling and not your SSH target. It means the OAuth client_id in the connector does not match a configured MCP Nexus OAuth client.

Legacy machine-to-machine token flow

For scripts, curl tests, or non-ChatGPT clients, the legacy gateway token endpoint still exists. This is a separate flow and should not be used as the ChatGPT Connect configuration:

curl -X POST https://lightcap.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_SERVER_IP",
    "client_secret": "YOUR_SSH_PASSWORD"
  }'

The gateway validates by connecting to your server via SSH. Once authenticated, all 163 MCP tools operate on YOUR server through the Lightcap gateway. Full audit logging, rate limiting, and connection pooling included.

flowchart LR
    AI["Your AI"] -->|MCP / HTTPS| Gateway["lightcap.ai/mcp/nexus<br/>Hosted Gateway"]
    Gateway -->|SSH| Target["Your Server<br/>Target Host"]

Self-hosted? Skip the gateway and run MCP Nexus on your own machine — see Quick Start below.

---

Why MCP Nexus?

Most MCP servers give you tools. Nexus gives you tools that remember.

Every command you run, every service you restart, every file you edit — Nexus quietly learns your patterns. The next time you connect, it already knows what you were working on, which paths you use most, and what you'll probably need next.

flowchart LR
    Client["You via Claude / GPT"] -->|MCP| Nexus
    Nexus -->|SSH| Host

    subgraph NexusBox["MCP Nexus"]
        direction TB
        Nexus["Gateway + Tool Surface"]
        Intelligence["Intelligence"]
        Memory["Session memory"]
        Preferences["Preference learning"]
        Workflows["Workflow detection"]
        Suggestions["Smart suggestions"]
        Nexus --> Intelligence
        Intelligence --> Memory
        Intelligence --> Preferences
        Intelligence --> Workflows
        Intelligence --> Suggestions
    end

    subgraph TargetBox["Your Server"]
        direction TB
        Host["Execution Target"]
        Files["Files<br/>read, write, edit, search, diff"]
        Terminal["Terminal<br/>execute commands, scripts"]
        Git["Git<br/>commit, push, pull, branch"]
        Services["Services<br/>systemd, docker, nginx"]
        Database["Database<br/>PostgreSQL queries"]
        Debug["Debug<br/>lint, typecheck, syntax, TODOs"]
        Monitoring["Monitoring<br/>health, metrics, logs"]
        Deploy["Deploy<br/>sync, restart, rollback"]
        Network["Network<br/>ports, DNS, SSL, forwarding"]
        Packages["Packages<br/>pip, apt, npm"]
    end

    Host --> Files
    Host --> Terminal
    Host --> Git
    Host --> Services
    Host --> Database
    Host --> Debug
    Host --> Monitoring
    Host --> Deploy
    Host --> Network
    Host --> Packages

What makes it different

| | Other MCP servers | MCP Nexus | |---|---|---| | Hosted gateway | Install-only | Use lightcap.ai/mcp/nexus instantly — zero setup | | Memory | Stateless — every session starts from zero | Remembers your sessions, preferences, and workflows | | Scope | Single-purpose (just files, just git) | 163 tools covering the full DevOps stack | | Debugging | None | Lint, typecheck, syntax check, error search, symbol finder | | Connection | Spawns new processes per call | Pooled SSH connections with auto-reconnect | | Recovery | You notice when things break | Watchdog auto-restarts crashed services | | Auth | None or basic | OAuth2 with scoped tokens and rate limiting | | Audit | None | Every tool call logged with timing |

---

Quick Start

Install

mkdir -p ~/mcp-nexus
cd ~/mcp-nexus
python3 -m venv .venv
source .venv/bin/activate
pip install "git+https://github.com/farukalpay/mcp-nexus.git"
mcp-nexus init .

Or from a local checkout:

git clone https://github.com/farukalpay/mcp-nexus.git
cd mcp-nexus
python -m venv .venv && source .venv/bin/activate
pip install -e .
mcp-nexus init .

Configure

mcp-nexus init .          # writes .env
mcp-nexus init . --systemd
# Edit .env with your server credentials

Minimal .env:

NEXUS_SSH_HOST=your-server-ip
NEXUS_SSH_KEY_PATH=~/.ssh/id_rsa

Note: NEXUS_SSH_USER defaults to root. If your host uses a different account, set it explicitly in .env. Any non-root user should have the permissions your tool set requires for service, package, and deployment operations.

mcp-nexus init is the pip-first setup path. It writes a runnable .env in the target directory and can also generate a systemd unit example bound to the currently installed Python environment.

Connect to your AI

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "nexus": {
      "command": "mcp-nexus",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Claude Code (.mcp.json):

{
  "mcpServers": {
    "nexus": {
      "command": "mcp-nexus",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Remote / HTTP mode (for web apps, shared teams):

mcp-nexus serve                # starts on port 8766
# Then connect via: http://your-host:8766/mcp

Docker:

docker compose up -d

---

Intelligence

The intelligence layer is what turns Nexus from a tool shelf into an operating context. It stores interaction history in SQLite (~/.mcp-nexus/memory.db by default), keeps a JSONL audit trail, and exposes both layers back through MCP tools.

What it learns

• Session context: recent actions, errors, and the last active workflow.
• Preferences: repeated repo paths, working directories, services, sandboxes, and deployment roots.
• Workflow patterns: explicit tool-to-t