> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/ai-and-agents/mcp/ilert-mcp-connector.md).

# ilert MCP connector

Deploy the read-only connector that lets ilert-hosted MCP servers reach Kafka, MySQL, PostgreSQL, ClickHouse and Redis inside your own network.

The **ilert MCP connector** is a small service you deploy in your own network. It exposes a read-only REST API over the systems that normally have no public endpoint — Kafka, MySQL, PostgreSQL, ClickHouse and Redis — so the ilert-hosted MCP servers can reach them without ilert needing direct access to your broker or database.

One connector serves all of these systems. If you use more than one of them, enable them on the same deployment rather than running a connector per system.

The connector is open source: [github.com/iLert/ilert-mcp-connector](https://github.com/iLert/ilert-mcp-connector).

{% hint style="info" %}
The connector must be reachable from the internet over a **public HTTPS URL** — that is its entire purpose. Put it behind a load balancer, ingress controller or reverse proxy, and protect it with the auth token described below.
{% endhint %}

#### Generate the auth token

The connector authenticates every request against the `AUTH_TOKEN` environment variable. This is the value you later paste as the **Secret value** when you connect the MCP server to an agent, so generate it first and keep it:

```bash
openssl rand -hex 32
```

If you start the connector without `AUTH_TOKEN`, it generates a random token and writes it to the startup log. Setting it explicitly is strongly recommended — otherwise the token changes on every restart.

#### Deploy the connector

Enable only the systems you need — each one is off until you set its `*_ENABLED` variable, and only the endpoints of enabled systems are registered. The variables for each system are listed in the configuration sections further down this page.

**Option 1: Deploy using Docker**

{% stepper %}
{% step %}
Pull the connector image:

```bash
docker pull ghcr.io/ilert/ilert-mcp-connector:latest
```

{% endstep %}

{% step %}
Run the container, enabling the systems you need and passing the token you generated:

```bash
docker run -d \
  --name ilert-mcp-connector \
  -p 8383:8383 \
  -e AUTH_TOKEN=your_generated_secret \
  -e MYSQL_ENABLED=true \
  -e MYSQL_HOST=mysql.internal \
  -e MYSQL_USER=ilert_mcp_connector \
  -e MYSQL_PASSWORD=your_password \
  -e REDIS_ENABLED=true \
  -e REDIS_HOST=redis.internal \
  -e REDIS_PASSWORD=your_password \
  ghcr.io/ilert/ilert-mcp-connector:latest
```

Drop the blocks you do not need and add `KAFKA_*`, `POSTGRES_*` or `CLICKHOUSE_*` variables the same way.
{% endstep %}
{% endstepper %}

**Option 2: Deploy using Kubernetes**

{% stepper %}
{% step %}
Create a secret holding the auth token, plus one per system whose credentials the connector needs:

```bash
kubectl create secret generic ilert-mcp-secret \
  --from-literal=authToken=your_generated_secret

kubectl create secret generic mysql-secret \
  --from-literal=username=ilert_mcp_connector \
  --from-literal=password=your_password
```

{% endstep %}

{% step %}
Create the deployment manifest:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ilert-mcp-connector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ilert-mcp-connector
  template:
    metadata:
      labels:
        app: ilert-mcp-connector
    spec:
      containers:
      - name: ilert-mcp-connector
        image: ghcr.io/ilert/ilert-mcp-connector:latest
        ports:
        - containerPort: 8383
        env:
        - name: PORT
          value: "8383"
        - name: AUTH_TOKEN
          valueFrom:
            secretKeyRef:
              name: ilert-mcp-secret
              key: authToken
        - name: MYSQL_ENABLED
          value: "true"
        - name: MYSQL_HOST
          value: "mysql"
        - name: MYSQL_PORT
          value: "3306"
        - name: MYSQL_USER
          valueFrom:
            secretKeyRef:
              name: mysql-secret
              key: username
        - name: MYSQL_PASSWORD
          valueFrom:
            secretKeyRef:
              name: mysql-secret
              key: password
        livenessProbe:
          httpGet:
            path: /health
            port: 8383
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8383
          initialDelaySeconds: 5
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: ilert-mcp-connector
spec:
  selector:
    app: ilert-mcp-connector
  ports:
  - port: 8383
    targetPort: 8383
```

{% endstep %}

{% step %}
Apply it:

```bash
kubectl apply -f deployment.yaml
```

{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Use `/health` for Kubernetes probes, not `/ready`. `/ready` requires the auth token and returns connection error details for every enabled system.
{% endhint %}

#### Server configuration

<table><thead><tr><th width="243.15625">Variable</th><th width="140.5">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>AUTH_TOKEN</code></td><td>auto-generated</td><td>Token required on every data request. Sent by ilert as <code>Authorization: Bearer &#x3C;token></code>.</td></tr><tr><td><code>PORT</code></td><td><code>8383</code></td><td>Port the connector listens on.</td></tr><tr><td><code>LOG_LEVEL</code></td><td><code>info</code></td><td><code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, <code>fatal</code> or <code>panic</code>.</td></tr><tr><td><code>LOG_FORMAT</code></td><td>console</td><td>Set to <code>json</code> for structured logs.</td></tr></tbody></table>

#### Kafka configuration

<table><thead><tr><th width="243.15625">Variable</th><th width="140.5">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>KAFKA_ENABLED</code></td><td><code>false</code></td><td>Set to <code>true</code> to enable the Kafka endpoints.</td></tr><tr><td><code>KAFKA_BROKERS</code></td><td><code>localhost:9092</code></td><td>Comma-separated broker list.</td></tr><tr><td><code>KAFKA_CLIENT_ID</code></td><td><code>ilert-mcp-connector</code></td><td>Client ID the connector registers with.</td></tr><tr><td><code>KAFKA_AUTH_TYPE</code></td><td><code>NONE</code></td><td><code>NONE</code>, <code>PLAIN</code>, <code>SCRAM-SHA-256</code>, <code>SCRAM-SHA-512</code>, <code>SSL</code> or <code>SASL_SSL</code>. If a username and password are set but this is not, it falls back to <code>PLAIN</code>.</td></tr><tr><td><code>KAFKA_USERNAME</code> / <code>KAFKA_PASSWORD</code></td><td>empty</td><td>SASL credentials, required for the <code>PLAIN</code>, <code>SCRAM-*</code> and <code>SASL_SSL</code> types.</td></tr><tr><td><code>KAFKA_SSL_CERT_LOCATION</code> / <code>KAFKA_SSL_KEY_LOCATION</code></td><td>empty</td><td>Paths to the client certificate and private key, required for <code>SSL</code> and <code>SASL_SSL</code>.</td></tr><tr><td><code>KAFKA_SSL_CA_LOCATION</code></td><td>empty</td><td>Path to the CA certificate. Optional but recommended.</td></tr><tr><td><code>KAFKA_SSL_KEY_PASSWORD</code></td><td>empty</td><td>Password for an encrypted private key.</td></tr><tr><td><code>KAFKA_SSL_INSECURE_SKIP_TLS</code></td><td><code>false</code></td><td>Skips TLS certificate verification. Not recommended in production.</td></tr><tr><td><code>KAFKA_LOG_LEVEL</code></td><td><code>6</code></td><td>Log level of the underlying Kafka client, <code>0</code> (emergency) to <code>7</code> (debug). Raise it to <code>7</code> when debugging broker connectivity.</td></tr></tbody></table>

#### MySQL configuration

<table><thead><tr><th width="243.15625">Variable</th><th width="140.5">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>MYSQL_ENABLED</code></td><td><code>false</code></td><td>Set to <code>true</code> to enable the MySQL endpoints.</td></tr><tr><td><code>MYSQL_HOST</code></td><td><code>localhost</code></td><td>MySQL host.</td></tr><tr><td><code>MYSQL_PORT</code></td><td><code>3306</code></td><td>MySQL port.</td></tr><tr><td><code>MYSQL_USER</code></td><td><code>root</code></td><td>The read-only user you created for the connector.</td></tr><tr><td><code>MYSQL_PASSWORD</code></td><td>empty</td><td>Password for that user.</td></tr><tr><td><code>MYSQL_DATABASE</code></td><td>empty</td><td>Default database for the connection. The agent addresses other databases by name.</td></tr></tbody></table>

#### PostgreSQL configuration

{% hint style="info" %}
PostgreSQL isn't generally available yet — the connector already serves it, but there is no PostgreSQL card to attach to an agent. Select **PostgreSQL** in the agent wizard and click **Request beta access**, and we will reach out when it is ready. You can enable the variables below in the meantime.
{% endhint %}

<table><thead><tr><th width="243.15625">Variable</th><th width="140.5">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>POSTGRES_ENABLED</code></td><td><code>false</code></td><td>Set to <code>true</code> to enable the PostgreSQL endpoints.</td></tr><tr><td><code>POSTGRES_HOST</code></td><td><code>localhost</code></td><td>PostgreSQL host.</td></tr><tr><td><code>POSTGRES_PORT</code></td><td><code>5432</code></td><td>PostgreSQL port.</td></tr><tr><td><code>POSTGRES_USER</code></td><td><code>postgres</code></td><td>The read-only monitoring user you created for the connector.</td></tr><tr><td><code>POSTGRES_PASSWORD</code></td><td>empty</td><td>Password for that user.</td></tr><tr><td><code>POSTGRES_DATABASE</code></td><td><code>postgres</code></td><td>Database the connection is opened against. Other databases are reached on demand.</td></tr><tr><td><code>POSTGRES_SSLMODE</code></td><td><code>disable</code></td><td><code>disable</code>, <code>require</code>, <code>verify-ca</code> or <code>verify-full</code>.</td></tr></tbody></table>

The connector reads databases, tables (as `schema.table`), table schemas with their statistics, and server metrics — current sessions, per-database statistics, configuration values, replication and replay lag, connection counts against `max_connections`, locks and blocked queries, checkpoint and buffer statistics, vacuum and dead-tuple pressure, plus long-running and idle-in-transaction sessions. There is no arbitrary-query endpoint.

**Create the PostgreSQL user**

The connector only reads system catalogs and statistics views. A plain user sees just its own sessions in `pg_stat_activity`, so grant the built-in monitoring role:

```sql
CREATE USER mcp_connector WITH PASSWORD 'your_password';
GRANT pg_monitor TO mcp_connector;
GRANT CONNECT ON DATABASE your_database TO mcp_connector;
```

`pg_monitor` (PostgreSQL 10 and later) covers `pg_stat_activity`, `pg_stat_replication`, `pg_stat_database`, `pg_stat_bgwriter` / `pg_stat_checkpointer` and `pg_settings`.

{% hint style="info" %}
PostgreSQL cannot query across databases on one connection. When a request addresses a database other than `POSTGRES_DATABASE`, the connector opens a short-lived connection to it — so repeat the `GRANT CONNECT` for every database that should be reachable.
{% endhint %}

#### ClickHouse configuration

<table><thead><tr><th width="243.15625">Variable</th><th width="140.5">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>CLICKHOUSE_ENABLED</code></td><td><code>false</code></td><td>Set to <code>true</code> to enable the ClickHouse endpoints.</td></tr><tr><td><code>CLICKHOUSE_HOST</code></td><td><code>localhost</code></td><td>ClickHouse host.</td></tr><tr><td><code>CLICKHOUSE_PORT</code></td><td><code>9000</code></td><td>Native protocol port.</td></tr><tr><td><code>CLICKHOUSE_USER</code></td><td><code>default</code></td><td>ClickHouse user.</td></tr><tr><td><code>CLICKHOUSE_PASSWORD</code></td><td>empty</td><td>Password for that user.</td></tr><tr><td><code>CLICKHOUSE_DATABASE</code></td><td><code>default</code></td><td>Default database for the connection.</td></tr></tbody></table>

#### Redis configuration

<table><thead><tr><th width="243.15625">Variable</th><th width="140.5">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>REDIS_ENABLED</code></td><td><code>false</code></td><td>Set to <code>true</code> to enable the Redis endpoints.</td></tr><tr><td><code>REDIS_HOST</code></td><td><code>localhost</code></td><td>Redis host.</td></tr><tr><td><code>REDIS_PORT</code></td><td><code>6379</code></td><td>Redis port.</td></tr><tr><td><code>REDIS_PASSWORD</code></td><td>empty</td><td>Redis password. Leave unset if no password is configured.</td></tr><tr><td><code>REDIS_ENABLE_SENSITIVE_TOOLS</code></td><td><code>false</code></td><td>Allows reading the <strong>values</strong> stored in keys. While this is <code>false</code>, the connector answers that request with <code>403</code> and only key metadata is available.</td></tr></tbody></table>

There is no database-number setting — the agent selects the Redis database per request, so all databases on the instance are reachable.

{% hint style="warning" %}
**Reading key values is gated twice.** The agent can only read stored values when `REDIS_ENABLE_SENSITIVE_TOOLS=true` on the connector **and** the `get_key_values` tool is enabled on the agent's **Tools** tab — both are off by default, and the connector-side flag is the one you control in your own network.

Even when enabled, the endpoint stays narrow: at most **20 keys per call** and each value truncated to **1 KB**. Keys holding a non-string type, and binary values that are not valid text, are reported as such instead of being returned.
{% endhint %}

#### Verify the deployment

`GET /health` is public and only says the process is up:

```bash
curl https://ilert-mcp-connector.example.com/health
```

`GET /ready` needs the token and reports one check per enabled system — this is the call that tells you whether the connector can actually reach your broker or database:

```bash
curl -H "Authorization: Bearer your_generated_secret" \
  https://ilert-mcp-connector.example.com/ready
```

A healthy response looks like this:

```json
{ "status": "ready", "checks": { "mysql": "ok", "postgres": "ok", "redis": "ok" } }
```

Anything other than `ok` is the driver's own error message — fix that before connecting the MCP server in ilert, because the agent hits the same code path.

Two more endpoints are public, next to `/health`:

* `GET /version` returns the connector's version and build commit — use it to check which image is actually running after an upgrade.
* `GET /metrics` exposes Prometheus metrics, including a counter per system operation and its errors, so you can alert on a connector that stops reaching your database.

{% hint style="warning" %}
`/health`, `/version` and `/metrics` need no token, so they are readable by anyone who can reach the URL. They expose no data from your systems, but if that is not acceptable, restrict them at your ingress or reverse proxy.
{% endhint %}

#### Used by

{% content-ref url="/pages/e92a6e1c4be3b7bd07d43d932eb17292e1608bef" %}
[Kafka](/ai-and-agents/mcp/hosted/kafka.md)
{% endcontent-ref %}

{% content-ref url="/pages/cf3580c1eb5e8097589c65e9d1c8a869ba9cec79" %}
[MySQL](/ai-and-agents/mcp/hosted/mysql.md)
{% endcontent-ref %}

{% content-ref url="/pages/20df71bf9835cd30e17e610b8b3cab78dd67e217" %}
[Clickhouse](/ai-and-agents/mcp/hosted/clickhouse.md)
{% endcontent-ref %}

{% content-ref url="/pages/aed321fed41a4199a4e085367d24714cea3ae5de" %}
[Redis](/ai-and-agents/mcp/hosted/redis.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ilert.com/ai-and-agents/mcp/ilert-mcp-connector.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.