Skip to main content

General

AI Agent Integration (MCP Server)

Connect AI assistants like OpenAI Codex, Claude, Cursor, and custom agents to Proxus IIoT Platform via Model Context Protocol.

Proxus includes a Model Context Protocol (MCP) server that enables AI assistants and autonomous agents to interact with your IIoT platform through natural language. Query telemetry data, manage devices, and automate workflows—all through conversational AI.

Quick Start

  1. Configure your AI agent

    Add Proxus MCP server to your agent configuration (see Agent Configuration below).

    Endpoint: http://your-proxus-server:8080/mcp

  2. Authenticate

    Use the auth_login tool:

    auth_login(userName: "Admin", password: "your-password")

    Token is cached for 25 minutes.

  3. Start querying

    schema_overview()           # Understand the platform
telemetry_devices(hours=24) # List active devices
telemetry_latest(count=10)  # Get recent sensor data

Available Tools

Proxus MCP provides 12 tools organized into four categories:

Authentication Tools

ToolDescription
auth_loginLogin with username/password, cache JWT token (25 min)
auth_logoutClear cached token for a user
auth_whoamiShow active sessions and token status

Telemetry Tools (ClickHouse)

Direct access to time-series sensor data stored in ClickHouse (DeviceRawData).

ToolDescriptionParameters
telemetry_queryExecute custom SQL SELECT queryquery, maxRows=1000
telemetry_latestGet most recent recordscount=10, deviceName?, key?
telemetry_statsAggregated statistics (count, min, max, avg)hours=24, deviceName?, key?
telemetry_devicesList devices with recent telemetryhours=24
telemetry_keysList available metrics/tagsdeviceName?, hours=24

Telemetry Schema (DeviceRawData):

ColumnTypeDescription
TimeDateTime64(3)Timestamp with milliseconds
DeviceIdUInt32Device identifier
DeviceNameStringDevice name
KeyStringTag/metric name (e.g., Temperature, Pressure)
DataTypeEnumBool, Short, Int, Float, Double, String, DateTime
NumericValueFloat64Numeric value
StringValueStringString value

Schema Tools

Discover available data and understand the platform structure.

ToolDescription
schema_overviewPlatform overview with data sources and workflow guide
schema_entitiesList OData entities (Device, Tag, Rule, Function, Alarm, etc.)
schema_telemetryClickHouse DeviceRawData table schema with example queries

OData Tool

ToolDescription
odata_requestExecute OData API requests for entity CRUD operations

Parameters: method, path or endpoint, body?, baseUrl?, userName?/username?, password?

Example:

{
  "method": "GET",
  "path": "Device?$top=10&$filter=Connected eq true"
}

Agent Configuration

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.proxus]
url = "http://localhost:8080/mcp"

Usage in Codex:

› connect to proxus mcp server
› Admin password empty

• Called proxus.auth_login({"userName":"Admin","password":""})
• Connected. Token valid for 25 minutes.

› analyze telemetry data for the last 24 hours

• Called proxus.telemetry_devices({"hours":24})
• Called proxus.telemetry_stats({"hours":24})

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "proxus": {
      "httpUrl": "http://localhost:8080/mcp"
    }
  }
}

Usage in Gemini:

gemini "analyze recent telemetry data"

The Gemini CLI uses ~/.gemini/settings.json for configuration. After adding the server, it will be available for all Gemini-powered tools.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "proxus": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://your-proxus-server:8080/mcp", "--transport", "sse-only"]
    }
  }
}

Cursor IDE

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "proxus": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Windsurf / Codeium

Add to MCP configuration:

{
  "servers": {
    "proxus": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Custom Python Agent

from mcp import ClientSession
from mcp.client.http import HttpClient

async def query_proxus():
    async with HttpClient("http://localhost:8080/mcp") as client:
        session = ClientSession(client)
        await session.initialize()
        
        # Login
        result = await session.call_tool("auth_login", {
            "userName": "Admin",
            "password": ""
        })
        
        # Get device telemetry
        devices = await session.call_tool("telemetry_devices", {
            "hours": 24
        })
        
        print(devices)

Common Workflows

Device Status Report

1. auth_login(userName, password)
2. odata_request(GET, api/odata/Device?$filter=Enabled eq true)
3. telemetry_devices(hours=1)  # Which devices have recent data?

Telemetry Analysis

1. telemetry_keys(hours=168)     # What metrics are available?
2. telemetry_stats(hours=168, key="Temperature")
3. telemetry_query("SELECT toStartOfHour(Time) as Hour, avg(NumericValue) 
                    FROM DeviceRawData 
                    WHERE Key='Temperature' 
                    GROUP BY Hour 
                    ORDER BY Hour")

Troubleshooting Device

1. schema_entities()  # Understand data model
2. odata_request(GET, api/odata/Device?$filter=DeviceName eq 'PLC_01')
3. telemetry_latest(deviceName="PLC_01", count=50)
4. telemetry_stats(hours=24, deviceName="PLC_01")

Security Configuration

MCP settings in Proxus-config.toml. See the Configuration Reference for details.

[MCP]
Enabled = true                    # Enable/disable MCP server
AllowedMethods = "GET,POST,PATCH,PUT"  # Allowed HTTP methods
BlockDelete = true                # Block DELETE operations
AdminOnly = false                 # Restrict to admin users
RateLimitEnabled = true           # Enable rate limiting
RateLimitRequestsPerMinute = 60   # Requests per user per minute
AuditLogging = true               # Log all MCP operations
IPWhitelist = []                  # IP restriction (empty = all allowed)
MaxConcurrentSessionsPerUser = 0  # 0 = unlimited
AlertOnSuspiciousActivity = false # Log suspicious attempts

Production Recommendations

Read-Only Mode (Maximum Safety):

[MCP]
Enabled = true
AllowedMethods = "GET"
AdminOnly = true
RateLimitRequestsPerMinute = 30
IPWhitelist = ["10.0.0.0/8", "192.168.0.0/16"]

Standard Mode (Controlled Write):

[MCP]
Enabled = true
AllowedMethods = "GET,POST,PATCH"
BlockDelete = true
RateLimitRequestsPerMinute = 60
AuditLogging = true

Troubleshooting

Connection Failed

  1. Check server is running: curl http://localhost:8080/healthz
  2. Verify MCP is enabled in Proxus-config.toml
  3. Check firewall allows port 8080

401 Unauthorized

  1. Call auth_login first with valid credentials
  2. Token expires after 25 minutes—re-authenticate if needed
  3. Check AdminOnly setting if using non-admin account

Rate Limit Exceeded

Increase limit in configuration:

[MCP]
RateLimitRequestsPerMinute = 120

Tool Not Found

Ensure you're using the correct tool names:

  • Telemetry: telemetry_query, telemetry_latest, telemetry_stats, telemetry_devices, telemetry_keys
  • Schema: schema_overview, schema_entities, schema_telemetry
  • OData: odata_request
  • Auth: auth_login, auth_logout, auth_whoami

API Reference

Endpoint

POST http://your-server:8080/mcp
Content-Type: application/json
Accept: text/event-stream, application/json

Initialize Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": {"name": "my-agent", "version": "1.0"},
    "capabilities": {}
  }
}

Tool Call Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "telemetry_latest",
    "arguments": {"count": 10}
  }
}
← Previous
REST API Reference
Next →
Troubleshooting Overview