Skip to content

mcp-user-guide.md

Latest commit

 

History

History
387 lines (270 loc) · 8.76 KB

mcp-user-guide.md

File metadata and controls

387 lines (270 loc) · 8.76 KB

🤖 MCP Integration User Guide

Connect AI assistants directly to your C³ CELERITY panel for automated management.

📖 What is MCP?

Model Context Protocol (MCP) is a protocol that allows AI assistants (Claude, Cursor, etc.) to directly interact with the C³ CELERITY panel.

✨ Capabilities

Through MCP, AI can:

Capability Description
👥 User Management Create, edit, disable VPN users
🖥 Server Configuration Configure servers and nodes
💻 SSH Commands Execute commands on servers remotely
📊 Monitoring Retrieve statistics and logs
🔧 Diagnostics Diagnose and troubleshoot issues

📋 Requirements

Requirement Description
🔑 API Key With mcp:enabled scope
🖥 AI Client Claude Desktop, Cursor IDE, or any HTTP client with SSE support

🔐 Creating an API Key

Step-by-Step

  1. 🖱 Open panel → Settings → API Keys

  2. ➕ Click Create MCP API Key

  3. ✏️ Enter a key name (e.g., "Claude Assistant")

  4. 🎛 Select permissions:

    Type Scopes Use Case
    🟢 Basic mcp:enabled + read scopes Read-only access (default)
    🟡 Extended users:write, nodes:write, sync:write Write operations

  5. 📋 Copy the key — shown only once!

⚠️ Important: Store your API key securely. You won't be able to see it again.

🔌 Connecting AI Clients

🖥 Claude Desktop

Add to your Claude Desktop configuration file:

Platform Config Path
🍎 macOS ~/Library/Application Support/Claude/claude_desktop_config.json
🪟 Windows %APPDATA%\Claude\claude_desktop_config.json 
{
  "mcpServers": {
    "celerity": {
      "url": "https://your-panel.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

📝 Cursor IDE

Create a .cursor/mcp.json file in your project root:

{
  "mcpServers": {
    "celerity": {
      "url": "https://your-panel.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

🔧 Custom Client

Any HTTP client with SSE support can connect:

Parameter Value
📍 Endpoint https://your-panel.com/api/mcp
🔐 Auth Authorization: Bearer YOUR_API_KEY
📦 Content-Type application/json
📡 Accept text/event-stream (for streaming)
📖 Example Request 
curl -X POST https://your-panel.com/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'

🛠 Available Tools

🔍 query — Read Data

Universal tool for retrieving data from the panel.

Resource Description Required Scope
users 👥 List of users users:read
nodes 🖥 List of servers nodes:read
groups 📁 Server groups stats:read
stats 📊 Traffic statistics stats:read
logs 📜 System logs stats:read

Parameters:

Parameter Required Description
resource ✅ Yes Resource type
id ❌ No Specific item ID
filter ❌ No Filters (resource-dependent)
limit, page ❌ No Pagination
sortBy, sortOrder ❌ No Sorting
📖 Example: Get all active users 
{
  "name": "query",
  "arguments": {
    "resource": "users",
    "filter": { "enabled": true },
    "limit": 50
  }
}

👤 manage_user — User Management

users:write scope required

Available Actions: create | update | delete | enable | disable | reset_traffic

📖 Example: Create a user 
{
  "name": "manage_user",
  "arguments": {
    "action": "create",
    "userId": "user123",
    "data": {
      "username": "John Doe",
      "trafficLimit": 107374182400,
      "maxDevices": 3,
      "groups": ["groupId1"]
    }
  }
}

🖥 manage_node — Server Management

nodes:write scope required

Available Actions: create | update | delete | sync | setup | reset_status | update_config

📖 Example: Setup node via SSH 
{
  "name": "manage_node",
  "arguments": {
    "action": "setup",
    "id": "nodeId123",
    "setupOptions": {
      "installHysteria": true,
      "setupPortHopping": true,
      "restartService": true
    }
  }
}

📁 manage_group — Group Management

nodes:write scope required

Available Actions: create | update | delete

🔗 manage_cascade — Cascade Tunnels

nodes:write scope required

Available Actions: create | update | delete | deploy | undeploy | reconnect

💻 execute_ssh — Execute Commands

nodes:write scope required

Executes a shell command on the server and returns the output.

📖 Example: Check service status 
{
  "name": "execute_ssh",
  "arguments": {
    "nodeId": "nodeId123",
    "command": "systemctl status hysteria-server"
  }
}

🖥 ssh_session — Interactive SSH Session

nodes:write scope required

Available Actions: start | input | close

⚙️ system_action — System Operations

sync:write scope required

Available Actions: sync_all | clear_cache | backup | kick_user

🗺 get_topology — Network Topology

nodes:read scope required

Returns all active nodes and connections between them.

❤️ health_check — Health Check

✅ No scope required

Returns uptime, sync status, cache stats, memory usage.

📝 Built-in Prompts

Prompts are pre-configured scenarios that appear as slash commands in Claude Desktop (e.g., /panel_overview).

Prompt Description
📊 panel_overview System overview: nodes, users, health
🔍 audit_nodes Find problematic nodes and suggest fixes
👤 user_report Detailed report for a specific user
🖥 setup_new_node Step-by-step node addition guide
🔧 troubleshoot_node Node diagnostics via SSH
⏰ manage_expired_users Find and handle expired users

💡 Usage Examples

📊 "Show me the status of all servers"

AI will execute:

Step Tool Purpose
1 health_check Overall status
2 query with resource=nodes List of nodes
3 — Generate report with problematic nodes highlighted

👤 "Create user testuser with 50 GB limit"

AI will execute:

manage_user → action=create, userId=testuser, trafficLimit=53687091200

🔧 "Why is node DE-01 not working?"

AI will execute:

Step Tool Purpose
1 query with resource=nodes, id=<DE-01-id> Get lastError
2 execute_ssh with systemctl status hysteria-server Check service
3 — Analyze and suggest solution

🖥 "Set up new server 192.168.1.100"

AI will use the setup_new_node prompt:

Step Action
1 📋 Collect data (IP, domain, SSH credentials)
2 🆕 Create node via manage_node
3 ⚙️ Run auto-setup via manage_node action=setup
4 ✅ Verify status

🔑 Access Permissions (Scopes)

Scope Description Level
mcp:enabled 🟢 Basic MCP access permission Required
users:read 👁 Read users Read
users:write ✏️ Create, modify, delete users Write
nodes:read 👁 Read servers and statistics Read
nodes:write ✏️ Manage servers, SSH commands Write
stats:read 👁 Read statistics and logs Read
sync:write ✏️ Sync, backups, system operations Write

🛡 Security

Best Practice Description
🔒 Secure Storage Store API keys in a secure location
🎯 Least Privilege Use minimum required permissions
🔄 Key Rotation Rotate keys periodically
📝 Audit Trail All MCP operations are logged in panel system logs

📚 Sources

File Description
src/services/mcpService.js Tool registry
src/routes/mcp.js MCP endpoints
src/mcp/prompts.js Built-in prompts
src/locales/en.json MCP interface localization