Skip to content

Let AI agents query Argus data via a local MCP endpoint (#299) - #329

Open
mando wants to merge 1 commit into
mainfrom
mando-mcp-endpoint-for-agent-queries
Open

Let AI agents query Argus data via a local MCP endpoint (#299)#329
mando wants to merge 1 commit into
mainfrom
mando-mcp-endpoint-for-agent-queries

Conversation

@mando

@mando mando commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Fixes: #299

Why

Argus indexes local agent sessions, but agents can't see any of it. This lets AI agents on the user's machine (Claude Code, Codex, Gemini CLI) query Argus directly — "what did I work on last week", usage/cost, task outcomes — so agents can use the user's own work history as context.

How

A local MCP server, served as stateless streamable HTTP on the existing serve app at POST /mcp (reachable at http://127.0.0.1:4242/mcp, including through the desktop app's front-door proxy, which is a dumb TCP relay so no proxy changes were needed). No stdio subcommand: the desktop sidecar binary lives at an unstable bundle path, and all three clients speak streamable HTTP.

  • Six read-only tools (search_sessions, get_session, get_session_transcript, usage_summary, tool_usage, health_summary) reuse the exact readers startServer assembles for the web API. Zero new store queries, so agents and the dashboard can never disagree.
  • Privacy gates resolve per request, so Settings toggles apply live with no restart: agentAccess.enabled (default on; off makes /mcp 404) and agentAccess.includeTranscripts (default off; also requires retainText). The transcript tool stays listed while gated, with a description that tells the agent how to ask the user to enable it, and refuses with a tool-level error if called anyway.
  • Security: mounted among the read routes (survives readOnly mode), guarded by the existing rejectUnsafeHost (the MCP spec's DNS-rebinding requirement), no x-argus-app CSRF requirement (MCP clients can't send one, and every tool is read-only), no auth token (loopback bind stays the boundary, consistent with the rest of the API).
  • Transport details: fresh McpServer + StreamableHTTPTransport (@hono/mcp) per request, sessionIdGenerator: undefined (no session state), enableJsonResponse: true (plain JSON answers, easy to smoke-test), GET /mcp → 405 (no standalone notification stream; this server never initiates messages).

Settings surface

New "Agent access" category in Settings with the two toggles. The web Settings screen renders from describeSettings(), so no web code changes were required; the transcript toggle is gated on the enabled toggle via the existing activeWhen mechanism.

Docs

  • New docs/connect-your-agent.md (under "Using Argus"): per-client connect snippets, the tool table, the transcript toggle, and the plain-HTTP/CLI fallback.
  • New docs/internals/agent-access.md: transport decision, tool-to-reader map, threat model.
  • Updated docs/privacy.md (agent access section) and docs/settings-reference.md (both new settings).

Verification

  • bun test (720 pass, including 17 new test/mcp.test.ts tests driving createApp with raw JSON-RPC POSTs: initialize, tools/list, tools/call per tool, filter pass-through, sentinel stripping, limit clamping, gating, non-loopback Host 403, GET 405, read-only mode) and bun run typecheck.
  • Compile smoke: bun run build:compile, ran dist/argus serve, POSTed initialize + tools/list + tools/call (usage_summary, search_sessions) to /mcp; confirmed transcripts-off refusal, disabled 404, evil-Host 403, GET 405.
  • Not yet done (needs a live agent): claude mcp add --transport http argus http://127.0.0.1:4242/mcp end-to-end, and Claude Cowork's sandboxed VM may not reach host loopback (docs note Claude Code/Codex/Gemini CLI first).

Serve a stateless streamable-HTTP MCP server at POST /mcp, mounted among
the read routes in createApp behind the existing rejectUnsafeHost guard.
Six read-only tools (search_sessions, get_session, get_session_transcript,
usage_summary, tool_usage, health_summary) reuse the exact readers
startServer assembles for the web API, so agents and the dashboard never
disagree.

Two new settings resolve per request so Settings toggles apply live:
agentAccess.enabled (default on; off makes /mcp 404) and
agentAccess.includeTranscripts (default off; gates transcript text, the
genuinely new exposure). Both surface in a new Agent access category in
Settings.

Docs: new Connect Your Agent page, internals/agent-access.md, and
updates to privacy.md and settings-reference.md.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Let AI agents query Argus data via a local MCP endpoint

1 participant