How Agents Work

The on-premise agent architecture — how an agent on your server becomes a secure MCP bridge to your databases.

Architecture overview

conexor.io is split into two parts: a cloud control plane that handles authentication, routing, and audit logging — and an on-premise agent that runs inside your network and has direct database access.

  Claude / AI Model
       │  MCP call
       ▼
  ┌─────────────────────────────┐
  │   conexor.io Control Plane  │  (cloud)
  │   ─ Auth & routing          │
  │   ─ Audit logging           │
  │   ─ Schema caching          │
  └──────────────┬──────────────┘
                 │  SignalR (WSS)
                 ▼
  ┌─────────────────────────────┐
  │   Agent (your network)     │  (on-premise)
  │   ─ Receives query request  │
  │   ─ Executes parameterized  │
  │     SQL against your DB     │
  │   ─ Returns result rows     │
  └──────────────┬──────────────┘
                 │  native driver
                 ▼
        Your Database

Your actual data never passes through conexor.io's servers. The control plane relays the query request (a template + parameters) to the agent, the agent runs the query, and the result travels back through the same channel.

The SignalR connection

The agent uses ASP.NET Core SignalR over WebSocket Secure (WSS) to maintain a persistent, bidirectional connection to the control plane. This connection is:

Outbound-only — your firewall only needs to allow TCP 443 outbound
Always-on — the agent reconnects automatically after any interruption
Authenticated — the agent API key is sent in a header on every connection
Encrypted — TLS 1.3 end-to-end between agent and control plane

Reconnection behaviour

The agent uses exponential backoff reconnection: it retries immediately, then after 2 seconds, 10 seconds, and 30 seconds. If all retries fail, it continues retrying on each heartbeat interval.

text

Connection lost
└─ Retry 1: immediately
└─ Retry 2: after 2s
└─ Retry 3: after 10s
└─ Retry 4: after 30s
└─ Then: retries on every heartbeat (default 30s)

Message protocol

The control plane sends named messages to the agent over the SignalR channel. The agent handles each message type asynchronously and responds via the same channel.

MessageDirectionDescription

schema.discover→ agentTrigger schema discovery for a data source

schema.result← agentSchema discovery result (tables, columns, FK)

query.execute.parameterized→ agentExecute a parameterized SELECT query

query.execute→ agentLegacy: execute a raw SQL query (deprecated)

query.result← agentQuery result columns, rows, and execution time

api.execute→ agentExecute a REST API request

api.result← agentAPI response columns and rows

connection.set→ agentSet or update a data source connection string

Heartbeat

Every 30 seconds (configurable), the agent sends a Heartbeat message to the control plane containing its current version, status, and timestamp. The control plane uses this to update the online/offline status shown in the dashboard.

If a heartbeat is missed, the agent status changes to Degraded. After several missed heartbeats, it changes to Offline. New queries are rejected while the agent is offline.

Config persistence

When a data source connection string is set via connection.set, the agent encrypts it with AES-256 and saves it to a local config file. On restart, the agent loads the encrypted config and decrypts it in memory — meaning data source connections persist across restarts without requiring the dashboard to re-send them.

INFOThe config file is stored at ~/.conexor/config.json on Linux/macOS or %APPDATA%\conexor\config.json on Windows.

Use with Claude Schema Discovery

All systems operational