@dichvuright/mcp-hosting-server

Kết nối AI Agent (Claude, Cursor, Antigravity, OpenClaw...) vào hệ thống quản trị DichVuRight qua giao thức MCP.

Kiến trúc

AI Agent (Claude / Cursor / OpenClaw)
        |
MCP Protocol (JSON-RPC 2.0, stdio)
        |
@dichvuright/mcp-hosting-server
        |  chỉ biết: API_URL + API_KEY + API_SECRET
        |
POST /api/mcp/tools/call  ← HMAC-SHA256 signed
        |
Next.js App (verify HMAC + scope mcp:admin)
        |
MongoDB / Redis  ← MCP không kết nối trực tiếp

MCP server không bao giờ biết: JWT_SECRET, MongoDB URI, Redis password.

Cài đặt

npx -y @dichvuright/mcp-hosting-server

Tạo API Key

1. Vào Admin → API Keys
2. Tạo key mới với scope mcp:admin
3. Copy API Key và Secret

Cấu hình (không dùng .env)

Truyền biến trực tiếp qua env trong MCP config JSON:

Claude Desktop

Mở %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "dichvuright": {
      "command": "npx",
      "args": ["-y", "@dichvuright/mcp-hosting-server"],
      "env": {
        "MCP_API_URL": "https://dichvuright.com",
        "MCP_API_KEY": "mc_xxxxxxxxxxxx",
        "MCP_API_SECRET": "sk_xxxxxxxxxxxx"
      }
    }
  }
}

Antigravity / Cursor / Cline

{
  "mcpServers": {
    "dichvuright": {
      "command": "npx",
      "args": ["-y", "@dichvuright/mcp-hosting-server"],
      "env": {
        "MCP_API_URL": "https://dichvuright.com",
        "MCP_API_KEY": "mc_xxxxxxxxxxxx",
        "MCP_API_SECRET": "sk_xxxxxxxxxxxx"
      }
    }
  }
}

Dev local (chỉ dùng app local)

{
  "env": {
    "MCP_API_URL": "http://localhost:3000",
    "MCP_API_KEY": "mc_xxxxxxxxxxxx",
    "MCP_API_SECRET": "sk_xxxxxxxxxxxx"
  }
}

Tools (28 tools)

| Nhóm | Tools | |------|-------| | 🔍 Health (5) | health_check_all, health_check_mongodb, health_check_redis, health_check_suppliers, get_stuck_tasks | | 📋 Logs (5) | query_logs, get_error_summary, detect_suspicious_ips, get_critical_events, get_admin_activity_digest | | 🔔 Alerts (3) | send_alert✏️, get_alert_history, silence_alert✏️ | | 📊 Dashboard (5) | get_revenue_stats, get_user_stats, get_service_utilization, get_ticket_stats, get_payment_health | | 👤 Users (6) | find_user, get_user_profile, get_user_transactions, get_user_security_events, get_user_services, flag_user_for_review✏️ | | 🎫 Tickets (4) | list_open_tickets, get_ticket_summary, get_overdue_tickets, get_ticket_stats_summary |

* Heavy query: giới hạn 10 req/min
✏️ Write op: tạo audit log

Bảo mật

• HMAC-SHA256: mọi request đều signed, timestamp drift 60s, dedup Redis
• PII masking: email, phone, name, IP tự động masked trước khi trả về AI
• Không expose: password hash, CCCD data, encrypted secrets
• Rate limit: 60 req/min per IP global, 30 req/min per API key
• IP Rules: blocklist/allowlist quản lý trong Admin → IP Rules
• Audit trail: mọi tool call ghi vào MongoDB logs

Troubleshooting

| Lỗi | Nguyên nhân | Fix | |-----|-------------|-----| | MCP_API_KEY và MCP_API_SECRET là bắt buộc | Chưa set env | Thêm vào env trong MCP config | | Invalid API key | Key sai hoặc bị revoke | Kiểm tra Admin → API Keys | | Insufficient scope | Key chưa có scope mcp:admin | Tạo key mới với đúng scope | | Request expired | Đồng hồ máy lệch >60s | Sync NTP | | IP blocked | IP bị block trong Admin → IP Rules | Kiểm tra và xóa rule | | Tools không xuất hiện trong IDE | Sai config | Restart IDE sau khi sửa config |