Connector MCP Agent

High-performance Model Context Protocol (MCP) workspace bridge and remote execution runner for autonomous AI developer agents (Claude, Gemini, Cursor, Cline, Codex).

🚀 Overview

Connector MCP Agent provides AI developer agents with direct access to dedicated remote Linux workspace sandboxes, persistent background task execution, and project memory persistence.

Instead of running heavy compilers, test suites, or background daemons directly on local development machines, agents connect through standard MCP tool calls or the included zero-configuration connector-cli.

Key Benefits

• Zero-Config Agent Onboarding: Ready out-of-the-box. System identity and workspace endpoints are auto-detected without manual environment variable setup.

• Persistent Multi-Tasking: Launch background commands that survive connection drops, and reconnect at any time.

• Isolated Workspace Containers: Isolated rootless container sandboxes for build, test, and dependency installation.

• Persistent Knowledge Graph: Project context and code structure persist across agent turns and generations.

Related MCP server: MileHost MCP Server

📥 Installation (Linux / Ubuntu)

Prerequisites

• Linux / Ubuntu (20.04 LTS or newer) / WSL2

• Node.js >= 20 (node -v)

• Git (git --version)

# Verify prerequisites
node -v && git --version

Option 1: Quick Automated Install (Recommended)

Clone the repository and run the setup script:

git clone https://github.com/Catzpro01/connector-mcp-agent.git
cd connector-mcp-agent
chmod +x install.sh && ./install.sh

Option 2: Standard Git Clone & Build

git clone https://github.com/Catzpro01/connector-mcp-agent.git
cd connector-mcp-agent
npm install
npm run build
npm install -g .

Option 3: One-Liner Setup

git clone https://github.com/Catzpro01/connector-mcp-agent.git ~/.connector-agent && cd ~/.connector-agent && npm run setup

⚡ Basic Verification Commands

Once installed, verify that the CLI binary is available in your PATH:

# Check version
connector-cli --version

# Quick server latency check
connector-cli ping

# Check active agent identity
connector-cli whoami

# Check server connection & workspace health
connector-cli status

# List available workspaces
connector-cli list

# Show full help menu
connector-cli help

Sample output:

$ connector-cli --version
connector-cli v0.1.0

$ connector-cli ping
🏓 PONG! VPS di http://your-vps-ip:3210 merespons dalam 210ms (HTTP 200).

$ connector-cli whoami
👤 Identitas Agen : agent
🌐 Server VPS     : http://your-vps-ip:3210
🔑 API Key        : (default / dev)

💻 Usage

1. Interactive Workspace (TUI)

Launch the interactive workspace manager:

connector-cli

Inside the interactive workspace, you can switch between:

• Tab VPS: Interactive remote shell inside the sandbox container (/work).

• Tab Disk Session: Local project session disk, AST symbol indexer, and MCP Knowledge Graph.

• Project List: Browse, create, and switch between project sandboxes.

2. Direct Command Execution

Run commands directly in the remote container from your shell:

# Run command directly in the remote workspace
connector-cli vps "cargo test"
connector-cli vps "npm run build"

3. Background Task Multiplexing

Spawn commands that keep running in the background even if you exit:

# Open a background task
connector-cli tab new --vps build-job "npm run build:prod"

# List active background tabs
connector-cli tabs

# View real-time output of a background task
connector-cli tab attach build-job

# Stop a background task
connector-cli tab kill build-job

4. Create and Connect to Projects

# Create a new workspace sandbox
connector-cli new my-service "Backend API microservice"

# Connect to a specific workspace
connector-cli connect my-service

🧩 MCP Integration (Claude / Cursor / Cline)

To integrate Connector MCP directly with AI agent frameworks (Claude Desktop, Cline, Roo-Code, Cursor):

Add the server to your mcpServers configuration (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "connector": {
      "command": "connector-cli",
      "args": ["mcp"]
    }
  }
}

Or connect via remote HTTP/SSE endpoint directly:

{
  "mcpServers": {
    "connector-remote": {
      "type": "http",
      "url": "http://your-vps-ip:3210/mcp"
    }
  }
}

📑 Core Tool Reference

⚙️ Optional Configuration

Connector works with zero manual configuration. If custom settings are needed:

# Set custom VPS endpoint
connector-cli setting set serverUrl http://your-vps:3210

# Set agent identity
connector-cli setting set agentName my-agent

Configuration is automatically stored in ~/.connector-cli/config.json.

📄 License

MIT License © 2026. Designed for agentic developer workflows.