Skip to main content

Connecting AI agents with MCP

Insights ships a Model Context Protocol (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.
  • 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 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.

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:

FlagEnvDescription
--contextINSIGHTS_NATS_CONTEXTOverride the currently selected NATS CLI context with a named context.
--serverINSIGHTS_NATS_SERVERAn explicit NATS server URL, e.g. nats://insights.example.com:4222.
--credsINSIGHTS_NATS_CREDSPath 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​

ToolDescription
infoReport the instance's capabilities: data retention, scrape interval, enrichment availability, and license. Orient here first.
systemsList the reachable systems (ids, roles, serving nodes) for the system argument below.
queryRun a read-only DuckDB SQL query and return the rows as JSON.
explainPlan a query with EXPLAIN (or EXPLAIN ANALYZE) without returning data.
schemasList the queryable schemas and their descriptions.
tablesList tables and views in a schema, with comments.
columnsList columns with their data types and comments.
macrosList the user-defined SQL macros and their signatures.
checks_listList all checks grouped by category.
checks_infoShow full metadata for one check.
checks_findingsRun 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​

SymptomFix
Tools don't appear in the clientConfirm command is an absolute path, then fully restart the client.
"connect to nats" / timeout errorsVerify 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 listNothing 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 errorAdd a LIMIT or aggregate — the result exceeded the 100,000-row cap.
Writes are rejectedExpected. 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 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 above, and INSIGHTS_SYSTEM (or --system) when more than one system is reachable.

Next steps​