Agent Remote

Self-hosted MCP gateway for VPS with dashboard, API keys, and 51 granular tools.

Features

• MCP Server — Streamable HTTP transport at /mcp, compatible with Claude Code, Cursor, etc.
• API Key Management — Generate keys with per-key tool permissions, MCP config auto-generated
• 51 Granular Tools — System, filesystem, Docker, services, network, SSL, Git, PM2, Nginx, and more
• Dashboard — React SPA with login, key management, tool permissions, audit logs, live system metrics
• Per-key Permissions — Enable/disable specific tools for each API key via dashboard
• Filesystem Whitelist — Manage allowed directories from dashboard (no restart needed)
• Realtime — WebSocket for live log streaming and system metrics
• Bilingual — Vietnamese + English

Quick Start

# Install dependencies
npm install
cd web && npm install && cd ..

# Build (server + frontend)
npm run build

# Start (production with PM2) — single process serves both API and dashboard
pm2 start ecosystem.config.cjs

Dashboard + API: http://localhost:3927

Scripts

Configuration

Copy .env.example to .env:

PORT=3927
HOST=0.0.0.0
JWT_SECRET=your-random-secret
ADMIN_PASSWORD=change-me
DATA_DIR=./data
CORS_ORIGIN=*
ALLOWED_PATHS=/home:/var/www:/var/log:/opt:/etc/nginx:/tmp:/srv

MCP Client Config

Add to your Claude Code (~/.claude.json) or Cursor MCP settings:

{
  "mcpServers": {
    "agent-remote": {
      "url": "http://your-server:3927/mcp",
      "headers": {
        "x-api-key": "ar_k_your_api_key_here"
      }
    }
  }
}

Built-in Tools (51)

System (5)

Filesystem (7)

Logs (3)

Docker (7)

Docker Compose (3)

Service/Systemd (5)

Network (4)

Package (2)

SSL/TLS (2)

Git (3)

Cron (3)

PM2 (4)

Nginx (3)

Permissions

Each API key has per-tool permissions. By default, a new key can access all globally enabled tools. Use the dashboard to enable/disable specific tools for each key.

Tech Stack

• Backend: Fastify 5 + TypeScript + SQLite (better-sqlite3)
• Frontend: React 18 + Vite 5
• MCP: @modelcontextprotocol/sdk (Streamable HTTP)
• Auth: bcrypt + JWT + SHA-256 API keys
• Realtime: @fastify/websocket
• Deploy: PM2 fork mode

Production Deployment

With Nginx reverse proxy

server {
    listen 443 ssl;
    server_name agent.example.com;

    location / {
        proxy_pass http://127.0.0.1:3927;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

With Cloudflare Tunnel

cloudflared tunnel --url http://localhost:3927