QuoxMCP

MCP protocol adapter for AI infrastructure tools.

Current release: v1.2.0

QuoxMCP is an MCP (Model Context Protocol) server that gives Claude native access to QuoxCORE infrastructure tools. It runs as a STDIO subprocess spawned by Claude Desktop, fetches available tools from the collector at startup, and proxies every tool call back to the collector for execution.

What It Is

QuoxMCP is a thin protocol adapter. It translates between the MCP JSON-RPC protocol (used by Claude Desktop and Claude CLI) and the QuoxCORE collector HTTP API. No tool logic lives in QuoxMCP — all execution, RBAC, bastion routing, and audit logging stays in the collector.

When Claude needs to run docker_status on a host, it calls the MCP tool. QuoxMCP forwards the call to POST /api/v1/tools/execute on the collector. The collector runs the tool through the SSH bastion, logs the action to the AEE audit trail, and returns the result. QuoxMCP sends it back to Claude.

The Problem

Without MCP, the QuoxCORE CLI path uses regex pattern matching to detect tool intent in user messages. This is fragile:

• False matches: "dig deeper into the logs" triggers the DNS dig tool
• One-shot execution: Tools run before Claude sees the message, so Claude can't iterate
• Hallucinated tools: Claude sometimes references tools that don't exist
• No follow-up: After one tool result, Claude must respond in a single pass

MCP fixes all of these by giving Claude native tool-calling capability — the same iterative, multi-step execution that the API path provides.

Architecture

Claude Desktop (or Claude CLI)
  │
  │ spawns via .mcpb install / --mcp-config
  │
  ▼
QuoxMCP (STDIO subprocess)
  │
  │ 1. GET /api/v1/tools/list?agent_id={id}  → fetch available tools
  │ 2. Register tools via MCP protocol
  │ 3. POST /api/v1/tools/execute             → proxy tool calls
  │
  ▼
QuoxCORE Collector (port 9848)
  │
  │ RBAC enforcement (AGENT_TOOLS)
  │ AEE audit logging
  │ SSH bastion routing
  │ Plugin license checks
  │
  ▼
Infrastructure (Docker hosts, Proxmox, monitoring, etc.)

Installation

Claude Desktop — recommended

1. Download quoxmcp.mcpb from the latest release.
2. Double-click the file — Claude Desktop opens an install dialog.
3. Fill in the four required fields:
   • Collector URL — base URL of your QuoxCORE collector (e.g. http://127.0.0.1:9848)
   • Service Key — INTERNAL_SERVICE_KEY from your QuoxCORE deployment
   • Org ID — your organisation identifier (required for audit attribution, v1.2.0+)
   • User ID — the user performing the install (required for audit attribution, v1.2.0+)
4. Optionally set Agent ID (defaults to quox).
5. Click Install, fully quit Claude Desktop, then relaunch.

After relaunch, QuoxMCP appears in Claude Desktop's tools panel and the 130 available tools are ready to use.

Manual install — advanced

For fleet or server deployments where Claude Desktop is not used, see the manual install guide. This path requires editing the MCP JSON config directly — see the environment variables table below.

Configuration

QuoxMCP is configured via environment variables. When using the .mcpb installer these are set through the install dialog. For manual installs they are set in the MCP config file:

{
  "mcpServers": {
    "quox-tools": {
      "command": "node",
      "args": ["/path/to/quoxmcp/server.js"],
      "env": {
        "QUOX_SERVICE_KEY": "your-service-key",
        "QUOX_COLLECTOR_URL": "http://127.0.0.1:9848",
        "QUOX_ORG_ID": "your-org-id",
        "QUOX_USER_ID": "your-user-id",
        "QUOX_AGENT_ID": "quox",
        "QUOX_SESSION_ID": ""
      }
    }
  }
}

Audit Trail

Every tool call from Claude Desktop produces a complete, attributed audit record in QuoxCORE (v1.2.0+):

All three records are chained under the same stable session correlation ID (see QUOX_SESSION_ID above). The full call history is visible in the QuoxCORE dashboard audit viewer.

To check the status of your installed clients: GET /api/v1/mcp/status or the /quoxmcp dashboard page.

Tool Categories

QuoxMCP serves 130 tools dynamically loaded from the collector, organised by category:

In addition to tools, QuoxMCP exposes 5 read-only resources (system identity, fleet topology, agent capabilities, and others) and 4 operational prompts (fleet-health, security-sweep, incident-triage, deploy-checklist). All are fetched live from the collector at startup.

Agent RBAC

Each AI agent sees only the tools it is authorised to use. The collector enforces this via the AGENT_TOOLS mapping:

• QUOX (Orchestrator) — All tools including delegate_to_agent and workflow management
• SENTINEL (Security) — ssh_exec, security_audit, ssl_certificates, network_check, fleet_status, memory tools
• NOVA (DevOps) — ssh_exec, docker_status, docker_extended, system_admin, fleet_status, memory tools
• ATLAS (Proxmox) — ssh_exec, all proxmox_* tools, fleet_status, memory tools
• METRICS (Monitoring) — ssh_exec, metrics_query, alerts_manage, fleet_status, memory tools
• CIPHER (Network) — ssh_exec, network_check, fleet_status, system_admin, memory tools

When QUOX delegates to a specialist agent, a new MCP session is spawned with that agent's ID. The specialist only sees its own tools.

Plugin Extension

Licensed plugins automatically extend the tool set. When you install and license a plugin (e.g., Proxmox), its tools become available through MCP without any additional configuration:

1. Plugin is licensed in QuoxCORE dashboard
2. Plugin tools are registered in TOOL_DEFS
3. Collector serves them via /api/v1/tools/list
4. QuoxMCP picks them up at next startup

Collector API Endpoints

QuoxMCP uses three collector API endpoints:

GET /api/v1/tools/list

Returns available tools for an agent.

# Tools for a specific agent
curl http://127.0.0.1:9848/api/v1/tools/list?agent_id=sentinel

# All tools (for dashboard Core tab)
curl http://127.0.0.1:9848/api/v1/tools/list?agent_id=all

POST /api/v1/tools/execute

Executes a tool with RBAC enforcement.

curl -X POST http://127.0.0.1:9848/api/v1/tools/execute \
  -H 'Content-Type: application/json' \
  -d '{
    "tool_name": "fleet_status",
    "input": {},
    "agent_id": "quox",
    "session_id": "sess-123"
  }'

