MCP server

At the end of this guide, an AI assistant that speaks the Model Context Protocol (MCP), such as Claude, Cursor or VS Code, is connected to your hub. It can answer questions about devices, pipelines, rules and alerts from the live system, with the rights of the Proxus user it signs in as.

Before you start

You need:

• The hub's address. The MCP server is at /mcp on the hub's port, for example http://localhost:8080/mcp.
• A Proxus user for the assistant. Its role limits what the assistant may read and change. See Users and roles.
• An MCP client that supports the Streamable HTTP transport.
• [MCP] Enabled = true in the hub's configuration (the default).

Step 1: Add the server to your client

claude mcp add --transport http proxus http://localhost:8080/mcp

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

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

No header or key is configured in the client. Signing in happens inside the conversation, in the next step.

Step 2: Sign in

Before it signs in, the assistant can only list the tools and call schema_overview, which explains the server and the sign-in step. Ask it to sign in and give it the Proxus user name and password when it asks. It calls auth_login with them.

With single sign-on, the host can sign in with an access token of your identity provider instead: auth_login with accessToken. No Proxus password passes through the conversation, and the connection gets the roles mapped from the person's or service account's groups.

When two-step verification is on for the user, the assistant also asks for the current code from the authenticator app and passes it as code.

The sign-in is tied to this MCP connection and lasts SessionTtlMinutes (25 minutes by default). After that, or after auth_logout, the assistant asks again. auth_whoami shows which user the connection is signed in as.

What the assistant can do

The server also offers three prompts, proxus_read_entity, proxus_write_change and proxus_analyze_telemetry, and resources under proxus://schema/ (overview, entities, telemetry, templates, protocols).

Every call runs with the signed-in user's permissions. A change the role does not allow is refused, as it would be in the hub's screens. The role's AI Assistant Access also applies to MCP: with No access every tool except signing in is refused, with Ask questions the agent only reads, and changes need at least Ask and propose changes. Deleting is blocked by default even for users who may delete (BlockDelete = true).

Secure it for production

Set these in the [MCP] section of the hub's configuration (environment form MCP__<Key>):

[MCP.ClickHouse] limits telemetry_query: MaxResultRows (1000), MaxRowsToRead (10000000), MaxBytesToRead and MaxMemoryUsage (512 MiB), MaxExecutionTimeSeconds (10), MaxThreads (4) and MaxResultBytes (16 MiB). Set Username and Password to a database user that may only read the DeviceRawData and Logs tables.

When several hub instances run behind a load balancer, sign-ins are shared through Redis when Cluster:RedisConnection (or MCP:RedisConnection) is set.

Refusals reach the client as errors: 403 when the address is not allowed, an authorization_denied error when an administrative tool is called by a user without an administrative role, 401 when a protected tool is called before signing in, 429 when a rate limit is reached.

What's next

• REST API: the same data for your own programs.
• Operational graph: what the graph tools read.
• Security hardening.