kenn-io--agentsview/docs/mcp.md

title, description

title	description
MCP Server	Connect assistant clients to your AgentsView session history with MCP

The agentsview mcp command runs a read-only Model Context Protocol server. MCP-capable assistant clients can use it to search prior sessions, inspect a session before opening it, fetch message slices, search raw content, and summarize token usage without leaving the assistant.

When To Use It

Use the MCP server when you want a coding assistant to answer questions such as:

• "Have I solved this error before?"
• "Find prior sessions in this repository about the deploy pipeline."
• "Open the relevant messages around this search hit."
• "Summarize recent token usage for this project."

The tools are read-only. They expose session history and usage data, but they do not mutate the archive or resync files directly.

Quick Start

For local desktop-style MCP clients, use stdio:

{
  "mcpServers": {
    "agentsview": {
      "command": "agentsview",
      "args": ["mcp"]
    }
  }
}

Restart or reload your MCP client after adding the server. Once connected, the client will see these tools:

Tool	Purpose
search_sessions	Full-text search across recorded sessions
list_sessions	List recent or filtered sessions
get_session_overview	Fetch metadata and a compact message preview
get_messages	Read paginated message bodies from one session
search_content	Substring, regex, semantic, or hybrid search over raw session text
get_usage_summary	Aggregate token and cost usage

search_content accepts a mode of substring (default), regex, semantic, or hybrid, plus a scope of top, all (default), or subordinate that is only valid with the semantic and hybrid modes. The semantic and hybrid modes need the opt-in semantic search index on the local SQLite archive; without it they return a "not available" error. In every mode, each match carries a conversation-unit citation: an ordinal_range of [start, end] ordinals around the match, plus subordinate, relationship, parent_session_id, and is_sidechain fields that flag hits from sidechain runs and subagent or fork sessions.

Daemon-Backed Reads

Local MCP mode talks to the AgentsView daemon. Each tool call resolves the local daemon and starts it when needed, so a long-lived MCP server keeps working even after the daemon exits due to idleness.

The MCP server does not open the local SQLite archive directly. This keeps MCP reads on the same daemon policy as the desktop app and avoids a long-running MCP process holding its own archive handle.

If you need to disable daemon auto-start for general CLI work with AGENTSVIEW_NO_DAEMON=1, do not use local MCP mode for that archive. Start the daemon yourself and connect with --server, or stop the MCP server.

Explicit Daemon URLs

Use --server when the daemon is already running or when you want to target a specific host:

{
  "mcpServers": {
    "agentsview": {
      "command": "agentsview",
      "args": ["mcp", "--server", "http://127.0.0.1:8080"]
    }
  }
}

If that daemon requires bearer auth, set AGENTSVIEW_SERVER_TOKEN in the MCP client environment or pass --server-token-file <path>:

{
  "mcpServers": {
    "agentsview": {
      "command": "agentsview",
      "args": [
        "mcp",
        "--server",
        "https://agents.example.com",
        "--server-token-file",
        "/Users/me/.agentsview/token"
      ]
    }
  }
}

The local config auth_token is not sent to explicit --server URLs. This prevents accidentally leaking a local daemon token to another host.

PostgreSQL-Backed MCP

If [pg] or AGENTSVIEW_PG_URL is configured, pass --pg to read from PostgreSQL directly:

{
  "mcpServers": {
    "agentsview": {
      "command": "agentsview",
      "args": ["mcp", "--pg"]
    }
  }
}

This is useful when the MCP server should read the shared PostgreSQL archive without relying on a local SQLite daemon.

You can also expose PostgreSQL-backed session history through a read-only PostgreSQL daemon and point MCP at it:

agentsview pg serve --port 8085

{
  "mcpServers": {
    "agentsview": {
      "command": "agentsview",
      "args": ["mcp", "--server", "http://127.0.0.1:8085"]
    }
  }
}

See PostgreSQL Sync for configuring pg push and pg serve.

StreamableHTTP Mode

stdio is the default and safest choice for local MCP clients. Use StreamableHTTP only when your client needs an HTTP MCP endpoint:

agentsview mcp --http 127.0.0.1:8085

Bare ports and :PORT values bind to loopback:

agentsview mcp --http 8085   # same as 127.0.0.1:8085
agentsview mcp --http :8085  # same as 127.0.0.1:8085

Non-loopback binds require an explicit opt-in:

agentsview mcp --http 0.0.0.0:8085 --http-allow-insecure

When the HTTP listener is reachable beyond loopback, AgentsView requires a configured bearer token and enforces Authorization: Bearer <token> on every request. If require_auth is enabled, loopback HTTP binds also require bearer auth so forwarded ports are not accidentally unauthenticated.

Security Notes

The MCP server can reveal prompts, assistant responses, tool output, file paths, project names, and usage totals. Treat it like access to your session archive.

• Prefer stdio for local assistant clients.
• Prefer loopback HTTP binds unless the endpoint is behind a trusted network or authenticating proxy.
• Use bearer tokens for any non-loopback or forwarded HTTP endpoint.
• Remember that MCP tools are read-only, but the data they expose may still be sensitive.

For every flag, see agentsview mcp in the CLI reference.