# AI Agents

Insights is designed to be queried headlessly. Anything you can see in the web UI — server stats, JetStream assets, accounts, audit findings — is reachable as DuckDB SQL via the [`insights query`](../reference/cli.md#insights-query) subcommand, which talks to the running server over NATS. That makes it a natural fit for both shell automation and AI coding agents.

To make agents productive without hand-rolling prompts, every running Insights server publishes a downloadable **query-insights skill** packaged for the major AI coding tools.

## Download

Open the running Insights web UI, click the **info dialog** (top-right), choose your target format, and download the bundle.

| Target format | Bundle contents                            | Install location    |
| ------------- | ------------------------------------------ | ------------------- |
| Claude Skill  | `query-insights/SKILL.md`                  | `~/.claude/skills/` |
| AGENTS.md     | `AGENTS.md` (Codex / generic agent format) | Project root        |
| GEMINI.md     | `GEMINI.md`                                | Project root        |
| Cursor Rule   | `.cursor/rules/query-insights.mdc`         | Project root        |

On Windows, `~` resolves to `%USERPROFILE%` (typically `C:\Users\<you>`); the Claude skill goes in `%USERPROFILE%\.claude\skills\`. The other three live alongside the project, so they're platform-independent.

The endpoint is `GET /skill/query-insights/{agent}/download` where `{agent}` is `claude`, `codex`, `gemini`, or `cursor`. You can fetch it from the CLI as well:

```sh
curl -OJ https://insights.example.com/skill/query-insights/claude/download
unzip query-insights-claude.zip -d ~/.claude/skills/
```

## Using the Skill

The skill emits `insights query` calls that reach the running server over NATS, so the agent's environment must point at the correct URL for your [deployment topology](deployment.md):

- **Embedded sink (default)** — Insights runs an internal NATS server. By default it binds to `127.0.0.1` on a random port, printed to the server logs at startup; you can read it from there and pass it to the agent. For a stable URL across restarts, pin it with `--sink.host` / `--sink.port` (for example `--sink.port=4222`) and use that as the `--server` value.
- **External sink (`--sink.embed=false`)** — point `insights query` at the same external NATS cluster the server uses (`--server` on the server side).

The cleanest setup is to save the connection as a [NATS context](https://docs.nats.io/using-nats/nats-tools/nats_cli#nats-contexts) and export `INSIGHTS_NATS_CONTEXT=<name>` once — both interactive shells and AI agents then pick it up automatically.

### Claude Code

After extracting into `~/.claude/skills/`, invoke it with:

```
/query-insights how many connections per cluster right now?
```

Claude will emit `insights query "<SQL>"` calls, read the CSV/JSON results, and answer.

### Codex / Gemini

Drop `AGENTS.md` or `GEMINI.md` at the project root. The agent picks it up automatically as ambient context whenever you ask insights-related questions in that workspace.

### Cursor

Place `.cursor/rules/query-insights.mdc` in the project. The rule is set to `alwaysApply: false`, so it only kicks in when you explicitly mention insights or the `query-insights` skill in a chat.

## MCP Server

Insights also ships a first-class [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server as the built-in `insights mcp` subcommand. Where the skill teaches an agent to emit `insights query` calls, the MCP server lets an MCP-capable client — Claude Desktop, Claude Code, Cursor, and others — query the running instance directly through native tools.

The server is **read-only by construction**. It owns no database of its own: it's a thin gateway that forwards each tool call to the same `$INS.*` NATS API the CLI uses, with the read-only guard enforced on the server side. Pointing an agent at a production instance is safe.

It exposes ten read-only tools over the database and checks endpoints:

| Endpoints | Tools                                                                |
| --------- | -------------------------------------------------------------------- |
| Database  | `query`, `explain`, `schemas`, `tables`, `columns`, `macros`, `info` |
| Checks    | `checks_list`, `checks_info`, `checks_findings`                      |

The server speaks two transports:

- **stdio (default)** — the client launches `insights mcp` as a subprocess and talks to it over stdin/stdout. This is the right choice for local desktop clients.
- **Streamable HTTP** — a long-running service on a port, for networked or shared clients.

Point a client at a running Insights node with the same connection flags as [`insights query`](../reference/cli.md#insights-query) — a NATS context, or an explicit server URL:

```sh
insights mcp --server nats://node:4222
```

Most clients are wired up by registering that command once. With Claude Code, for example:

```sh
claude mcp add insights -- insights mcp --context my-nats-context
```

See the [CLI reference](../reference/cli.md#insights-mcp) for every flag, including the Streamable HTTP transport options.

## Example Prompts

1. What's the message throughput per cluster right now?
2. Show me the top 10 connections by bytes sent in the last hour.
3. Which streams haven't received a message in the past 24 hours?
4. List all critical audit findings grouped by entity type.
5. What accounts are using the most JetStream storage?
6. Find consumers with growing pending counts over the last 30 minutes.
7. How has memory usage trended across servers in the last hour?
8. Which servers have the most subscriptions per connection?
9. Show me streams where the leader changed in the past day.
10. What's the slowest-draining consumer per account?