GET /api/v1/tools/agents

Returns agent-to-tool and tool-to-agent mappings.

curl http://127.0.0.1:9848/api/v1/tools/agents

Remote Agent Deployment

QuoxMCP can be deployed to any host in the fleet alongside QuoxAgent. This gives each server its own AI agent with native tool access, calling back to the central collector for execution and audit.

How It Works

1. The install script (quoxagent/deploy/install.sh) provisions Node.js, downloads the QuoxMCP bundle, and generates an MCP config
2. The service key is passed over SSH during deployment — never baked into downloadable scripts
3. Each host's QUOX_AGENT_ID is set to its hostname, so RBAC applies per-host
4. Claude CLI on the remote host uses --mcp-config /etc/quoxmcp/mcp-config.json

File Layout on Remote Hosts

Deploy Commands

# Build the bundle on the control workstation
cd /home/control/quoxmcp/deploy && ./bundle.sh

# Deploy to a single host (reads service key from dashboard .env)
cd /home/control/quoxagent/deploy
./deploy-to-host.sh nw-web-01

# Deploy to all fleet hosts
./deploy-to-host.sh all

# Verify QuoxMCP on all hosts
./deploy-to-host.sh all --check-mcp

Authentication

Every request from QuoxMCP to the collector carries an X-Service-Key header. The collector validates this against its INTERNAL_SERVICE_KEY environment variable. QuoxMCP will refuse to start if no service key is configured.

The service key travels over SSH during deployment and is stored in /etc/quoxmcp/mcp-config.json with chmod 600 (root-only readable).

Troubleshooting

QuoxMCP can't connect to collector

[QuoxMCP] Failed to fetch tools from collector: ECONNREFUSED

The collector isn't running or isn't accessible at the configured URL. Check:

• docker ps | grep collector — is the collector container running?
• curl http://127.0.0.1:9848/health — can you reach it?
• Check QUOX_COLLECTOR_URL in your MCP config

No tools available

[QuoxMCP] Warning: No tools available for agent xyz

The agent ID doesn't have any tools assigned. Check:

• Is QUOX_AGENT_ID set correctly?
• curl http://127.0.0.1:9848/api/v1/tools/agents — does this agent have tools?

Claude says "I don't have tools"

MCP config isn't being loaded by Claude CLI. Verify:

• The --mcp-config flag points to a valid JSON file
• The config file has correct paths to server.js
• Node.js is available in the PATH

Related

• QuoxCORE — The platform that powers QuoxMCP
• AI Agents — Agent hierarchy and delegation system
• Architecture — System architecture overview
• API Reference — Full API documentation