🤖 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:

📋 Requirements

🔐 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:

{
  "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:

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.

Parameters:

{
  "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

{
  "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

{
  "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.

{
  "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).

💡 Usage Examples

📊 "Show me the status of all servers"

AI will execute:

👤 "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:

🖥 "Set up new server 192.168.1.100"

AI will use the setup_new_node prompt:

🔑 Access Permissions (Scopes)

🛡 Security

📚 Sources