Reference
MCP reference
The seven tools the ai-insights MCP server offers your agent, with every parameter and default.
On this page
The server
ai-insights mcp is a Model Context Protocol server over standard input and output, named ai-insights. The plugin and the install script register it as:
{
"mcpServers": {
"ai-insights": {
"command": "npx",
"args": ["-y", "ai-insights", "mcp"]
}
}
}Every tool reads local files and none reaches the network; each declares openWorldHint: false. Your agent may show the tools with a prefix, such as mcp__ai-insights__ai_insights_scan. Tools return JSON as text. A failed call returns a short error saying what went wrong.
Typical flow
ai_insights_scanai_insights_reportfor the findingsai_insights_sessionswithmissingFacets: trueai_insights_excerptandai_insights_save_facetsfor each sessionai_insights_save_narrativeai_insights_render
The analyze-ai-usage skill walks your agent through exactly this. See Run the review.
ai_insights_scan
Start here. Finds and parses local transcripts (cached, so repeat calls are fast) and returns which agents were found, how far back history goes, headline numbers, the number of findings, and how many sessions already have labels, need one, or changed since they were labelled.
| Parameter | Type | Description |
|---|---|---|
since | string | Only history from a window like 30d, 12w, 6m or 1y, or an ISO date. |
harness | string | Only one agent: claude-code, codex, cursor, pi, opencode or gemini. |
maxSessions | integer, 1 to 50,000 | Read at most this many transcripts, newest first. Default 5,000. |
refresh | boolean | Re-parse every transcript, ignoring the cache. |
ai_insights_report
The computed report for the current scan as JSON, with no model involved. Ask only for the sections you need. Findings carry evidence with session ids you can pass to ai_insights_excerpt, most severe first. Read-only.
| Parameter | Type | Description |
|---|---|---|
sections | array | Any of summary, coverage, activity, usage, findings, facets, narrative, recap. Default summary and findings. |
detail | digest or full | Shape of the facets, activity, usage and recap sections. The digest (default) holds top-N lists and weekly series, about 3,000 characters for facets, activity and usage together; full holds every list and the daily series. |
findingsLimit | integer, 1 to 100 | Most findings to return. Default 20. |
evidenceLimit | integer, 0 to 20 | Evidence items per finding. Default 5. |
weeks | integer, 1 to 60 | Digest only: most recent weeks in weekly series. Default 8. |
days | integer, 1 to 400 | Full only: most recent days kept in daily series. Default 60. |
ai_insights_sessions
Sessions from the current scan with counts, whether a label (facet) is saved, whether the session is still running, whether another agent drove it, and its first prompt, redacted and cut to 160 characters. Paginate with offset; the order is stable while the set is unchanged. Read-only.
| Parameter | Type | Description |
|---|---|---|
harness | string | Only one agent: claude-code, codex, cursor, pi, opencode or gemini. |
missingFacets | boolean | Only sessions that need a label: none saved yet, or one that is stale (judged while running, or the session has grown since). |
includeStale | boolean | With missingFacets: also offer sessions whose label is stale. Default true. |
strategy | spread or newest | spread: proportional across agents and time, at least one per agent. newest: newest first. Default spread with missingFacets, else newest. |
minUserMessages | integer, 0 to 10,000 | Skip sessions with fewer prompts than this, counting yours and other agents'. Default 2 with missingFacets, else 0. |
includeLive | boolean | With missingFacets: include sessions still running. Default false. |
includeSlashCommandOnly | boolean | With missingFacets: include sessions that were only slash commands. Default false. |
limit | integer, 1 to 100 | Page size. Default 20. |
offset | integer | Skip this many matching sessions. |
With missingFacets, the response also says how many sessions it skipped and why.
ai_insights_excerpt
A redacted, truncated slice of one session's transcript plus its numbers. Turns are labelled user (you), agent (a message another agent or automation sent), assistant and tool. Your prompts, agent messages, tool errors and the final reply are kept first; routine tool output is cut first. The text is read from the transcript on demand and not stored. Read-only.
| Parameter | Type | Description |
|---|---|---|
sessionId | string, required | A session id from ai_insights_sessions or a finding's evidence. |
harness | string | The session's agent, when an id could be ambiguous: claude-code, codex, cursor, pi, opencode or gemini. |
maxTurns | integer, 1 to 80 | Turns to sample. Default 24. |
maxCharsPerTurn | integer, 100 to 4,000 | Characters per turn. Default 600. |
maxChars | integer, 500 to 40,000 | Size budget for the whole response. Default 4,000; when maxCharsPerTurn is given, maxTurns × maxCharsPerTurn if that is larger. |
around | ISO timestamp | Keep the turns closest to this moment, for example a finding's evidence timestamp. |
A trimmed response from a synthetic session:
{
"session": { "sessionId": "00000011-2222-4333-8444-555555555555", "harness": "claude-code",
"project": "work/acme-api", "durationMinutes": 11, "userMessages": 3,
"toolCalls": 3, "toolErrors": 1, "hasFacet": false, … },
"turns": [
{ "role": "user", "text": "run the tests and fix what fails", … },
{ "role": "tool", "toolName": "Bash", "text": "pnpm test", … },
{ "role": "tool", "toolName": "Bash", "isError": true, "text": "pnpm test → 1 failed", … },
{ "role": "assistant", "text": "Done.", … },
…
]
}ai_insights_save_facets
Saves your agent's judgement of one or more sessions, one facet per session, from the fixed lists in Session labels. Valid facets are saved even if others in the batch are rejected; each rejection says what to fix. Saving again overwrites. The response lists what was saved and rejected, how many sessions still need a label, and how many were held back.
| Parameter | Type | Description |
|---|---|---|
facets | array of 1 to 50 objects | Each with sessionId, harness, underlyingGoal, goalCategories, sessionType, outcome, helpfulness, satisfaction, primarySuccess, frictions, frictionDetail and summary; drivenBy is optional. |
ai_insights_save_narrative
Saves the narrative for the report. Saving again replaces it. A suggestion whose instructionText holds an angle-bracket placeholder or an ellipsis is rejected, because that text is pasted into an instructions file as is.
| Parameter | Type | Description |
|---|---|---|
narrative | object | headline (2 or 3 sentences); workAreas (name, sessions, description; at most 12); interactionStyle; wins (title, description); frictions (title, description, examples); suggestions (type, title, action, and optionally instructionText, an http or https url, and findingId; at most 15); horizon (title, description, starterPrompt; at most 8). |
ai_insights_render
Builds the report from the current scan plus saved labels and narrative, writes the HTML file, and returns its path and file:// URL, the session and label counts, the headline numbers, and the top three findings with their suggested actions. It takes no parameters and works before the agent review too, with the deterministic sections only.
{
"path": "~/.ai-insights/reports/report.html",
"url": "file://~/.ai-insights/reports/report.html",
"sessions": 12,
"sessionsWithFacets": 0,
"hasNarrative": false,
"headline": { "activeHours": 2.2, "agentHours": 2.2, "activeDays": 12,
"cost": "about $1.13 at API list prices", … },
"topFindings": [ { "title": "You keep telling the agent: \"run the tests and fix what fails\"",
"severity": "medium", … } ]
}