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 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:

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

Using the Skill

Point the agent at the right NATS URL

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:

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 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 (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 — a NATS context, or an explicit server URL:

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

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

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

See the CLI reference for every flag, including the Streamable HTTP transport options.

Example Prompts

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