Skip to content
DocsMCP reference

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:

MCP server config
{
  "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

  1. ai_insights_scan
  2. ai_insights_report for the findings
  3. ai_insights_sessions with missingFacets: true
  4. ai_insights_excerpt and ai_insights_save_facets for each session
  5. ai_insights_save_narrative
  6. ai_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.

ai_insights_scan parameters
ParameterTypeDescription
sincestringOnly history from a window like 30d, 12w, 6m or 1y, or an ISO date.
harnessstringOnly one agent: claude-code, codex, cursor, pi, opencode or gemini.
maxSessionsinteger, 1 to 50,000Read at most this many transcripts, newest first. Default 5,000.
refreshbooleanRe-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.

ai_insights_report parameters
ParameterTypeDescription
sectionsarrayAny of summary, coverage, activity, usage, findings, facets, narrative, recap. Default summary and findings.
detaildigest or fullShape 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.
findingsLimitinteger, 1 to 100Most findings to return. Default 20.
evidenceLimitinteger, 0 to 20Evidence items per finding. Default 5.
weeksinteger, 1 to 60Digest only: most recent weeks in weekly series. Default 8.
daysinteger, 1 to 400Full 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.

ai_insights_sessions parameters
ParameterTypeDescription
harnessstringOnly one agent: claude-code, codex, cursor, pi, opencode or gemini.
missingFacetsbooleanOnly sessions that need a label: none saved yet, or one that is stale (judged while running, or the session has grown since).
includeStalebooleanWith missingFacets: also offer sessions whose label is stale. Default true.
strategyspread or newestspread: proportional across agents and time, at least one per agent. newest: newest first. Default spread with missingFacets, else newest.
minUserMessagesinteger, 0 to 10,000Skip sessions with fewer prompts than this, counting yours and other agents'. Default 2 with missingFacets, else 0.
includeLivebooleanWith missingFacets: include sessions still running. Default false.
includeSlashCommandOnlybooleanWith missingFacets: include sessions that were only slash commands. Default false.
limitinteger, 1 to 100Page size. Default 20.
offsetintegerSkip 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.

ai_insights_excerpt parameters
ParameterTypeDescription
sessionIdstring, requiredA session id from ai_insights_sessions or a finding's evidence.
harnessstringThe session's agent, when an id could be ambiguous: claude-code, codex, cursor, pi, opencode or gemini.
maxTurnsinteger, 1 to 80Turns to sample. Default 24.
maxCharsPerTurninteger, 100 to 4,000Characters per turn. Default 600.
maxCharsinteger, 500 to 40,000Size budget for the whole response. Default 4,000; when maxCharsPerTurn is given, maxTurns × maxCharsPerTurn if that is larger.
aroundISO timestampKeep the turns closest to this moment, for example a finding's evidence timestamp.

A trimmed response from a synthetic session:

Response, from a synthetic session; trimmed
{
  "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.

ai_insights_save_facets parameters
ParameterTypeDescription
facetsarray of 1 to 50 objectsEach 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.

ai_insights_save_narrative parameters
ParameterTypeDescription
narrativeobjectheadline (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.

Response, from a synthetic history; home folder shortened to ~; trimmed
{
  "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", … } ]
}

Something wrong or missing? Edit this page on GitHub or open an issue.