AI Agents

You don't need the web UI to work with Insights. Anything the UI shows (server stats, JetStream assets, accounts, check findings) is reachable as DuckDB SQL through the insights db query subcommand, which talks to the running server over NATS. That makes it a natural fit for shell scripts and AI coding agents.

There are two ways to connect an agent: the query-insights skill, which teaches an agent that runs shell commands to use the CLI, and the built-in MCP server, which gives an MCP-capable client native tools.

Install the Skill

The query-insights skill is published in the public synadia-io/insights repository. The web UI's info dialog links to it. It covers schema discovery, epoch scoping, aggregation contexts, and the check macros.

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

In Gemini CLI, install the repository as an extension:

gemini extensions install synadia-io/insights

For Codex, Cursor, and other agents that read the SKILL.md format, copy the skill folder into the tool's skills directory; the repository README lists the locations.

Using the Skill

Point the agent at the right NATS URL and system

The skill runs insights CLI commands 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 the CLI at the same external NATS cluster the server uses.

The cleanest setup is to save the connection as a NATS context and export INSIGHTS_NATS_CONTEXT=<name> once. Interactive shells and AI agents then both pick it up automatically. If the connection reaches more than one system, also export INSIGHTS_SYSTEM=<id>; without it, a query stops and lists the reachable systems.

Claude Code

Ask about your deployment and Claude loads the skill when the question calls for it, or invoke it directly:

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

Claude runs insights queries, reads the results, and answers.

Gemini CLI

The extension loads the skill as session context, so ask insights-related questions directly in a session.

MCP Server

Insights also ships a Model Context Protocol (MCP) server as the built-in insights mcp subcommand. Where the skill teaches an agent to run CLI commands, 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; the NATS credentials it runs with are the data boundary.

It exposes eleven read-only tools:

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

One server serves every reachable system. Every tool but systems requires a system argument naming the system that call addresses, on a single-system deployment too. The systems tool tells the agent how to resolve it: one result is the answer, and several means asking you which one you mean. checks_findings marks findings from a check the system has disabled, so the agent doesn't present them as open issues.

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. Credentials come from the environment (a NATS context, flags, or INSIGHTS_* variables), never over the protocol.
Streamable HTTP (--transport http): a long-running service, listening on 127.0.0.1:8090 by default. Add --http-tls with --http-tls-cert and --http-tls-key to serve HTTPS.

The HTTP transport has no authentication

The HTTP transport answers any client that reaches its listen address. Keep it on loopback or behind your own authenticating proxy. It has no OAuth support, so managed remote clients that require OAuth can't connect to it.

Point a client at a running Insights node with the same connection flags as the other client subcommands: 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

Give the MCP server a NATS identity 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. See the CLI reference for every flag.

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 check 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?