# AI agents (MCP)

Insights ships a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets an AI agent — Claude Desktop, Claude Code, Cursor, or any MCP-capable client — read your NATS deployment's data directly: run read-only SQL, discover the schema, inspect instance capabilities, and run checks. It reaches the same NATS API the CLI uses, so it works against any Insights node, including production.

The MCP server is **read-only by construction**. Every tool is enforced server-side to reject writes and DDL, so pointing an agent at a production instance is safe. For the full flag reference, see the CLI reference.

## Prerequisites

* The `insights` binary (the MCP server is the built-in `mcp` subcommand — there is no separate download). See [Installation](/insights/1.2/getting-started/installation.md).
* A running Insights server reachable over NATS. The MCP server owns no database; it is a NATS client that forwards each tool call to a live Insights node, exactly like `insights db query`. See the [Quickstart](/insights/1.2/getting-started/quickstart.md) to stand one up.
* NATS connection details for that node — a NATS CLI context or an explicit server URL and credentials. With the embedded sink (the default), the node's NATS server binds `127.0.0.1` on a random port, printed in its logs at startup; pin it with `--sink.port` (for example `--sink.port=4222`) for a URL that survives restarts. With an external sink, use the cluster the node uses.

## How it works

The MCP server is a thin gateway: a tool call arrives, and it forwards the request to the matching Insights NATS endpoint and returns the reply. It runs no queries itself and stores nothing. Its NATS credentials are the real data boundary — it can only reach what that identity is permitted to.

It offers two transports:

* **stdio** — the client launches `insights mcp` as a subprocess and talks to it over stdin/stdout. This is the default and the right choice for local desktop clients (Claude Desktop, Cursor, Claude Code).
* **HTTP** — a long-running service on a port, for networked or shared clients. See [HTTP transport](#http-transport).

## Quick start

Select the NATS context that reaches the Insights API, then run the server over stdio:

```
nats context select my-nats-context

insights mcp
```

It reads and writes MCP over stdin/stdout, so it looks idle when launched by hand — that is expected. A client (below) starts and stops it for you. To sanity-check that your connection works, run a one-shot query through the same selected context instead:

```
insights db query "SELECT count(*) FROM hx.servers"
```

If that returns rows, the MCP server will reach the same data. With several systems reachable, the query stops and lists them; add `--system <id>` to pick one, which is the same choice an agent makes through the `systems` tool.

## Connecting to NATS

The MCP server takes the same connection flags as every other Insights subcommand:

| Flag        | Env                     | Description                                                            |
| ----------- | ----------------------- | ---------------------------------------------------------------------- |
| `--context` | `INSIGHTS_NATS_CONTEXT` | Override the currently selected NATS CLI context with a named context. |
| `--server`  | `INSIGHTS_NATS_SERVER`  | An explicit NATS server URL, e.g. `nats://insights.example.com:4222`.  |
| `--creds`   | `INSIGHTS_NATS_CREDS`   | Path to a NATS credentials file.                                       |

A context bundles the server URL and credentials under one name. With no connection flags, MCP inherits the currently selected local NATS context; use `--context` only for a per-process override. For stdio, credentials come from this environment (the context, flags, or `INSIGHTS_*` env vars), per the MCP spec — not from the protocol. Each tool call is a NATS request bounded by `--timeout` (default `2m`).

One `insights mcp` serves every system: each tool takes a **required** `system` argument naming the one that call addresses, so a session can compare across systems and no call can be answered by a system it did not name.

Resolving which system is the agent's job, and the `systems` tool describes how: call it first, and exactly one result is the answer while several means asking the user which they mean rather than choosing for them. There is no default and no `--system` to pin the server — a default would guess, and would break every call that had been omitting the argument the moment a second system appeared.

## Integrating with tools

### Claude Desktop

Edit Claude Desktop's config file:

* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add an `insights` server:

```
{

  "mcpServers": {

    "insights": {

      "command": "/absolute/path/to/insights",

      "args": ["mcp"]

    }

  }

}
```

* `command` **must be an absolute path** — Claude Desktop resolves neither `$PATH` nor `~`. Find it with `which insights`.
* Restart Claude Desktop. The Insights tools then appear in the client, and you can ask it questions like *"which servers have the highest CPU right now?"* or *"run the JetStream checks and summarize the findings."*

To keep credentials out of the config file, reference a context that points at a creds file on disk, or supply them through an `env` block:

```
{

  "mcpServers": {

    "insights": {

      "command": "/absolute/path/to/insights",

      "args": ["mcp"],

      "env": { "INSIGHTS_NATS_CONTEXT": "my-nats-context" }

    }

  }

}
```

### Claude Code

Register the server with the CLI (the `--` separates Claude Code's flags from the server command):

```
claude mcp add insights -- /absolute/path/to/insights mcp
```

Use the absolute path to `insights` if it is not on your `PATH`. Add `--scope project` to share the server with a repository via a checked-in `.mcp.json`. Verify with `claude mcp list`.

### Cursor

Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project). The shape is the same as Claude Desktop:

```
{

  "mcpServers": {

    "insights": {

      "command": "/absolute/path/to/insights",

      "args": ["mcp"]

    }

  }

}
```

### Other stdio clients

Zed, Windsurf, and other MCP hosts use the same `command`/`args` shape — an absolute path to `insights` with `["mcp"]`. Consult the client's MCP documentation for where its server config lives. Add an explicit context flag or environment variable only when the process should not inherit the selected local context.

### HTTP transport

For a long-running or shared service, run the HTTP transport instead of stdio:

```
insights mcp --transport http --http 127.0.0.1:8090
```

Then point a Streamable-HTTP-capable MCP client at the address (`--http` defaults to `127.0.0.1:8090`). Serve it over HTTPS by supplying a certificate and key — `--http-tls` requires them (Insights does not generate a self-signed certificate), and there is no client-certificate verification:

```
insights mcp --transport http --http-tls --http-tls-cert cert.pem --http-tls-key key.pem
```

The HTTP transport applies **no authorization**: it listens on whatever `--http` names and answers any client that reaches it, so the NATS credentials remain the only data boundary. Keep it on the default loopback address (or behind your own authenticating reverse proxy); do not expose it directly on a network interface. It has no OAuth support, so managed remote clients that require it, such as Claude's connectors, cannot use it; the HTTP transport is for clients you run or control.

## Available tools

| Tool              | Description                                                                                                                   |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `info`            | Report the instance's capabilities: data retention, scrape interval, enrichment availability, and license. Orient here first. |
| `systems`         | List the reachable systems (ids, roles, serving nodes) for the `system` argument below.                                       |
| `query`           | Run a read-only DuckDB SQL query and return the rows as JSON.                                                                 |
| `explain`         | Plan a query with `EXPLAIN` (or `EXPLAIN ANALYZE`) without returning data.                                                    |
| `schemas`         | List the queryable schemas and their descriptions.                                                                            |
| `tables`          | List tables and views in a schema, with comments.                                                                             |
| `columns`         | List columns with their data types and comments.                                                                              |
| `macros`          | List the user-defined SQL macros and their signatures.                                                                        |
| `checks_list`     | List all checks grouped by category.                                                                                          |
| `checks_info`     | Show full metadata for one check.                                                                                             |
| `checks_findings` | Run a check over a time window and return the findings, flagged `disabled` when the system has turned the check off.          |

Every tool but `systems` requires the `system` argument, on a single-system deployment too; a call without it is refused with a validation error, and a call naming a system nothing serves returns `no responder for system "<id>"`.

Agents are guided to discover the schema (`schemas` → `tables` → `columns`) before querying, and to bound result sets with `LIMIT` or aggregation. Query results are capped by the serving node's `--db.query-max-rows` (100,000 rows by default) so a runaway query returns an error rather than an unbounded response.

## Security

* **Read-only.** Writes and DDL are rejected by the server, not the client, so the guarantee holds regardless of what an agent asks for.
* **Scoped by NATS.** The server can only read what its NATS identity is permitted to. Give it a credential scoped to the Insights API: request permission on `$INS.sys.<id>.db.>`, `$INS.sys.<id>.checks.>` and `$INS.sys.<id>.ops.info` for the systems it may read, plus `$INS.ping` for the `systems` tool, with replies allowed.
* **stdio credentials come from the environment** (flags or `INSIGHTS_*` env vars), never over the protocol.
* **HTTP is unauthenticated.** It defaults to loopback; keep it local or front it with your own auth.

## Troubleshooting

| Symptom                             | Fix                                                                                                                                                                                       |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tools don't appear in the client    | Confirm `command` is an **absolute** path, then fully restart the client.                                                                                                                 |
| "connect to nats" / timeout errors  | Verify the selected context with `nats context info`, then run `insights db query "SELECT 1"`. Check the context, server URL, and credentials.                                            |
| `systems` returns an empty list     | Nothing on this connection answers `$INS.ping`. Run `insights system list` with the same connection flags to confirm, and check the identity may publish `$INS.ping` and receive replies. |
| `no responder for system "<id>"`    | The id is misspelled or no node serving it is reachable. Call `systems` and use an id it returns.                                                                                         |
| A query returns an over-limit error | Add a `LIMIT` or aggregate — the result exceeded the 100,000-row cap.                                                                                                                     |
| Writes are rejected                 | Expected. The server is read-only; use `query` for `SELECT` statements only.                                                                                                              |

## Agent skills

MCP gives an agent tools; a skill gives it instructions. The **query-insights** skill teaches an agent that runs shell commands to answer questions with the `insights` CLI's query and schema-discovery subcommands: schema discovery, epoch scoping, aggregation contexts, and the check macros. It is published in the public [synadia-io/insights](https://github.com/synadia-io/insights) repository, which the web UI's info dialog links to.

In Claude Code, add the repository as a plugin marketplace and install the plugin:

```
/plugin marketplace add synadia-io/insights

/plugin install insights-skills@synadia-insights
```

Gemini CLI installs the same repository as an extension (`gemini extensions install synadia-io/insights`). For other agents that read the `SKILL.md` format, the repository README lists where to copy the skill folder.

The skill runs the CLI, so the agent's environment needs the same NATS connection as [Connecting to NATS](#connecting-to-nats) above, and `INSIGHTS_SYSTEM` (or `--system`) when more than one system is reachable.

## Next steps

* CLI reference → `insights mcp` — every flag and default.
* Search reference — the `hx` schema an agent queries.
* Checks reference — the checks behind `checks_findings`.
